CAP Gateway - API Documentation (Technical)

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 or issues you can log a support ticket here.

Getting started

This documentation provides the necessary steps to authenticate with the CAP API, submit leads to the CAP Platform, and handle responses effectively. It includes detailed descriptions of the Authentication, payload structure, and example responses for both successful and non-successful scenarios.

Prerequisites

Before you can start the integration, you will require the following details from CAP:

Per Environment
- API Key
- Campaign ID
Source Acquisition Channel
Enquiry Type
Vehicle Names
Additional Required Fields for Campaign

Authorization

This API requires authentication using an static API key to access its endpoints. Your API key should be provided to you. Example API key: be12f0d522bb41968b7cf4f82c76fbc2.

Request Headers

Key	Value

Key	Value
Content-Type	application/json
X-API-Key	<YOUR_API_KEY>

API Endpoints

Environment	Base URL

Environment	Base URL
QA	https://qa-api.cap-gateway.com
Production	https://api.cap-gateway.com

Method Type	Endpoint	Description

Method Type	Endpoint	Description
POST	/lead-submission/v1/external	This endpoint allows the submission of leads including contact details, optin consents, and vehicle.

Lead Submission

This endpoint allows external systems to submit leads, capturing essential details such as contact details, vehicle selected, and opt in consents.

Request URL

POST {baseUrl}/lead-submission/v1/external

Request Body

{
    "metadata": {
        "campaignId": "966c7488-bfa7-45b5-8510-d26ba3008879",
        "enquiryDateTime": "2024-09-12T10:20:59.52",
        "externalReferenceId": "9cf5ae87-aafb-43e5-b4d3-9d72367a2b86",
        "enquiryType": "Test Drive",
        "ipAddress": null,
        "enquirySource": {
            "acquisitionChannel": "Google"
        }
    },
    "contactDetail": {
        "firstName": "test",
        "lastName": "test",
        "emailAddress": "test@cap-gateway.com",
        "phoneNumber": "+4420 8759 9036",
        "address": {
            "postcode": "L39AG"
        }
    },    
    "optInConsents": {
        "PhoneCall": true,
        "Post": false,
        "Email": false,
        "Sms": false
    },
    "vehicle": {
        "name": "Audi Q6 e-tron"
    }
}

Payload Description

Property	Type	Required	Supplied by CAP	Description

Property	Type	Description
`metadata`	object	Information about the campaign and enquiry details.
`metadata.campaignId`	guid	Unique ID of the marketing campaign.
`metadata.enquiryDateTime`	DateTime	Date and time the enquiry was made. ISO 8601 format, Coordinated Universal Time (UTC), to the second. "T" is a delimiter between the date and time.
`metadata.externalReferenceId`	string	External system reference ID for tracking. Client’s reference ID.
`metadata.enquiryType`	string	Type of enquiry. Accepted Values: “Test Drive”, “Quotation”, “Retailer Contact”, “KMI”, “Interest Only”, “Register Of Interest”
`metadata.ipAddress`	string	The IP address of the user.
`metadata.enquirySource.acquisitionChannel`	string	The acquisition channel for the enquiry.
`contactDetail`	object	Contains the contact details of the person submitting the enquiry.
`contactDetail.firstName`	string	First name of the individual.
`contactDetail.lastName`	string	Last name of the individual.
`contactDetail.emailAddress`	string	Email address of the individual.
`contactDetail.phoneNumber`	string	Phone number of the individual. +44 or 0 prefix accepted. Required for certain campaigns
`contactDetail.address.postcode`	string	Postcode of the individual's address. Required for certain campaigns
`optInConsents`	object	Contains consent data for different communication channels.
`optInConsents.phoneCall`	boolean	Opt-in status for the communication channel Accepted values: true, false, null
`optInConsents.post`	boolean	Opt-in status for the communication channel Accepted values: true, false, null
`optInConsents.email`	boolean	Opt-in status for the communication channel Accepted values: true, false, null
`optInConsents.sms`	boolean	Opt-in status for the communication channel Accepted values: true, false, null
`vehicle.name`	string	Name of the vehicle the user is interested in.

Example Response

Accepted (202) - Leads that have passed validation and been accepted into CAP and will be subject to further processing.

{
    "success": true,
    "messages": [],
    "result": {
        "requestReferenceId": "e05072f9-ae85-42e2-ba42-c13449e5abaf",
        "enquiryReferenceCode": "ENQ-240912-AZGCM0F8"
    }
}

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,
    "messages": [
        "Campaign not found. Please check correct Campaign Id has been specified or contact support"
    ],
    "result": {
        "requestReferenceId": "08585f67-6d4d-4272-ac0a-342ac0edcb8c",
        "enquiryReferenceCode": null
    }
}

Internal Server Error (500) - Requests which the CAP Gateway has failed to process, such as an exception will return with a status code of Internal Server Error.

{
    "success": false,
    "messages": [
        "An internal error has occured."
    ],
    "result": {
        "requestReferenceId": "08585f67-6d4d-4272-ac0a-342ac0edcb8c",
        "enquiryReferenceCode": null
    }
}

API Response Codes And Error Messages

Response Codes

Code	Meaning

Code	Meaning
202	Lead submission accepted.
400	Bad request, validation error.
401	Unauthorized, invalid token.
500	Internal server error.

Error Messages

Each error message points out a specific issue related to the submission. This could be the submission data, campaign configurations, or other entities like vehicles, and offers a general suggestion to either correct the submission or contact support.

Validation Messages

Validation messages will be formatted will show in the response in this format: “Property:{PropertyName}; ErrorMessage:{Message}“. See below for the list of messages.

E.g. "Property:ContactDetail.FirstName; ErrorMessage:'First Name' must not be empty."

Property	Error Message

Property	Error Message
`metadata`	"Metadata must not be empty."
`metadata.enquiryDateTime`	"EnquiryDateTime must not be empty."
`metadata.enquiryType`	"EnquiryType must not be empty."
`metadata.enquirySource`	"EnquirySource must not be empty."
`metadata.enquirySource.acquisitionChannel`	"AcquisitionChannel must not be empty."
`vehicle`	"Vehicle must not be empty."
`vehicle.name`	"Vehicle Name must not be empty."
`contactDetail`	"ContactDetail must not be empty."
`contactDetail.firstName`	"FirstName must not be empty."
`contactDetail.lastName`	"LastName must not be empty."
`contactDetail.emailAddress`	"EmailAddress must not be empty."
`contactDetail.phoneNumber`	"PhoneNumber must not be empty."
`contactDetail.address`	"Address must be empty."
`contactDetail.address`	"Address must not be empty."
`contactDetail.address.postcode`	"Postcode must not be empty."
`contactDetail.address.postcode`	"Postcode is not in a valid format."
`optInConsents`	“Opt In Consents must not be empty”

Setup & Campaign Messages

Error Type	Error Message	Description

Error Type	Error Message	Description
`InternalError`	`There has been an issue processing your request. Please contact support.`	General error indicating an issue with internally. User should contact support for further assistance.
`InvalidCampaignId`	`CampaignId is not valid. Please check that it is populated and with the correct value.`	The specified Campaign ID is invalid or missing on the field `metadata.campaignId`
`CampaignNotFound`	`Campaign not found. If the correct CampaignId has been verified and the issue persists, please contact support.`	The system could not find a campaign matching the provided Campaign ID. Verify the value in `metadata.campaignId` or contact support.
`CampaignNotStarted`	`Campaign has not started. Submissions are not yet being accepted.`	The campaign has not started, so leads are not yet being accepted. Contact support if this is not expected.
`CampaignHasEnded`	`Campaign has ended. Submissions are no longer being accepted.`	The campaign has ended, and will not accept any more leads. Contact support if this is not expected.
`CampaignNotActive`	`Campaign is not currently active. Submissions are not currently being accepted.`	The campaign is not currently active. Please contact support if this is not expected.
`VehicleNotFound`	`Vehicle '{VEHICLE_NAME}' was not found for the campaign '{CAMPAIGN_ID}'.`	The specified vehicle could not be found for the given campaign. Verify the combination of the field values: `metadata.campaignId` `vehicle.name` User should contact support for further assistance.
`InvalidCampaignParameters`	`Please check correct combination of CampaignId, AcquisitionChannel, EnquiryType and Vehicle have been specified or contact support.`	Could be due to an incorrect combination of the data on the fields: `metadata.campaignId` `metadata.enquiryType` `metadata.enquirySource.acquisitionChannel` `vehicle.name` User should contact support for further assistance.
`AcquisitionChannelNotFound`	`AcquisitionChannel '{CHANNEL}' not found. Please check correct value has been specified or contact support`	The specified Acquisition Channel is invalid. Please verify the value specified in `metadata.source.acquisitionChannel` or contact support.

Need help?

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.