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
Servers
Computed URL:https://api.eu-stage.keyloop.io/api/sample/sample/v1

Server variables

environmententerpriseIdstoreId
environment
enterpriseId
storeId

Sales Lead Queries

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

NameDescription
leadId *
string
(path)

A unique id that identifies an individual Lead resource.

Responses

CodeDescription
200

Success

Media type
Controls 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."
  }
}
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"
    }
  ]
}

Sales Lead Actions

Create/modify lead resource

POST​/leads​/sales-lead
Create Sales Lead

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

CodeDescription
201

Lead created result

Media type
Controls Accept header.
{
  "leadId": "82445634-b823-4bd5-8160-cf91a885ce43"
}
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"
    }
  ]
}

Schemas

HumanResource
LeadReferenceData
Note
SalesInterest
SalesLeadCreateResponse
SalesLeadCreateRequest
VehicleFull
VehicleOfInterest
VehicleReferenceData
VehicleSpecification
LeadSourceCode
LeadActivityData
ActivityTypeData
ActivityType
LeadRequestTypeData
LeadRequestType
ValidationError
LeadQueryResponse
LeadIdData
Common.Response.Error