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.

Request

GET: https://<DCS-URI>/checks/passport

The <DCS-URI> will be supplied at a later date.

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

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":[]
}

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
  • Planned outage in progress finishing <TIMESTAMP> - the DCS or HM Passport Office (HMPO) are in a period of scheduled downtime, ending at <TIMESTAMP>
  • Unplanned outage - the DCS or HMPO are experiencing a period of unscheduled downtime

For example, during a planned outage, the response is similar to:

{
  "available": false,
  "message": "Planned outage in progress finishing 2019-09-12T00:00:00.000Z",
  "scheduledOutages":
    [
      {
        "start":"2019-09-05T00:00:00.000Z",
        "end":"2019-09-12T00:00:00.000Z",
        "message":"Maintenance work is underway."
      }
    ]
}

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.

scheduledOutages

A list of upcoming scheduled outages. The list is empty if there are no outages.

scheduledOutages.start

String in ISO 8601 format indicating when an outage is scheduled to start.

scheduledOutages.end

String in ISO 8601 format indicating when an outage is scheduled to end.

scheduledOutages.message

String indicating the reason for the scheduled outage.

Check passport validity

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

Request

POST: https://<DCS-URI>/checks/passport

The <DCS-URI> will be supplied at a later date.

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": "550e8400-e29b-41d4-a716-446655440000",
  "requestId": "550e8400-e29b-41d4-a716-446655440003",
  "timestamp": "1997-07-16T19:20:30.45+01:00",
  "clientId": "clientName",
  "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.

clientId

String which is an unique identifier issued by the DCS team.

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.

Response

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

The DCS returns a:

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.

This page was last reviewed on 29 October 2019.