Lead API

Overview

Use the Lead API to create a lead record in Aimbase. 

Related APIs: 

  • To filter, sort and retrieve lead records across an Aimbase instance, use the Lead API Search endpoint.  
  • To send activities (email, call, appointment, quote) performed on a lead, or a lead status change (working, sold, abandoned) use the Lead Disposition API
  • Use the Lead Odata endpoint to update a lead record.  


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. 
LeadUid


Use this field for shared leads to pass the source Aimbase's LeadUid.
Program
string The OEM program the lead is tied to - not every lead is tied to a program. 
EventName    Max Length: 100  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.
ConditionCode

A code that identifies if the product is New (N), Used (U) or Showroom (S). 
IsCommunicationOptIn  X  Boolean  A flag for identifying if the lead is opted in for future communications. 
CommunicationOptInIpAddress    Max Length: 50  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  The flag for opting in or out of sending the lead nurture email notifications.
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: 128 Specifies the list codes that the lead should filter into, must match the list codes in Aimbase. 
LeadReroute
Boolean When set to true, it allows the lead to reroute even for a pre-selected dealer. When set to false, it will override any reroute rules in place and lead will not be rerouted. If no value is passed, the default behavior will reroute the lead if the application has the reroute feature turned on. 
Medium    Max Length: 200  UTM parameter for Medium. This parameter reflects the channel name.
Term    Max Length: 200  UTM parameter for Term (also known as Keyword). This parameter can be used to pass any characteristics that prompted your content to display.
Content    Max Length: 200 UTM parameter for Content. This parameter passes details about your content and can be used to differentiate links that point to the same URL.
Comment
Max Length: 2048

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. 
OemManufactureCode
Max Length: 20 This field is used for shared leads. The manufacture code is the value to the Aimbase instance the lead is being shared. 
OemDealerNumber
Max Length: 20 This field is used for shared leads. The OEM dealer number value to where the lead is being shared. 

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. 
BrandCode X Max Length: 100  The brand code that corresponds to the  product being passed. If a value is passed, the Brand object on the lead will be ignored.
BrandName
Max Length: 100  The brand name that corresponds to the  product being passed. If a value is passed, the Brand object on the lead will be ignored.

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> 
    <Comment>This is a comment</Comment>
    <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>
            <BrandCode>FLXR</BrandCode> 
            <BrandName>Falcon XR</BrandName>  
        </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", 
        "ProductName" : "FLXR", 
        "ProductModelYear" : "Falcon XR"
        "BrandCode" : "FLXR",
        "BrandName" : "Falcon XR"
      } 
    ], 
    "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." 
         } 
       ] 
     } 
  ] 
}