---
updatedAt: 2026-01-06T17:59:51.000Z
agentTools:
  projectIndex: https://developers.checkatrade.com/llms.txt
---

# 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](#http-signature-scheme) and [#Signature string construction](#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](/docs/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:

```json
{
  "description": "My boiler needs fixing.",
  "categoryId": 667,
  "email": "test@user.com",
  "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](https://developers.checkatrade.com/docs/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:

```json
{
  "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:

```json
{
  "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.

| Environment | URL                                                         | Description                                                             |
| ----------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| Staging     | <https://api.staging.checkatrade.com/v1/affiliate-job/jobs> | Staging environment. Jobs will not be sent to real tradespeople.        |
| Production  | <https://api.checkatrade.com/v1/affiliate-job/jobs>         | Production environment. Jobs created will be sent to live tradespeople. |

### 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](https://developers.checkatrade.com/docs/hmac-authentication) for a step by step guide, code snippets and much more in

***

v1.1