Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
215 lines (151 sloc) 6.15 KB
---
title: API reference
weight: 6
last_reviewed_on: 2019-10-29
review_in: 3 weeks
---
# API reference
The Document Checking Service (DCS) API is based on [REST principles][REST]. It returns data in [JSON format][JSON], and uses standard [HTTP 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:
* [see the operational status of the DCS][check-status]
* [check passport validity][check-passport]
## 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][wrapper].
### Response
If the DCS is available, the JSON response body will be similar to:
```json
{
"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:
```json
{
"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, this is the structure of the JSON object in a request body without the [signature and encryption wrapper][wrapper]:
```json
{
"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"
}
```
Surname and forename values must only be comprised of the characters a-z, A-Z, space, hyphen, full stop and apostrophe.
All Universally Unique Identifier (UUID) fields must be in RFC 4112 format.
#### correlationId
String containing an RFC 4122 compliant UUID which ties together multiple requests in the same session.
#### requestId
String containing a 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 a 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.
#### forenames
List of strings containing the forenames on the passport. The concatenated strings, including spaces between forenames, must be maximum 30 characters.
#### 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:
* `200` [HTTP response code][status-response-codes] for successful requests
* `503` [HTTP response code][status-response-codes] if HMPO is having a planned outage
Example response body for a valid passport:
```json
{
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"requestId": "af47ddc1-faa9-42fe-be1f-8131df114713",
"error": false,
"valid": true
}
```
Example response body for an invalid passport:
```json
{
"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:
```json
{
"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.
<%= partial "partials/links" %>
You can’t perform that action at this time.