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: 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 | ||
| 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: 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 | 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: | 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. | |
| Campaign | Max Length: 50 | UTM parameter for Campaign. This parameter identifies your campaign. | |
| Source | Max Length: 50 | UTM parameter for Source. This parameter is generally used to pass where the traffic originated. | |
| 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."
}
]
}
]
}