Overview

Discover Boating users who want to export leads out of Aimbase, can do so using the Remote Lead Export API. This API will return lead information for the specified NMMA ID incrementally, or in a specified time frame up to 7 days in the past. 

The data returned will be in FSDS XML format. If a call is made without any day or date parameters, it will be treated as an incremental call and retrieve leads since the last call. If a call does include the day or date parameter, it will return for that entire time frame. 

Authentication Overview

Public key and private key is required for authentication to retrieve data from the remote lead export service. Each value is unique per client. 

Possible Response Codes

• 400 (Bad Request). This response indicates that the data was not sent in the correct format, or had missing information.
• 401 (Unauthorized). This response indicates that authorization was not successful. The response body will contain an error message.
• 500 (Internal Server Error). An unknown error occurred.

Post Information

Endpoint 

GET https://apimap.aimbase.com/api/IncrementalLeadExport/{NMMA-ID}

Authentication Header format used to verify the source of API call

Authenticate: Bearer timestamp="{timestamp}",nonce="{nonce}",signature="{signature}",publickey="{publickey}"

Authentication Data Schema

Generating Header

Include a reference to the CryptoJS javascript library. 

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>

Determine the timestamp value for the current time.

var timestamp = Math.floor(Date.now() / 1000);

Randomly generate an alpha-numeric string with the exact length of 50 characters and use it as the nonce value.

var chars =   "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
var noncelength = 50;
var nonce = "";
for (var i = noncelength; i > 0; --i) nonce += chars[Math.floor(Math.random() * chars.length)];

Concatenate the timestamp, nonce, and publickey values and then encode the result using the HMAC algorithm, using the private key and SHA256 digest to generate the signature.

var publicKey = "{enter publickey}";
var privateKey = "{enter privatekey}";
var message = timestamp + nonce + publickey;
var signature = CryptoJS.HmacSHA256(message, privatekey);

Fill in the timestamp, nonce, signature, and publickey values in the header.

Authenticate: Bearer timestamp="{timestamp}",nonce="{nonce}",signature="{signature}",publickey="{publickey}"

When all steps are completed, it should look like this:

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>
<script>
    var timestamp = Math.floor(Date.now() / 1000);
    var chars = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
    var noncelength = 50;
    var nonce = "";
    for (var i = noncelength; i > 0; --i) nonce += chars[Math.floor(Math.random() * chars.length)];

    var publicKey = "{enter publickey}";
    var privateKey = "{enter privatekey}";
    var message = timestamp + nonce + publicKey;
    var signature = CryptoJS.HmacSHA256(message, privateKey);

    var headerValue =    'Authenticate: Bearer timestamp="' + timestamp +
      '",nonce="' + nonce +
      '",signature="' + signature +
      '",publickey="' + publicKey + '"';
</script>

Verifying Header

1. Use the publicKey to look up the private key for the client.
2. Concatenate the timestamp, nonce, and publickey values.   
3. Encode the result using the HMAC algorithm using the private key and SHA256 digest.
4. To verify the correct private key was used, verify that the result of number 2 matches the signature.
5. (Optional) To prevent replay attacks, developer can cache the nonce of the request and reject any requests with nonces already seen. 
6. (Optional) Can reject requests that have a timestamp of too far in the past. This time frame should match the nonce caching time length if nonce caching is being done.

Endpoint Parameters

NMMA ID: Leads will be retrieved based on the NMMA ID parameter that is passed. This parameter is required to pull leads. Example:

GET https://apimap.aimbase.com/api/IncrementalLeadExport/{NMMA-ID}

Days/Date: If this parameter is passed, leads will be retrieved for the specified time frame. If this parameter is not passed, the call will be incremental, only retrieving leads since the last call. The max number of days you can request is 7. The furthest back in date you can go is 7 days in the past. Examples:

GET https://apimap.aimbase.com/api/IncrementalLeadExport/{NMMA-ID}?Days=7

GET https://apimap.aimbase.com/api/IncrementalLeadExport/{NMMA-ID}?Date=03/03/2020

Example Post

GET https://apimap.aimbase.com/api/IncrementalLeadExport/{NMMA-ID}
Authenticate: Bearer timestamp="{timestamp}",nonce="{nonce}",signature="{signature}",publickey="{publickey}"

Success Response

<ProcessSalesLead xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:schemaLocation="http://www.starstandards.org/STAR" xmlns="http://www.starstandards.org/STAR">
    <ApplicationArea>
        <Sender>
            <Component>OUTPUT.LeadData.DBLSRemoteLeadExport</Component>
            <Task>ProcessSalesLead</Task>
            <CreatorNameCode>NMMA</CreatorNameCode>
            <SenderNameCode>CB</SenderNameCode>
            <SystemVersion>1.0</SystemVersion>
        </Sender>
        <Destination>
            <DestinationNameCode>{NMMA ID}</DestinationNameCode>
        </Destination>
        <CreationDateTime>2020-06-16T16:51:06.3788239Z</CreationDateTime>
    </ApplicationArea>
    <DataArea>
<SalesLead>
            <Header>
                <DocumentDateTime>2020-06-12T11:53:02.633Z</DocumentDateTime>
                <DocumentId>13236</DocumentId>
                <LeadSource>DiscoverBoating.com</LeadSource>
                <CustomerComments>
                    <![CDATA[ Buying Horizon: I don't know ]]>
                </CustomerComments>
                <IndividualProspect>
                    <PersonName>
                        <GivenName>
                            <![CDATA[ John ]]>
                        </GivenName>
                        <FamilyName>
                            <![CDATA[ Doe ]]>
                        </FamilyName>
                    </PersonName>
                    <MarketingMailInd>1</MarketingMailInd>
                    <Address>
                        <AddressLine>
                            <![CDATA[ 123 John Doe Road ]]>
                        </AddressLine>
                        <AddressLine>
                            <![CDATA[ Apt 123 ]]>
                        </AddressLine>
                        <City>
                            <![CDATA[ San Diego ]]>
                        </City>
                        <StateOrProvince>
                            <![CDATA[ CA ]]>
                        </StateOrProvince>
                        <Country>
                            <![CDATA[ US ]]>
                        </Country>
                        <PostalCode>
                            <![CDATA[ 92108 ]]>
                        </PostalCode>
                    </Address>
                    <Contact>
                        <Telephone desc="Evening Phone">
                            <![CDATA[ 555-555-5555 ]]>
                        </Telephone>
                        <EmailAddress desc="Home">
                            <![CDATA[ johndoe@gmail.com ]]>
                        </EmailAddress>
                    </Contact>
                </IndividualProspect>
            </Header>
            <Detail>
                <LeadStatus>Lead</LeadStatus>
                <LeadIndustryType>Boats</LeadIndustryType>
                <LeadRequestType>
                    <![CDATA[ Contact Dealer and Manufacturers Form ]]>
                </LeadRequestType>
                <SalesVehicle>
                    <ModelDescription>
                        <![CDATA[ Bowrider ]]>
                    </ModelDescription>
                    <BoatingActivities>
                        <![CDATA[ Day Cruising ]]>
                    </BoatingActivities>
                    <BoatOwnershipStatus>
                        <![CDATA[ Yes ]]>
                    </BoatOwnershipStatus>
                </SalesVehicle>
            </Detail>
        </SalesLead>
    </DataArea>
</ProcessSalesLead>