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"
}

Request validation error messages

If any of the request fields do not pass validation, the errorMessage field will contain an entry for each validation error detailing the cause of the error.

These are in the format validation: <field>: <message>, for example validation: requestId: must be in universally unique identifier (UUID) format.

We’ve listed all possible validation error messages for requests to the DCS’s passport checking endpoint, along with some example values that would cause each error message.

Request field Error message Example of what could cause the error message
requestId must be in universally unique identifier (UUID) format 1234
must not be empty <blank>
correlationId must be in universally unique identifier (UUID) format 1234
must not be empty <blank>
timestamp must be in ISO 8601 format YYYY-MM-DD’T'hh:mm:ss.SSSZ. For example, 2020-01-01T12:30:00.000Z 01-01-1990 12:00:00
must not be empty <blank>
is not recent enough 1990-01-01T12:00:00.000Z
passportNumber must be a numeric string between 1 and 899999999 999999999
must be a numeric string between 1 and 899999999 abcde
must not be empty <blank>
surname length must be between 1 and 30 characters long...name
must only contain the characters: a-z, A-Z, space, hyphen, full stop and apostrophe 12345
must not be empty <blank>
forenames must not be empty []
length must be between 1 and 30 characters ["long...", "...names"]
must only contain the characters: a-z, A-Z, space, hyphen, full stop and apostrophe [1234]
must not be empty <blank>
dateOfBirth must be in the format YYYY-MM-DD 01-01-1990
must not be in the future 3000-01-01
must not be empty <blank>
expiryDate must be in the format YYYY-MM-DD 01-01-1990
must not be more than 18 months in the past 1990-01-01
must not be empty <blank>

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 21 September 2020.