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 /^[A-Z]{1,2}\d[0-9A-Z]? ?\d[A-Z]{2}$/.
• preferredStart (object) - Customer's preferred timing for work to begin
  • 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

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)

Response

Success

If the request is successful, you will receive a 201 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.

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.

HTTP signature scheme

The signature is based on this draft "Signing HTTP Messages". Your application must provide to the client application both unique identifier:

• key: A key used to identify the client application;
• shared secret: A secret key shared between your application and the client application used to sign the requests and authenticate the client application.

HTTP header

The signature must be sent in the HTTP header "Authorization" with the authentication scheme "Signature":

Authorization: Signature keyId="API_KEY",algorithm="hmac-sha256",headers="(request-target) host date digest content-length",signature="Base64(HMAC-SHA256(signing string))"  

The different components of the signature are:

• keyId (REQUIRED): The client application's key.
• algorithm (REQUIRED): The algorithm used to create the signature.
• header (OPTIONAL): The list of HTTP headers used to create the signature of the request. If specified, it should be a lowercased, quoted list of HTTP header fields, separated by a single space character. If not specified, the Date header is used by default therefore the client must send this Date header. Note : The list order is important, and must be specified in the order the HTTP header field-value pairs are concatenated together during signing.
• signature (REQUIRED): A base 64 encoded digital signature. The client uses the algorithm and headers signature parameters to form a canonicalized signing string.

Signature string construction

To generate the string that is signed with the shared secret and the algorithm, the client must use the values of each HTTP header field in the headers Signature parameter in the order they appear.

To include the HTTP request target in the signature calculation, use the special (request-target) header field name.

1. If the header field name is (request-target) then generate the header field value by concatenating the lowercased HTTP method, an ASCII space, and the path pseudo-headers (example : get /protected);
2. Create the header field string by concatenating the lowercased header field name followed with an ASCII colon :, an ASCII space and the header field value. If there are multiple instances of the same header field, all header field values associated with the header field must be concatenated, separated by a ASCII comma and an ASCII space ,, and used in the order in which they will appear in the HTTP request;
3. If value is not the last value then append an ASCII newline \n.

To illustrate the rules specified above, assume a headers parameter list with the value of (request-target) host date cache-control x-test with the following HTTP request headers:

GET /protected HTTP/1.1  
Host: example.org  
Date: Tue, 10 Apr 2018 10:30:32 GMT  
x-test: Hello world  
Cache-Control: max-age=60  
Cache-Control: must-revalidate  

For the HTTP request headers above, the corresponding signature string is:

(request-target): get /protected  
host: example.org  
date: Tue, 10 Apr 2018 10:30:32 GMT  
cache-control: max-age=60, must-revalidate  
x-test: Hello world  

Note: For the purposes of signature construction, the URL as seen by the service is "/jobs", so when providing the (request-target), it should be: (request-target): post /jobs.

Signature creation

In order to create a signature, a client must:

1. Create the signature string as described in signature string construction;

2. The algorithm and shared secret associated with keyId must then be used to generate a digital signature on the signature string;

3. The signature is then generated by base 64 encoding the output of the digital signature algorithm.

Supported algorithms

Currently supported algorithm names are:

• hmac-sha1
• hmac-sha256
• hmac-sha512

v1.1