Skip to main content
Table of contents

API reference

The Document Checking Service (DCS) API:

This section describes the calls you can make to the DCS API, along with example requests and possible responses.

Using the DCS API you can:

You can read further guidance about what responses mean when making a DCS check.

Check the DCS status

You can check the status of the DCS which helps you build a fallback plan if the DCS is unavailable.

Make a status request

GET /checks/passport

The request body for a DCS status check is empty and therefore does not require the signature and encryption wrapper.

Interpret the status response

If the DCS is available, the JSON response body will be similar to:

{
  "available":true,
  "scheduledOutages":[]
}

If the DCS is unavailable, the message field in the response describes the reason. The reason for the DCS being unavailable can be:

  • Limit exceeded - you have exceeded your rate limit
  • Unplanned outage - the DCS or Her Majesty’s Passport Office (HMPO) is experiencing a period of unscheduled downtime
Field Type Description
available boolean Indicates if the DCS is available and serving requests.
scheduledOutages array A list of upcoming scheduled outages, which is empty if there are no outages scheduled.
message string Explains why the DCS is unavailable. For example, if there is an ongoing planned outage, the field will contain details of the outage duration.
scheduledOutages.start string Indicates when an outage is scheduled to start. Will be in ISO 8601 format, for example 2020-01-01T12:30:00.000Z.
scheduledOutages.end string Indicates when an outage is scheduled to end. Will be in ISO 8601 format, for example 2020-01-01T12:30:00.000Z.
scheduledOutages.message string Indicates the reason for the scheduled outage.

Check whether a passport is valid

You can use the DCS API to check if a passport is valid.

Make a passport validity check request

POST /checks/passport

Request HTTP headers must include Content-Type: application/jose.

The request body should be a DCS payload.

Field Type Description
correlationId string Contains an RFC 4122-compliant Universally Unique Identifier (UUID) which ties together multiple requests in the same session.
requestId string Contains an RFC 4122-compliant UUID which identifies a single request within a session.
timestamp string When your client makes the request. Must be in ISO 8601, for example 2020-01-01T12:30:00.000Z.
passportNumber string The number on the passport. This is between 1 and 899999999.
surname string The surname on the passport must be maximum 30 characters and only contain the characters a-z, A-Z, space, hyphen, full stop and apostrophe.
forenames array A list containing the forenames on the passport. The total length of all forenames must be maximum 30 characters, including spaces between the forenames. The forenames must only contain the characters a-z, A-Z, space, hyphen, full stop and apostrophe.
dateOfBirth string Birth date on the passport in YYYY-MM-DD format.
expiryDate string The passport expiration date in YYYY-MM-DD format. Must be no more than 18 months in the past at the time you submit the request.

The DCS validates each field before forwarding the evidence check to HMPO. For example, if the requestId field was not a valid UUID, you would receive a response similar to:

{
  "error": true,
  "errorMessage": [
    "validation: requestId: must be in universally unique identifier (UUID) format"
  ],
  "correlationId": "15ac0617-2654-4886-9cff-eaac3a47ae99",
  "requestId": "not-a-valid-uuid"
}

Interpret the passport validity response

A successful request completes without any errors, regardless of whether the passport is valid or not.

The DCS returns a 200 HTTP response code for successful requests. This response is a JSON payload in a signing and encryption wrapper.

If the requests are not successful, the DCS will return a HTTP response code to indicate why the request was not successful.

You can read further guidance about what responses mean when making a DCS check.

Example payload for a valid passport

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
  "error": false,
  "valid": true
}

Example payload for an invalid passport

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
  "error": false,
  "valid": false
}

Example payload for a successful response containing an error

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
  "error": true,
  "errorMessage": [
    "Unplanned outage"
  ]
}
Field Type Description
correlationId string Contains the same correlationId provided in the request, which is a RFC 4122-compliant UUID.
requestId string Contains the same requestId provided in the request, which is a RFC 4122-compliant UUID.
error boolean Indicates if there was an error when checking the passport data.
valid boolean Indicates if the passport is valid or not. This field is not included if there is an error.
errorMessage array A list of error messages which indicate why there was an error processing the request. This field is only included if there is an error.

Understand rate limits in the DCS

The DCS handles up to 50 requests every 10 seconds. This rate limit is divided between the pilot participants.

Each participant will have a fixed number of requests over a 60 second period, equal to 300 divided by the number of participants. For example, if there are 10 participants, each would have an individual rate limit of 30 requests per 60 seconds.

These rate limits may change over the course of the pilot.

Tracking your rate limit usage

The DCS provides rate limit information within the following HTTP response headers:

Exceeding rate limits

When you exceed the rate limit, the DCS returns a:

  • 503 Service Unavailable HTTP status code if, at the time you submit a request, the total traffic from all pilot organisations is over the rate limit
  • 429 Too Many Requests HTTP status code if you have exceeded your individual share of the limit

In both cases, the Retry-After HTTP response header specifies how many seconds you should wait before retrying.

Understand your quota in the DCS

Each organisation will have an allocated quota of checks in the DCS production environment during the pilot.

The DCS provides quota usage information within the following HTTP response headers:

  • DCS-Quota-Limit is the total number of checks you’ll be able to make within the DCS pilot
  • DCS-Quota-Remaining is the number of checks you have remaining

The DCS returns a 403 Forbidden HTTP status code if you have used up your quota. You will not be able to make DCS checks after this point. If you need more advice or help with your quota, contact the DCS helpdesk.

This page was last reviewed on 6 August 2020.