Leads API
Leads 1.7.0
OAS3
Introduction
The Sales Lead API can be used to write new Leads into the Keyloop data systems.
The following definitions are referenced in this API
Lead: A Lead represents a potential customer interest in purchasing a new or used vehicle or an aftersales service
Sales Advisor : A Sales Advisor is the person tasked with selling the car, or closing the Lead.
Current Vehicle : The current vehicle is the vehicle the customer attached to the Lead currently has.
Vehicle of Interest : The vehicle of interest is the vehicle the current customer attached to the Lead is interested in.
Notes : Lead Notes are details relevant to the lead that do not fall within the structured data categories identified.
External reference : Identifier to lead or vehicle that comes from external system.
Provider : Who is responsible of that id, i.e, 3rd party name.
Application : What is the application area for this id, i.e LEADMANAGEMENT
Id : Id in the external system, i.e leadId in 3rd party system
Change history:
##[1.7.0]
- Added new Endpoint i.e., 'getLeadById'
[1.6.3]
- Updated fields descriptions
[1.6.2]
- Changed to 'shared.v1.5.3.yaml'
[1.6.1]
- Changed consumer value from internal to dms.external
[1.6.0]
Updated common schema version in the spec from v1.1.9 to v1.1.11 for customer x-pii attribute
Updated shared schema version in the spec from v1.5.0 to v1.5.2 for customer x-pii attribute
[1.5.0]
- Removed nullable property from LeadRequestType and ActivityType ENUM fields.
[1.4.0]
- Updated leadSourceCode enum to consider first value "GENERAL_SALES_INQUIRY"
[1.3.0]
- Added leadSourceCode, leadRequestType and other fields to SalesLeadCreateRequest schema Fixed validation errors (additionalProperties, x-position)
- Updated common schema version in the spec from v1.1.8 to v1.1.9
[1.2.0]
- Removed swaggerhub urls- Fixed validation errors (removed unused schema LeadFull, among other changes)
[1.1.2]
- Changed SalesLeadCreateRequest.assignedTo into array because previous definition caused the element to chagne from object to array when generating resolved versions of the specification. It has always been seen as array by any party using resolved versions of spec (code-generation, partners, OEM, etc.), this change fixes this specification file to match with reality.
[1.1.1]
- Migration to Keyloop organisation.
[1.1.0]
- Added secondary route for Partner Program access.
[1.0.0]
- Changed response from LeadFull to new schema LeadCreateResponse
[0.0.7]
- Updated privacy schema
[0.0.6]
- Updated privacy schema
[0.0.5]
- Added specification section, removed status, changed source to be optional
[0.0.4]
- Updated descriptions
[0.0.3]
- Updated to newer version of external reference
[0.0.2]
- Updated customer to include external reference
[0.0.1]
- Initial version
https://api.eu-stage.keyloop.io/api/sample/sample/v1
Server variables
environment | |
enterpriseId | |
storeId |
Sales Lead QueriesFind/retrieve lead resource
Find/retrieve lead resource
Get the details of a specific Lead using the LeadID from the leads endpoint. The response will include details of the external reference if available, the source of the Lead and link to the relevant customer that this Lead is related to and their current vehicle and vehicle of interest.
Parameters
Name | Description |
---|---|
leadId * string (path) | A unique id that identifies an individual Lead resource. |
Responses
Code | Description | Links |
200 | Success Media typeControls Accept header.{
"leadId": "b6ea629d-e1b5-490c-aec9-4389136d4110",
"leadHubId": "4D2659D2-035C-4B14-8746-2C276C14EFB6",
"leadSourceCode": "GENERAL_SALES_INQUIRY",
"leadRequestType": {
"requestType": "AUTO_SHOW",
"description": "Request for a vehicle from the auto show."
},
"appointmentDateTime": "2019-02-20T12:34:01.194Z",
"submissionDate": "2019-02-20T12:34:01.194Z",
"displayName": "John Doe - Toyota Avensis 2.0 TDI",
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
},
"leadReferenceData": {
"externalCampaignId": "I2476",
"externalDealerId": "BUK1049284"
},
"source": "WEBSITE",
"contact": {
"contactDetails": {
"customerId": "string",
"names": {
"familyName": "string",
"familyName2": "string",
"middleName": "string",
"givenName": "string",
"preferredName": "string",
"initials": "string",
"salutation": "string",
"titleCommon": "string"
},
"addresses": {
"home": {
"physicalAddress": {
"streetType": "Avenue",
"streetName": "Mill Lane",
"houseNumber": "7",
"buildingName": "string",
"floorNumber": "string",
"doorNumber": "string",
"blockName": "string",
"estate": "string",
"postalCode": "string",
"suburb": "string",
"city": "London",
"county": "string",
"province": "string",
"countryCode": "GB"
},
"postalAddress": {
"poBoxName": "string",
"poBoxNumber": "12",
"poBoxSuite": "string",
"postalCode": "SE4 1UU",
"suburb": "string",
"city": "string",
"county": "string",
"province": "string",
"countryCode": "GB"
}
}
},
"communication": {
"home": {
"mobile": "123-123123",
"landline": "111-234567",
"fax": "111-355754",
"email": "mike@something.com"
},
"work": {
"mobile": "122-124433",
"landline": "122-234567",
"fax": "122-355754",
"email": "mike@work.com"
}
},
"externalReferences": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"privacy": {
"privacyId": "462fef0c-ee4c-4d38-843a-0625db1d37b2",
"level": "OEM",
"usage": "PRIVATE",
"providerName": "Dealer",
"description": "Basic privacy statement",
"validFrom": "2019-01-01T00:00:00.000Z",
"validUntil": "2019-12-31T00:00:00.000Z",
"channel": {
"post": "AGREED",
"email": "DENIED",
"phone": "UNKNOWN",
"messaging": "AGREED"
}
}
},
"currentVehicles": [
{
"vehicleId": "c210f207-b255-4086-9fa0-fb0008c9f79e",
"class": "CAR",
"description": "Toyota Avensis 2.0 D4D Terra STW",
"identification": {
"vin": "string",
"chassis": "string",
"licensePlate": "string",
"engineNumber": "string"
},
"referenceData": {
"make": "Toyota",
"model": "Avensis",
"variant": "2.0 D4D Terra STW",
"modelYear": 2018,
"color": "Brilliant Red"
},
"mileage": {
"unit": "KM",
"value": 120000
},
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}
],
"interest": {
"budget": {
"minimum": 10000,
"maximum": 20000
},
"age": {
"minimum": 0,
"maximum": 60
},
"mileage": {
"minimum": {
"unit": "KM",
"value": 120000
},
"maximum": {
"unit": "KM",
"value": 120000
}
},
"fuelTypes": [
"DIESEL"
],
"class": "CAR",
"condition": "NEW",
"specifications": [
{
"make": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"model": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"variant": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
}
}
],
"vehiclesOfInterest": [
{
"vehicleId": "c210f207-b255-4086-9fa0-fb0008c9f79e",
"description": "Toyota Avensis 2.0 D4D Terra STW",
"identification": {
"vin": "string",
"chassis": "string",
"licensePlate": "string",
"engineNumber": "string"
},
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}
]
},
"assignedTo": [
{
"humanResourceId": "170b0cf1-8154-4ded-8424-8f14ca6f7e5a",
"email": "Joe.Doe@example.com",
"description": "Please can Joe look at this?"
}
],
"salesPerson": {
"id": "170b0cf1-8154-4ded-8424-8f14ca6f7e5a",
"email": "Joe.Doe@example.com"
},
"notes": [
{
"title": "Note title",
"details": "Note details"
}
],
"activity": {
"activityType": {
"activityTypeCode": "VEHICLE_SOLD",
"description": "Activity indicating vehicle sale."
},
"activityDateTime": "2019-02-20T12:34:01.194Z",
"activityNote": "Customer has shown interest in arranging a demo of the vehicle."
}
} | No links |
404 | NotFound Error Media type {
"correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"message": "Invalid request",
"details": [
{
"field": "Status",
"value": "string",
"issue": "The value 'XYZ' is not valid."
}
],
"links": [
{
"method": "GET",
"rel": "self",
"href": "string",
"title": "string"
}
]
} | No links |
Sales Lead ActionsCreate/modify lead resource
Create/modify lead resource
This endpoint can be used to create vehicle sales leads from external sources in a Keyloop dealer management system. This would allow the dealer's vehicle sales team to receive and then progress the lead and respond to the customer's needs.
Parameters
No parameters
Request body
Lead details
{
"leadSourceCode": "GENERAL_SALES_INQUIRY",
"leadRequestType": {
"requestType": "AUTO_SHOW",
"description": "Request for a vehicle from the auto show."
},
"appointmentDateTime": "2019-02-20T12:34:01.194Z",
"submissionDate": "2019-02-20T12:34:01.194Z",
"displayName": "John Doe - Toyota Avensis 2.0 TDI",
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
},
"leadReferenceData": {
"externalCampaignId": "I2476",
"externalDealerId": "BUK1049284"
},
"source": "WEBSITE",
"contact": {
"contactDetails": {
"customerId": "string",
"names": {
"familyName": "string",
"familyName2": "string",
"middleName": "string",
"givenName": "string",
"preferredName": "string",
"initials": "string",
"salutation": "string",
"titleCommon": "string"
},
"addresses": {
"home": {
"physicalAddress": {
"streetType": "Avenue",
"streetName": "Mill Lane",
"houseNumber": "7",
"buildingName": "string",
"floorNumber": "string",
"doorNumber": "string",
"blockName": "string",
"estate": "string",
"postalCode": "string",
"suburb": "string",
"city": "London",
"county": "string",
"province": "string",
"countryCode": "GB"
},
"postalAddress": {
"poBoxName": "string",
"poBoxNumber": "12",
"poBoxSuite": "string",
"postalCode": "SE4 1UU",
"suburb": "string",
"city": "string",
"county": "string",
"province": "string",
"countryCode": "GB"
}
}
},
"communication": {
"home": {
"mobile": "123-123123",
"landline": "111-234567",
"fax": "111-355754",
"email": "mike@something.com"
},
"work": {
"mobile": "122-124433",
"landline": "122-234567",
"fax": "122-355754",
"email": "mike@work.com"
}
},
"externalReferences": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"privacy": {
"privacyId": "462fef0c-ee4c-4d38-843a-0625db1d37b2",
"level": "OEM",
"usage": "PRIVATE",
"providerName": "Dealer",
"description": "Basic privacy statement",
"validFrom": "2019-01-01T00:00:00.000Z",
"validUntil": "2019-12-31T00:00:00.000Z",
"channel": {
"post": "AGREED",
"email": "DENIED",
"phone": "UNKNOWN",
"messaging": "AGREED"
}
}
},
"currentVehicles": [
{
"vehicleId": "c210f207-b255-4086-9fa0-fb0008c9f79e",
"class": "CAR",
"description": "Toyota Avensis 2.0 D4D Terra STW",
"identification": {
"vin": "string",
"chassis": "string",
"licensePlate": "string",
"engineNumber": "string"
},
"referenceData": {
"make": "Toyota",
"model": "Avensis",
"variant": "2.0 D4D Terra STW",
"modelYear": 2018,
"color": "Brilliant Red"
},
"mileage": {
"unit": "KM",
"value": 120000
},
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}
],
"interest": {
"budget": {
"minimum": 10000,
"maximum": 20000
},
"age": {
"minimum": 0,
"maximum": 60
},
"mileage": {
"minimum": {
"unit": "KM",
"value": 120000
},
"maximum": {
"unit": "KM",
"value": 120000
}
},
"fuelTypes": [
"DIESEL"
],
"class": "CAR",
"condition": "NEW",
"specifications": [
{
"make": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"model": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
},
"variant": {
"description": "string",
"codes": [
{
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
]
}
}
],
"vehiclesOfInterest": [
{
"vehicleId": "c210f207-b255-4086-9fa0-fb0008c9f79e",
"description": "Toyota Avensis 2.0 D4D Terra STW",
"identification": {
"vin": "string",
"chassis": "string",
"licensePlate": "string",
"engineNumber": "string"
},
"externalReference": {
"provider": "DummyProvider",
"application": "LEADMANAGEMENT",
"id": "6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0",
"url": "http://leadmanagement.DummyProvider.com/6e5b8bd0-8867-446c-a3a8-8ade9f7a07a0"
}
}
]
},
"assignedTo": [
{
"humanResourceId": "170b0cf1-8154-4ded-8424-8f14ca6f7e5a",
"email": "Joe.Doe@example.com",
"description": "Please can Joe look at this?"
}
],
"salesPerson": {
"id": "170b0cf1-8154-4ded-8424-8f14ca6f7e5a",
"email": "Joe.Doe@example.com"
},
"notes": [
{
"title": "Note title",
"details": "Note details"
}
],
"activity": {
"activityType": {
"activityTypeCode": "VEHICLE_SOLD",
"description": "Activity indicating vehicle sale."
},
"activityDateTime": "2019-02-20T12:34:01.194Z",
"activityNote": "Customer has shown interest in arranging a demo of the vehicle."
}
}
Responses
Code | Description | Links |
201 | Lead created result Media typeControls Accept header.{
"leadId": "82445634-b823-4bd5-8160-cf91a885ce43"
} | No links |
400 | Bad request Media type {
"correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"message": "Invalid request",
"details": [
{
"field": "Status",
"value": "string",
"issue": "The value 'XYZ' is not valid."
}
],
"links": [
{
"method": "GET",
"rel": "self",
"href": "string",
"title": "string"
}
]
} | No links |