Gateway API

See our Onboarding and Testing processes for a clear outline of the steps we follow.
See our FAQ for clarification on time scales and testing.
If you have any questions you log a support ticket here.

Any lead data entering our CAP systems must integrate with the Gateway API, this is the entry point for any data provided by data suppliers. This page contains details of the key steps required to integrate. All examples refer to our test environment, production equivalents will be provided in due course.

Contents

1 Authentication
- 1.1 IdentityModel
- 1.2 HTTP Request
- 1.3 Token Response
- 1.4 Token Refresh
2 Submitting Payload
- 2.1 Schema
- 2.2 Request body
- 2.3 Responses
3 Data Lookups
- 3.1 Vehicle Lookup
4 Production Environment
- 4.1 Endpoints
5 Webhook Responses
- 5.1 Configuration:
- 5.2 Expected response - Success
- 5.3 Failed validation - Email
- 5.4 Failed validation - Phone number
- 5.5 Failed validation - Duplicate
- 5.6 Failed validation - Address
- 5.7 Detected Test Lead
  - 5.7.1 Need help?

Authentication

Authentication can be transmitted via the Authorization header using the following scheme:

Authorization: Bearer access_token_here

An Authorization server is used to protect access to the Gateway API. It is configured to include OAuth2 Client

Credentials so access tokens can generated for making authenticated requests.

Our authentication server is hosted at:

STAGING - https://qa-authentication.theleadagency.com
PRODUCTION - https://authentication.theleadagency.com

IdentityModel

If integrating using the most recent versions of .NET, the IdentityModel NuGet package can be used to make a request for an access token.

Here you can find the documentation for making API requests using IdentityModel:

https://identitymodel.readthedocs.io/

When requesting a token a number of parameters must be provided in the request:

client_id = {thirdparty}
client_secret = REPLACE_WITH_SECRET
scope = GatewayAPI
grant_type = client_credentials

HTTP Request

If unable to use the IdentityModel mechanism, access tokens can be generated by making a HTTP request to the server’s token endpoint:

POST /connect/token HTTP/1.1
Host: qa-authentication.theleadagency.com
Content-Type: application/x-www-form-urlencoded
client_id={thirdparty}&client_secret=
{REPLACE_WITH_SECRET}&scope=GatewayAPI&grant_type=client_credentials

Token Response

Upon successfully retrieving an access token, the response should resemble the below:

{
  "access_token": "ACCESS_TOKEN_HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}

For efficiency, access tokens should be cached until they have expired. The time of expiry can be calculated using the expires_in property (seconds).

Token Refresh

Upon the expiration of token, you will need to refresh the token to continue accessing the API.

Here you can find the documentation for making API requests to refresh your access token:

https://identityserver4.readthedocs.io/en/latest/topics/refresh_tokens.html

Submitting Payload

All payloads can be submitted from the following test HTTPS endpoint

STAGING - https://qa-gateway-api.theleadagency.com/api/v1/orders/{orderID}/payload
PRODUCTION - https://gateway-api.theleadagency.com/api/v1/orders/{orderID}/payload

This endpoint accepts requests using POST method only and uses content type application/json.

Schema

Example payload:

{ "enquiryMetadata":{"externalReferenceId":"ABC123","enquiryType":["Test Drive"],"enquiryPlatformSource":"Example","enquiryDate":"2023-12-30T08:00:00"}, "enquiryItems":[{"isInitialItem":true,"enquiryItemDetails":{"vehicleType":1,"vehicleName":"Example"},"dateAdded":"2023-12-30T08:00:00"}], "contactDetails":{"telephoneNumbers":[{"telephoneNumber":"Example","isPreferred":true}],"lastName":"Example","firstName":"Example","emailAddresses":[{"isPreferred":true,"email":"Example"}],"addresses":[]}, "optInConsent":[{"policyType":"Partners","policyGuid":"00000000-0000-0000-0000-000000000000","optInValues":[{"type":"PhoneCall","isOptedIn":false},{"type":"Email","isOptedIn":false},{"type":"Sms","isOptedIn":false},{"type":"Post","isOptedIn":false}],"consentDate":"2023-12-30T08:00:00"}] }

Request body

Element			Required	Type	Accepted Values	Description

Element			Required	Type	Accepted Values	Description
enquiryMetadata			true	object		Object that contains the metadata with the enquiry.
	enquiryDate		true	string	Date and time the enquiry was created. In ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time. For example, July 26, 2017 at 11:10 p.m. and 20 seconds is expressed as 2017-07-26T23:30:20.
	externalReferenceId		false	string		External Identifier for the data in a third party system such as a data supplier, this can be used to correlate the enquiry.
	enquiryType		true	string	Support Types Test Drive Quotation KMI Dealer Contact	The type of enquiry, this is an array of strings. E.g. The types will be available from a vehicle lookup.
	enquiryPlatformSource		true	string	Examples include: Twitter FacebookIG LinkedIn Amazon Publication name	The source platform of the enquiry. Please contact TLA to confirm values specific to your payloads.
contactDetails			true	object		Object that contains information about with the contact details associated with the enquiry.
	title		true	string	Mr Mrs Miss Ms Dr Company Family PublicInstitution	Title of the consumer associated with the enquiry.
	firstName		true	string		First name of the consumer associated with the enquiry.
	lastName		true	string		Last name of the consumer associated with the enquiry.
	emailAddresses		true	array		Email addresses associated with the enquiry.
		email	true	string		Standard Email address Format
		isPreferred	true	bool	true false	Define whether this is the preferred email to use.
		type	false	string	Personal Work Other.	Type of email address
	telephoneNumbers (Provide an empty Array when not required)		true	array		Telephone numbers associated with the enquiry.
		telephoneNumber	true	string	11 digital number format, starting with 0. i.e. 07812345678	Telephone number.
		isPreferred	true	bool	true false	Define whether this is the preferred telephone number to use.
		type	false	string	Home Mobile Fax Work Other	Type of telephone number.
	addresses (Provide an empty Array when not required)		true	array		Addresses associated with the enquiry.
		building	false	string		Name of residential or commercial premise. required.
		buildingNumber	false	string		Number to identify premise on a street.
		subBuilding	false	string		When a premise is split into individual units such as flats, apartments or business units. E.g. Flat 1, A or 10A
		street	false	string		Also known as the thoroughfare or road name.
		subStreet	false	string		Used to supplement street when the same street name has been used more than once in the same postal town.
		townCity	false	string		Town or city the address is located in.
		dependentLocality	false	string		Dependent locality, this is used to supplement the address when multiple instances exist in the same postal town.
		countyState	false	string		County or state of the given address.
		postcode	true	string	With or without a space, i.e. L3 9AG L39AG	Postcode of the given address. Validated to Royal Mail standard.
		organisation	false	string		Name of the organisation registered at this address.
		type	false	string	Home Work Shipping Billing Other.	Type of address.
optInConsent			true	array		Opt in consent associated with the enquiry.
	consentDate		true	string	Date and time the consent was received. In ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time. For example, July 26, 2017 at 11:10 p.m. and 20 seconds is expressed as 2017-07-26T23:30:20.
	policyType		true	string	Partners	Type of policy. TLAMarketing, TLAService, or Partners. For this integration you will only need to supply Partners which represents consent to the manufacturer marketing the consumer.
	optInValues		true	array		Types of opt in associated with the policy type.
		type	true	string	PhoneCall Email Sms Post.	Type of opt in.
		isOptedIn	true	bool	true false	Define whether this opt in type is opted in for the given policy type.
enquiryItems			true	array		The items associated with the enquiry, in this case the vehicles associated with the enquiry
	dateAdded		true	string	Date and time the item was added to the enquiry. In ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time. For example, July 26, 2017 at 11:10 p.m. and 20 seconds is expressed as 2017-07-26T23:30:20.
	isInitialItem		true	bool	true false	Define whether this is the initial item on the enquiry.
	enquiryItemDetails		true	object		Define the vehicle for the given item on the enquiry.
		vehicleType	true	number	1 = Car 2 = Van	Type of vehicle
		vehicleName	true	number	The vehicle names will be available from a lookup.	Name of the vehicle.

Responses

We use appropriate HTTP status codes where possible to indicate the request status.

Leads submitted to the Gateway API will be subject to validation before they are accepted. As a result, you should

expect to see two key responses received upon submission.

Expected Response - Accepted (202)

Leads that have passed validation and been accepted into CAP and will be subject to further processing.

{
  "success": true,
  "status": "Success",
  "messages": [],
  "result": {
    "requestId": "df4e8172-6110-4b70-998c-858747209038"
  }
}

Bad Request (400)

Leads that have failed validation, this indicates an issue with the data provided as part of the request. The response body will contain further details on the validation failure that has occurred.

{
  "success": false,
  "status": "InvalidPayload",
  "messages": [
    "The vehicle is not valid for this order.",
    "The enquiry type is not valid for this order.",
    "The consent section is not valid or missing."
  ],
  "result": {
    "requestId": "df4e8172-6110-4b70-998c-858747209038"
  }
}

Bad Request (400)

Requests which contain invalid data (such as an invalid order id) will respond with a Bad Request. The response body will contain further details.