Skip to main content
Table of contents

API reference

The Document Checking Service (DCS) API is based on REST principles. It returns data in JSON format, and uses standard HTTP status response codes.

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:

Check the DCS status

You can check the status of the DCS by making a HTTP GET request to the service endpoint.

We recommend you use this endpoint to build appropriate levels of reliability into your service.

The DCS integration endpoint

The DCS integration endpoint is https://dcs-integration.ida.digital.cabinet-office.gov.uk/.

Request

GET: /checks/passport

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

Response

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

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

Please note the scheduledOutages field is deprecated and will always contain an empty array.

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

  • Limit exceeded - you have exceeded your allocated number of API calls
  • Unplanned outage - the DCS or HMPO are experiencing a period of unscheduled downtime

For example, during a unplanned outage, the response will be:

{
  "available": false,
  "message": "Unplanned outage",
}

available

Boolean field indicating if the DCS is available and serving requests.

message

A string explaining why the DCS is unavailable. For example, if there is an ongoing planned outage, the field will contain detail about the duration of the outage.

Check passport validity

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

Request

POST: /checks/passport

The HTTP header must contain Content-Type: application/jose.

For example, below is the structure of the JSON object in a request body without the signature and encryption wrapper. All fields in the JSON object are mandatory:

{
  "correlationId": "a16c296f-4f03-4f25-af32-91240b1e0da7",
  "requestId": "5d700930-c41b-4e99-92cd-e9517dce11c8",
  "timestamp": "1997-07-16T19:20:30.45+01:00",
  "passportNumber": "123456789",
  "surname": "Smith",
  "forenames": [
    "Bob",
    "Dave"
  ],
  "dateOfBirth": "1950-02-13",
  "expiryDate": "2020-01-01"
}

correlationId

String containing an RFC 4122 compliant Universally Unique Identifier (UUID) which ties together multiple requests in the same session.

requestId

String containing an RFC 4122 compliant UUID which identifies a single request within a session.

timestamp

String in ISO 8601 format which identifies when the request took place.

passportNumber

The number of the passport being checked, which is an integer between 1 and 899999999.

surname

String of maximum 30 characters containing the surname as on the passport. The surname must only contain the characters a-z, A-Z, space, hyphen, full stop and apostrophe.

forenames

List of strings containing the forenames on the passport. The concatenated strings, including spaces between forenames, must be maximum 30 characters. The forenames must only contain the characters a-z, A-Z, space, hyphen, full stop and apostrophe.

dateOfBirth

Birth date as on the passport in YYYY-MM-DD format.

expiryDate

The passport expiration date in YYYY-MM-DD format. Must be in the future or no more than 18 months in the past at the time you submit the request.

Response

A successful request is one that completes without error, regardless of whether the passport is valid or not.

The DCS returns a 200 HTTP response code for successful requests.

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

Example response body for a valid passport:

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

Example response body for an invalid passport:

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

Example response body for a successful response containing an error:

{
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
  "error": true,
  "errorMessage": [
    "Unplanned outage"
  ]
}

Example plain text response body for a planned outage:

Service passport check: Planned outage in progress finishing at 2019-10-24T03:00:00.000+01:00

correlationId

String containing an RFC 4122 compliant UUID which ties together multiple requests in the same session.

requestId

String containing an RFC 4122 compliant UUID which identifies a single request within a session. This is the request ID from the original request.

error

Boolean indicating if there was an error when checking the passport data.

valid

Boolean indicating if the passport is valid or not. This field is not included if there is an error.

errorMessage

A list of strings which describes the error. This field is present if there was an error processing the request.

Understand rate limits in the DCS

As a pilot participant, you’ll be subject to both:

  • an overall rate limit of 50 requests in any 10 second period - this is shared between all pilot participants
  • an individual rate limit of (300 / number of participants) requests in any 60 second period - for example if 10 participants join the pilot, you would have an individual rate limit of 30 requests in any 60 second period

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

Tracking your rate limit usage

The DCS provides information about your rate limit usage in HTTP response headers.

The DCS’s HTTP response headers contain information such as:

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 combined total traffic from all pilot organisations is over the overall rate limit
  • 429 (Too many requests) HTTP status code if you have gone over your individual rate limit

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

Understand quotas in the DCS

Each organisation connected to the DCS for the pilot will have a quota of checks for the DCS. This quota is a fixed limit on how many checks the organisation can make in DCS production during the pilot.

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.

You can see your quota usage in the HTTP headers when you receive passport validity responses from the DCS.

  • DCS-Quota-Limit is the total number of checks you’ll be able to make as part of the DCS pilot
  • DCS-Quota-Remaining is the number of checks you have remaining
This page was last reviewed on 29 May 2020.