Checkatrade API for Affiliates

Keys

You will be assigned a key & secret pair that identifies you to the affiliate job service. Jobs cannot be created unless you construct a correct authorization header with your key and secret, as described in #HTTP signature scheme and #Signature string construction. The key and secret are unique to your application, and should be kept secret. If you believe your key or secret has been compromised, please contact us immediately.

Usage

There is one endpoint for affiliates:

• POST /jobs - This endpoint is used to create a job.

Request

You must provide the following information in the POST request (more detailed information can be found in the OpenAPI spec):

• categoryId (number) - The category ID for the job. More information about trade categories can be found in Understanding Trade Categories.
• description (string) - The description of the job. This is a free text field and must be more than 10 characters.
• email (string) - The email address of the person creating the job.
• phone (string) - The phone number of the person creating the job. Must match /^\+?\d{5,15}$/.
• firstName (string) - The first name of the person creating the job.
• lastName (string) - The last name of the person creating the job.
• postcode (string) - The postcode of the job. Must match the following regex /^([Gg][Ii][Rr] 0[Aa]{2})|((([A-Za-z][0-9]{1,2})|(([A-Za-z][A-Ha-hJ-Yj-y][0-9]{1,2})|(([A-Za-z][0-9][A-Za-z])|([A-Za-z][A-Ha-hJ-Yj-y][0-9][A-Za-z]?))))\s?[0-9][A-Za-z]{2})$/.

Example request body:

{
  "description": "My boiler needs fixing.",
  "categoryId": 667,
  "email": "[email protected]",
  "phone": "07900000000",
  "firstName": "Test",
  "lastName": "User",
  "postcode": "SW1A 1AA",
  "preferredStart": {
    "id": "WITHIN_2_WEEKS"
  }
}

In addition to these required fields, you may also pass these optional fields:

• address (object) - To provide a full address to the tradesperson picking up the job.
  • line1 (string, required)
  • line2 (string)
  • line3 (string)
  • city (string, required)
  • postcode (string, required)
• preferredStart (object) - Customer's preferred timing for work to begin, you can find detail about how to get the option here Preferred Start Options
  • id (string, required) - e.g., "URGENT", "WITHIN_2_WEEKS", "FLEXIBLE", to get the list of the options, To retrieve the available options, send a GET request to /preferred-start-options
  • date (string, optional) - A specific date if applicable.

Response

Success

If the request is successful, you will receive a 200 response, with the following fields:

• id (UUID, string) - The ID of the job created.
• trades (array of objects) - The tradespeople that have received the job. Each object contains:
  • id (number) - The ID of the tradesperson.
  • name (string) - The name of the tradesperson.
  • profileURL (string) - URL to the tradesperson's Checkatrade profile.

Example response:

{
  "id": "01965e09-728b-7c80-961e-c88d86845fad",
  "trades": [
    {
      "id": 193131,
      "name": "Alpine Aerials",
      "profileURL": "https://www.checkatrade.com/trades/alpineaerials"
    },
    {
      "id": 598178,
      "name": "YR Installations",
      "profileURL": "https://www.checkatrade.com/trades/yrinstallations"
    },
    {
      "id": 359958,
      "name": "DR Data & Communications Limited",
      "profileURL": "https://www.checkatrade.com/trades/drdatacommunicationslimited"
    }
  ]
}

Failure

If the request fails, for whatever reason, you will get a non-200 status code back. These all follow a standard format (see example below).

A common reason for a failure is that the job has been classified as spam. Below is an example response for this situation:

{
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Job classified as spam",
  "instance": "https://api.staging.checkatrade.com/v1/affiliate-job/jobs"
}

To avoid hitting the spam detection, ensure that a comprehensive description is provided.

If trades are unable to be found for a given category in a given location, a 404 will be returned.

Endpoints

There are two environments, which use different API Keys. To validate your implementation, you may send jobs to the staging endpoint. The jobs will not be sent to tradespeople, but you will receive a response with the tradespeople that would have received the job.

3. Generate your authentication signature

All requests require HMAC-SHA256 signature authentication. This ensures requests genuinely come from you and haven't been tampered with.

How It Works

1. Generate a timestamp
2. Create a signature by hashing the timestamp with your secret
3. Send both in your request headers

See HMAC Authentication for a step by step guide, code snippets and much more in

v1.1