Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
---
title: API reference
weight: 6
last_reviewed_on: 2020-11-11
review_in: 6 months
---
# API reference
The Document Checking Service (DCS) API:
* is based on [REST principles](https://restfulapi.net/)
* returns data in [JSON format](https://www.rfc-editor.org/info/rfc8259)
* uses standard [HTTP status response codes](/status-response-codes/#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](/api-reference/#check-the-dcs-status)
* [check whether a passport is valid](/api-reference/#check-whether-a-passport-is-valid)
You can [read further guidance about what responses mean when making a DCS check](/integrating-with-the-dcs/#understand-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](/sign-and-encrypt-a-DCS-payload/#sign-and-encrypt-a-dcs-payload).
### Interpret the status response
If the DCS is available, the JSON response body will be similar to:
```json
{
"available":true,
"scheduledOutages":[]
}
```
The `scheduledOutages` field is a legacy field provided for compatibility reasons for older clients and is always empty for participants of the DCS pilot.
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](/api-reference/#understand-rate-limits-in-the-dcs)
* `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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](/sign-and-encrypt-a-DCS-payload/#build-a-plain-json-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](https://www.w3.org/TR/NOTE-datetime), 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:
```json
{
"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][status-response-codes] for successful requests. This response is a JSON payload in a [signing and encryption wrapper](/sign-and-encrypt-a-DCS-payload/#sign-and-encrypt-a-dcs-payload).
If the requests are not successful, the DCS will return a [HTTP response code][status-response-codes] to indicate why the request was not successful.
| 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. |
### Receiving a `valid: true` response
A `valid: true` response means:
* all the details on the passport, for example, first names or date of birth, exactly match the details held in Her Majesty’s Passport Office (HMPO)
* the passport is not marked as lost, stolen or cancelled in the HMPO database
* the passport has not expired, or expired no more than 18 months ago
#### Example payload for a valid passport
```json
{
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
"error": false,
"valid": true
}
```
### Receiving a `valid: false` response
A `valid: false` response means:
* one or more of the passport details, for example first names or date of birth, does not exactly match the details in the HMPO database
* the passport is marked as lost, stolen or cancelled in the HMPO database
* HMPO has not yet sent the passport to the holder
It’s possible for a valid passport to return a `valid: false` response. Check how to [reduce errors when using data from a passport chip](/reading-data-from-passport-nfc-chip/#reduce-errors-when-using-data-from-a-passport-chip).
#### Example payload for an invalid passport
```json
{
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
"error": false,
"valid": false
}
```
### Receiving an `error: true` response
An `error: true` response means the HMPO database is unavailable. You should wait a few seconds and then try again.
#### Example payload for a successful response containing an error
```json
{
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
"error": true,
"errorMessage": [
"Unplanned outage"
]
}
```
## 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:
* [`X-RateLimit-Limit`](https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html#rfc.section.3.1): the maximum number of requests you can make in the current time window
* [`X-RateLimit-Remaining`](https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html#rfc.section.3.2): the remaining number of requests you can make in the current time window
* [`X-RateLimit-Reset`](https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html#rfc.section.3.3): the time in seconds you have to wait until your usage resets
### 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`][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](/support).
<%= partial "partials/links" %>