Lead API

Overview

Our Lead API gives third-party websites a way to send lead data to Aimbase utilizing HTTP POST.

Possible Response Codes

  • 201 (Created).This response indicates that the lead data was successfully parsed. The body of the response will contain the success or failure status for each lead that was submitted in the request. NOTE: The response record details for each lead will be returned in the order that they were submitted.
  • 400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request.
  • 500 (Internal Server Error). An unknown error occurred during the import

Authentication

The Lead API requires authentication. The HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token. 

Authenticate message header example:

Authenticate: Avala-Api {username}:{token}

Post Information

HTTP Endpoint 

https://{baseurl}/Marketing/api/Lead?manufacturer={manufacturerCode}


Lead Data Schema 

Field Name  Required  Format  Description 
LeadSourceName  X  Max Length: 50  A valid Lead Source’s Name in the system.  
LeadTypeName  X  Max Length: 50  A valid Lead Type’s Name in the system. 
LeadCategoryName  X  Max Length: 50  A valid Lead Category’s Name in the system. 
LeadCampaignName    Max Length: 50  A valid Lead Campaign’s Name in the system. 
Brands  X  Max Length: 100  A comma delimited string list of Brand Code values. If no brand value is provided, the lead will be assigned to all of the manufacturer’s brands. 
EventName    Max Length: 50  Free text field. 
LeadDate    YYYY-MM-dd ±hh:mm If no lead date is given, the lead’s lead date will be the date and time the lead was submitted to the API. 

Optionally can provide DateTime Offset. Aimbase will convert to Central Time. DateTime Offset passed should account for daylight savings time. Format: YYYY-MM-dd ±hh:mm  
FirstName    Max Length: 50   
LastName  X  Max Length: 50   
Address1    Max Length: 64   
Address2    Max Length: 64   
City    Max Length: 64   
State    Max Length: 3  State or Province code. 
PostalCode    Max Length: 10   
Zip4    Max Length: 4   
CompanyName    Max Length: 50   
CompanyTitle    Max Length: 50   
CompanyExternalId    Max Length: 20   
CompanyUid    Guid   
County    Max Length: 25   
Country    Max Length: 50  Country name. 
HomePhone    Max Length: 20 

 

WorkPhone    Max Length: 20   
MobilePhone    Max Length: 20   
Fax    Max Length: 20   
Email    Max Length: 80   
CountryCode  X  Max Length: 2   Aimbase accepts the ISO two-letter country codes
DealerIds    Max Length: 100  A comma delimited string list of Aimbase Dealer Id values that the lead should be assigned to. 
Dealers      A list of Dealer data values for existing dealers in Aimbase that the lead should be assigned to. The dealer data schema is in a table below. 
ProductIds    Max Length: 100  A comma delimited string list of Aimbase Product Id values that the lead should be assigned to. 
Products      A list of Product data values for existing products in Aimbase that the lead should be assigned to. The product data schema is in a table below. 
EmailRefused    Max Length: 5  True/False. Notes if the lead should be opted out of email communications. If no value is given, the lead is not opted out of email communications. 
Customs      A list of custom fields and their values. If the field name is defined as a custom field in the application, the value will be set for that field. If the field name is not defined as a custom field in the application, the field name and value will be added to the lead’s generic metadata values. 
ProspectExternalId    Max Length: 20   
ExternalId    Max Length: 50   The unique identifier for a lead that matches a unique identifier in an external system.  Can be referenced in additional APIs to identify a lead back to an external system.
LeadApiIdentifier    Max Length: 100  Unique value used during an API messaging even to relate a request with a response. This value is not saved with the lead.
SMSOptIn

Boolean If collecting SMS opt in information, this field should be used to collect the information.
IsCommunicationOptIn  X  Boolean  A flag for identifying if the lead is opted in for future communications. 
CommunicationOptInIpAddress    Max Length: 20  The IP Address of the lead when it was submitted. This field is required if IsCommunicationOptIn is true. 
CommunicationOptInDate    yyyy-MM-dd  The date the lead opted in for communications. This field is required if IsCommunicationOptIn is true. 
CommunicationOptInSource    Max Length: 50  The source of the lead that was opted in for communications. This field is required if  IsCommunicationOptIn is true. 
SendAutoresponder    Boolean   The flag for opting in or out of sending the Lead an Autoresponder notification after submitting a lead.  
SendLead    Y or N An override for if the assigned dealer or contact should be notified of the lead when it is created. 
SendNurture    Boolean  An override for if the assigned dealer or contact should be notified of the lead when it is created. Default to TRUE if empty. 
ScoreProspect    Boolean  An override for if the lead’s score should be added to the prospect’s score. Default to TRUE if empty. 
UserUid    Guid  The web session user unique identifier. 
SessionUid    Guid  The web session unique identifier. 
ListCodes    Max Length:  Specifies the list codes that the lead should filter into, must match the list codes in Aimbase. 
LeadReroute
Boolean An override for Aimbase lead rerouting logic if it is on for your install. When sent in as true, it allows the lead to reroute even for a manually selected dealer. 

Custom Data Schema

Field Name  Required  Format  Description 
FieldName  X  Max Length: 50   
FieldValue  X  Max Length: 2048   

Dealer Data Schema

Field Name  Required  Format  Description 
DealerNumber  X  Max Length: 20  The main part of the unique identifier for dealers. 
DealerLocation    Max Length: 10  The second part or sub number of the unique identifier for dealers. 
DealerName    Max Length: 80  The name of the dealership. 

Product Data Schema

Field Name  Required  Format  Description 
ProductCode  X  Max Length: 50  The product code. 
ProductName    Max Length: 100  The name of the product. 
ProductModelYear    Number, 1000-9999  The model year of the product. 

XML Example Post

POST: https://{baseurl}/marketing/api/lead?manufacturer={manufacturerCode}
Host: {baseurl}
Authenticate: Avala-Api {username}:{token}
Content-Type: application/xml
 
<?xml version="1.0"?> 
<Leads xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
<Lead> 
    <LeadApiIdentifier>44b07d7b-1677-4bb8-84c0-9846b9d5bec1</LeadApiIdentifier> 
    <LeadSourceName>Website</LeadSourceName> 
    <LeadTypeName>Request Brochure</LeadTypeName> 
    <LeadCategoryName>Referral Traffic</LeadCategoryName> 
    <LeadDate xsi:nil="true" /> 
    <FirstName>Allen</FirstName> 
    <LastName>Hall</LastName> 
    <Address1>123 Main Street</Address1> 
    <City>Saint Louis</City> 
    <State>MO</State> 
    <PostalCode>63105</PostalCode> 
    <Email>ahall@avalamarketing.com</Email> 
    <CountryCode>US</CountryCode> 
    <Dealers> 
        <Dealer> 
            <DealerNumber>100</DealerNumber> 
            <DealerLocation>1</DealerLocation> 
            <DealerName>Bob's Boats</DealerName> 
        </Dealer> 
    </Dealers> 
    <Products> 
        <Product> 
            <ProductCode>100</ProductCode> 
            <ProductName>Fast Boat</ProductName> 
            <ProductModelYear>2014</ProductModelYear> 
        </Product> 
    </Products> 
    <Customs> 
        <Custom> 
            <FieldName>BuyTimeFrame</FieldName> 
            <FieldValue>1-3 months</FieldValue> 
        </Custom> 
        <Custom> 
            <FieldName>Financing</FieldName> 
            <FieldValue>Yes</FieldValue> 
        </Custom> 
    </Customs> 
    <IsCommunicationOptIn xsi:nil="true"/> 
    <CommunicationOptInDate xsi:nil="true"/> 
    </Lead> 
</Leads>



JSON Example Post


POST: https://{baseurl}/marketing/api/lead/?manufacturer={manufacturerCode}
Host: {baseurl}
Authenticate: Avala-Api {username}:{token}
Content-Type: application/json
 
[{ 
    "LeadApiIdentifier" : "99c932d0-310c-497b-8e45-cad143231092", 
    "Brands" : null, 
    "LeadSourceName" : "Website", 
    "LeadTypeName" : "Request Brochure", 
    "LeadCategoryName" : "Referral Traffic", 
    "LeadCampaignName" : null, 
    "EventName" : null, 
    "LeadDate" : null, 
    "FirstName" : "Allen", 
    "LastName" : "Hall", 
    "Address1" : "123 Main Street", 
    "Address2" : null, 
    "City" : "Saint Louis", 
    "State" : "MO", 
    "PostalCode" : "63105", 
    "Zip4" : null, 
    "CompanyName" : null, 
    "CompanyTitle" : null, 
    "County" : null, 
    "Country" : null, 
    "HomePhone" : null, 
    "WorkPhone" : null, 
    "MobilePhone" : null, 
    "Fax" : null, 
    "Email" : "ahall@avalamarketing.com", 
    "CountryCode" : "US", 
    "DealerIds" : null, 
    "Dealers" : [{ 
        "DealerNumber" : "100", 
        "DealerLocation" : "1", 
        "DealerName" : "Bob's Boats" 
      } 
    ], 
    "ProductIds" : null, 
    "Products" : [{ 
        "ProductCode" : "100", 
        "ProductName" : "Fast Boat", 
        "ProductModelYear" : "2014" 
      } 
    ], 
    "SessionData" : null, 
    "TriggeredSend" : null, 
    "OptInListIds" : null, 
    "EmailRefused" : null, 
    "Comment" : null, 
    "Customs" : [{ 
        "FieldName" : "BuyTimeFrame", 
        "FieldValue" : "1-3 months" 
    }, { 
        "FieldName" : "Financing", 
        "FieldValue" : "Yes" 
      } 
    ] 
  } 
]

   


Sample Success Response (XML/JSON)


<Leads xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Lead> 
        <Id>0</Id> 
        <Status>Success</Status> 
        <StatusMessage>Lead successfully received</StatusMessage> 
        <Messages /> 
        <LeadApiIdentifier>44b07d7b-1677-4bb8-84c0-9846b9d5bec1</LeadApiIdentifier> 
    </Lead> 
</Leads>


{ 
    "TopLevelError" : null, 
    "LeadResponseRecords" : [{ 
    "LeadApiIdentifier" : "99c932d0-310c-497b-8e45-cad143231092", 
    "Id" : "0", 
    "Status" : "Success", 
    "StatusMessage" : "Lead successfully received", 
    "Messages" : [] 
    } 
  ] 
}


Sample Failed Response (XML/JSON)


<?xml version="1.0"?> 
<Leads xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
    <Lead> 
        <Status>Failure</Status> 
        <StatusMessage>Lead failed validation</StatusMessage> 
        <Messages> 
            <Message> 
                <Field>LeadSourceName</Field> 
                <Message>The LeadSourceName field is required.</Message> 
            </Message> 
        </Messages> 
        <LeadApiIdentifier>44b07d7b-1677-4bb8-84c0-9846b9d5bec1</LeadApiIdentifier> 
    </Lead> 
</Leads>



{ 
    "TopLevelError" : null, 
    "LeadResponseRecords" : [{ 
    "LeadApiIdentifier" : "99c932d0-310c-497b-8e45-cad143231092", 
    "Id" : null, 
    "Status" : "Failure", 
    "StatusMessage" : "Lead failed validation", 
    "Messages" : [{ 
        "Field" : "LeadSourceName", 
        "Message" : "The LeadSourceName field is required." 
         } 
       ] 
     } 
  ] 
}