This is a technical summary document for the carsales.com Ltd Lead Service (LS) API. The LS provided by carsales.com Ltd is in the form of a RESTful web based API that allows approved third parties to integrate their leads with the Autogate Platform.
The terms and conditions for using this service must be adhered to. The utilisation of this service constitutes agreeing to the terms and conditions.
We have available Frequently Asked Questions for submitting leads.
| Details | URL(V2) | URL(V3) |
|---|---|---|
| Test* | https://lead-api.s.core.csnglobal.net/docs/v2-leads | https://lead-api.s.core.csnglobal.net/docs |
| Production | https://lead-api.core.csnglobal.net/docs/v2-leads | https://lead-api.core.csnglobal.net/docs |
| Documentation | https://lead-api.core.csnglobal.net/docs/v2-leads | https://lead-api.core.csnglobal.net/docs |
The lead API requires authentication. An account will need to be setup, and the credentials need to be included in the headers. A working email address will be used for the username. The address will be utilised for sending service notifications e.g. outages, password resets etc so must be a monitored email address.
The V3 API (described in this document) supports basic authentication (using HTTPS). To use basic authentication please ensure the HTTP Authorisation header is included (as per the HTTP standard).
NOTE: The v1 end point currently supports custom headers if you are unable to use the HTTP standard for authorisation:
username: xxx@xxx.com
password: {asprovided}
To use the V1 or V2 end point simply replace V3 with V1 or V2 in the URL.
Submitting a lead requires posting a JSON payload (lead model) to a web endpoint.
The lead model supports any type of lead (e.g. dealer, private, car, bike, etc.), however depending on the type different validation may be applied at the API level.
When validation fails, an error response will be returned with an explanation.
| HTTP Code | Description | Explanation |
|---|---|---|
| 40x | Failed during validation (bad request) or authentication (failed username or password verification). | Validation failed or authentication has failed. Check body for details. Retrying without modifying the lead / credentials will not result in a successful submission. |
| 50x | Temporary Failure. | The Lead API is currently offline or has a temporary issue. The request should be retried at a later time. |
| 200 | Lead is submitted. | GUID returned is an ID assigned to the lead by the API. It can be used to retrieve the lead or can be used as confirmation. If the Identifier property was provided as part of the lead submission, the GUID returned is the same identifier provided. |
If there is a successful submission of a lead the response body will contain a unique identifier that can be utilised in the future to gain access to the lead, and for immediate tracking purposes. If the Identifier was set on the Lead submitted, then the GUID returned will be the same value. The body will also return an error message if there is a problem submitting the lead. The response is a JSON string containing the GUID.
e.g. "75369C94-78FD-4009-8D43-E5F48F302014"
It is the responsibility of the submitter to ensure that they receive and process a 2xx response and not submit the lead again otherwise duplication will occur. To be sure the submitter can create and utilise a globally unique identifier for the unique Identifier of the lead, and duplicate submission will not occur. Caution should be taken though in resubmitting already submitted leads using a supplied UID as this could cause any subsequent changes to be overwritten (i.e. this is also the mechanism to submit updates to a lead).
It is also the responsibility of the submitter to ensure that if a 5xx error is received, that the lead is resubmitted at a later time. If the lead is not resubmitted, it will not appear in the receivers Autogate account.
| Property Name | Description | |
|---|---|---|
| Identifier | Desired |
If not provided will be assigned (and lead will be treated as a new lead). This must be provided as a GUID in the format: 00000000-0000-0000-0000-000000000000. |
| SellerIdentifier | Required | Carsales provided seller unique identifier. This is to identify the correct dealer account (within Autogate) that the lead is to be sent to. This must be included as a GUID in the format: 00000000-0000-0000-0000-000000000000. Carsales will provide the identifier for a given dealer account. It will be the responsibility of the submitter to maintain the mapping to any of their internal systems. |
| Service | Required | This must correspond to a service identifier configured specifically for the type of lead being submitted. This will be provided by carsales for the lead types you are submitting. For the most part this will likely be the name of the company and / or the system submitting the leads. |
| LeadType | Required |
Example valid values include (but are not limited to): New, Used, Generic, Demo, General. The following definitions apply
|
| RequestType | Required |
Should be set to Dealer for dealer leads. Example valid values include: Dealer, Private, Finance, Insurance. |
| ItemType | Required |
The type of the item described. Valid values include: Car, Boat, Bike, Caravan, Industry, Truck, Heavycommercial, Marinepower, Marinepwc, Marinesail. |
| Status | Desired |
Only required if the lead is being updated. Valid options are: New, Contact, Commitment, Sold, Lost, Duplicate, and Unworkable. |
| Tags | Desired |
String array allowing the specification of different lead attributes, e.g. was it submitted on a mobile device, or part of a specific campaign.
These tags will be passed through to the receiver of the lead.
Tags are provided so that a submitter can place various levels of attribution. Tags are freeform and can signify anything the submitter and receiver agree upon.
It is advised that tags be meaningful, as they will allow the receiver to search and filter leads.
|
| Comments | Desired | Free text comments as supplied by the user, and any additional information needing provision to the dealer. |
| Environment | ||
| SiteOrigin | Required | The domain name of where this lead is submitted. e.g. yourwebsite.com.au. |
| PageSource | Desired | The page of where this lead is submitted. e.g. Details, Listing, PhotoGallery |
| IPAddress | Required | It is the IP address of the device submitting the lead. |
| SessionId | Desired | Some form of unique identifier provider by the system submitting the lead to allow for tracing of the lead between user based sessions. |
| Prospect | ||
| Title | Prospect title. | |
| FirstName | Desired | Prospect first name. |
| LastName | Desired | Prospect last name. |
| CompanyName | Prospect company if applicable. | |
| Desired | Prospect email address. | |
| Address | ||
| Suburb | ||
| State | ||
| Postcode | Prospect postcode. | |
| MobilePhone | Mobile phone number. | |
| HomePhone | Home phone number. | |
| WorkPhone | Work phone number. | |
| Item | ||
|
NOTE: The fields here are not mandatory, however the more information provided the better the recipient understands the nature of the enquiry.
|
||
| StockNumber | Desired | The stock number for the item. Required for matching to inventory (unless Generic or General Lead and vehicle described below). |
| RedbookCode | Desired | The item RedbookCode. Desired if generic lead (and vehicle not described below). |
| Make | Desired | The item Make. |
| Model | Desired | |
| Badge | Desired | |
| Series | Desired | |
| Description | ||
| Year | ||
| Price | ||
| RegistrationNumber | ||
| EngineDescription | ||
| Transmission | ||
| Colour | ||
| BodyType | ||
| FuelType | ||
| Odometer | Desired | |
| DetailsUrl | ||
| Attachment | ||
| Type | Required | The Type is type of the Attachment object. Only the "trade-in" type is supported. |
| SpecificationId | The Id of the specification that describes the vehicle. | |
| SpecificationProvider | Required with a SpecificationId | The Specification Provider. Supported specifications are (RedbookCode). |
| Make | This is required when SpecificationId is empty. | |
| Model | This is required when SpecificationId is empty. | |
| Year | This is required when SpecificationId is empty. Must be between 1800 and 3000. | |
| RegistrationNumber | This is required when VIN is not provided. | |
| RegistrationState | This should be a valid Australian state (ACT, NSW, NT, QLD, SA, TAS, VIC, WA) and is required when RegistrationNumber is provided and VIN is not provided. | |
| VIN | This is required when RegistrationNumber is not provided. | |
| Odometer | Required | This should have a value greater than 0. |
{
Identifier : "c7806e18-4284-447a-a00a-c221e5647207",
SellerIdentifier : "cb41a639-76d4-4f8d-adfa-efce175c35f0",
Service : "ExampleService",
LeadType : "New",
ItemType : "Car",
RequestType : "Dealer",
Status : "New",
Environment : {
SiteOrigin : "carsales.com.au",
PageSource : "details",
SourceDevice : "desktop",
IPAddress : "12.12.12.12",
SessionId : "0deb7106-4b7b-4cee-a29e-8777b11a336d"
},
Prospect: {
Title : "Mr",
FirstName : "Barry",
LastName : "Bloke",
CompanyName : "XYZ Ltd",
Address : "31 The Avenue",
Suburb : "Smalltown",
State : "VIC",
Postcode : "3111",
Email : "barry@bloke.com",
HomePhone : "0397845346",
MobilePhone : "0411111111",
WorkPhone : "0398765432",
FaxNumber : "0398765432"
},
Attachments: [{
Type: "trade-in",
SpecificationProvider: "RedbookCode",
SpecificationId: "AUVFORD2015AEBB",
Make : "FASTF",
Model : "Focus",
Year : "2020",
VIN: "KL3MA4899FG14525",
RegistrationNumber: "ITE9ML",
RegistrationState :"VIC",
Odometer:91308
}],
Item : {
StockNumber : "ABC123",
Make : "FASTF",
Model : "Focus",
RedbookCode : "AUVFORD2015AEBB"
},
Assignment : {
Email : "john.smith@salescompany.com",
Name : "John Smith",
Assigned : "2017-01-01T22:00:00.000"
},
Tags : [ "MobileDevice", "DetailsPage", "XYZCampaign" ],
Comments : "any comments the prospect has included, e.g. questions"
}