# Get Status

:::{tip}
**API reference:**
{{ swagger_v2_link }}.
:::

## Overview

The Get Status API returns the current **processing status** of your in-progress DBS Basic and DBS Standard / Enhanced applications, as JSON. Authenticate with your unique organisation **key** in the JSON body.

Prior to use of any API endpoint, a company account must be setup and location IP address registered such that it can be entered into the uCheck firewall / be used for logging requests.

This document outlines the status API included within the uCheck HR Platform, describing the service itself and the requirement that must be fulfilled to use this service.

You will be issued one key per organization you wish to collect status information.

### Rate limiting

You may make **only one request per 10 minutes**; a repeat request within that window is rejected with a JSON error. If you make more than 4 requests per second the IP is locked out for 60 minutes and each request receives an HTTP 429 response.

### Overview diagram

Below is a flow chart of the status process.

```{mermaid}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'system-ui, -apple-system, Helvetica, Arial, sans-serif','fontSize':'15px','lineColor':'#f28e00','primaryColor':'#0094dd','primaryTextColor':'#ffffff','primaryBorderColor':'#112e51'}}}%%
flowchart TD
    A([Customer registers for the<br/>uCheck getStatus API]):::endpoint
    B[Customer makes a JSON request<br/>to the API endpoint]:::step
    C([Customer receives a<br/>JSON response]):::endpoint
    A ==> B ==> C

    classDef endpoint fill:#112e51,stroke:#0094dd,stroke-width:2px,color:#ffffff,rx:8,ry:8;
    classDef step fill:#0094dd,stroke:#112e51,stroke-width:2px,color:#ffffff,rx:8,ry:8;
```

## Process explanation

- Customer registers with uCheck for the 'Get Status Service'

- Customer provides IP address(es) to be white listed

- Customer makes a JSON request including

  - Unique organization key

- ALL statuses will be returned for all DBS Basic applications currently processing. You will not receive a status response for applications that have either not yet been processed by uCheck or that have results issued against them.

## Request format

| Property | Value |
|----------|-------|
| API URL endpoint | `https://api.ucheck.co.uk/getStatus/v2` |
| Request type | `POST` |
| POST data required | Key = `json`, Value = JSON-encoded object as described below |

- Status are raw 'POSTED' in the form of a JSON encoded string

- JSON request must include the following key pairs

  - key*: (Unique organization key)*

i.e.

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY"
}
```

NOTE: the above is example, the key is just for display and not a valid working one. You will be issued your own working key(s).

## Response format

- We will issue a HTTP 200 code on a successful request.

- The response contains:

  - Key field, which is uCheck's unique HR Reference code

  - The check type the status is for (i.e. Basic)

  - The current status (See section 2.3)

  - Processing E0 code (DBS status only)

- If there are no applications currently processing you will receive a [] blank array response.

### Example 1

```json
{
  " HR00000001": {
    "basic": {
      "status": "Police National Computer Search",
      "ApplicationFormReference": "E0000000001"
    }
  },
  "HR00000002": {
    "basic": {
      "status": "Application Received",
      "ApplicationFormReference": "E0000000002"
    }
  },
  "HR00000003": {
    "dbs": {
      "status": "Application Received",
      "ApplicationFormReference": "E0000000003"
    }
  }
}
```

### Example 5 – No matches

```json
[]
```

The above is a blank JSON array.

## Status descriptions

A successful response is a JSON object keyed by uCheck HR reference. Each entry
contains one check-type object (`basic` or `dbs`) describing the current status.

### Status header (Basic)

| Field | Example | Description |
|-------|---------|-------------|
| *(object key)* | `"HR000000001"` | uCheck's unique HR reference code for this applicant. |
| `basic` | *(object)* | Type of check the status response applies to. |
| `status` | `"Application Received"` | Current status — one of the values below. |
| `ApplicationFormReference` | `"E0000000001"` | DBS only: tracking code supplied to uCheck by the DBS. |

Possible `status` values (Basic):

- **Submitted** — sent to the DBS and awaiting acknowledgment from them.
- **Application Received** — application received and accepted by the DBS; an E0 code has been issued and it will progress through the stages.
- **Police National Computer Search** — application details are being checked against the PNC for possible matches.
- **Assemble Certificate** — final quality and assurance checks by the DBS prior to the final result being issued.
- **No Record Found for Details Provided** — application has been withdrawn DBS side.

### Status header (DBS Standard and Enhanced)

| Field | Example | Description |
|-------|---------|-------------|
| *(object key)* | `"HR000000001"` | uCheck's unique HR reference code for this applicant. |
| `dbs` | *(object)* | Type of check the status response applies to. |
| `status` | `"Application Received"` | For DBS standard & enhanced only one stage exists — **Application Received**: application received and accepted by the DBS and an E0 code issued. |
| `ApplicationFormReference` | `"E0000000001"` | DBS tracking code (the E0 number). |

<span class="uc-important">From the above header information, the applicant should be uniquely identified and matched to an entry within the customer database.</span>

## Optional flags

Optional Flags can be provided to customize the date period statuses are returned for and to return extra information fields for billing purposes (this will indicate the level of check and therefore the cost). This apply to standard/enhanced level checks only, not Basic.

### Date

A date can be specified for the applications you would like to return the status for. This applies to DBS standard/enhanced checks only, not basic level. This is enable filtering of E0 responses for a single day as this status for standard/enhanced will not change via the API whilst it is processing with the DBS. The E0 code can be used to create your own tracking page if you have all the required info (see Tracking Example). The status will be returned for the day the application was submitted to the DBS and the E0 code received which indicates the change of status to Application Received (by the DBS).

NOTE: Statuses are only returned for applications that are processing and not once a result has been issued. It is not possible to check the status for an E0 number retrospectively for an application which is complete.

If this flag is used all Basic statuses for processing apps will be returned regardless of the required date as these change during processing and the latest status will be returned.

Example:

Application is submitted to the DBS on the 1<sup>st</sup> of July 2020

Request

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "method": "date",
  "date": "2020-07-01"
}
```

Response

```json
{
  "HR00000001": {
    "dbs": {
      "status": "Application Received",
      "ApplicationFormReference": "E00000000001"
    }
  }
}
```

Tracking Example:

```xml
<form target="_blank" id="trackingForm" method="post" action="https://secure.crbonline.gov.uk/enquiry/enquirySearchAction.do">
<input type="hidden" name="applicationNo" id="applicationNo" value="" />
<input type="hidden" name="dateOfBirthDay" id="dateOfBirthDay"value="" />
<input type="hidden" name="dateOfBirthMonth" id="dateOfBirthMonth" value="" />
<input type="hidden" name="dateOfBirthYear" id="dateOfBirthYear" value="" />
</form>
```

In the example above DOB is needed, broken down into day, month, and year, to the relevant field and applicationNo which is the E0 number returned in ApplicationFormReference.

### ShowCostFields

Using this flag will return extra information regarding standard/enhanced applications only as Basic applications are a fixed price product and do not have options.

The extra information returned is as follows, the level (standard or enhanced), volunteer (y/n) and adult isa first barred list (y/n) as set when submitted to the DBS. All these fields affect the cost of an application.

Example:

Request

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "showCostFields": "true"
}
```

Response

```json
{
  "HR00000001": {
    "dbs": {
      "status": "Application Received",
      "ApplicationFormReference": "E0676294551",
      "level": "enhanced",
      "volunteer": "n",
      "barredlist": "n"
    }
  }
}
```

## Error responses

All error responses will be sent with an HTTP 400 Bad Request response header

### No JSON provided

```json
{
  "response": {
    "success": "false",
    "error": "no json data provided"
  }
}
```

You need to ensure you are providing json via a raw POST request

### Invalid key element

```json
{
  "response": {
    "success": "false",
    "error": "invalid key element supplied"
  }
}
```

The key element you have supplied is not valid. Please ensure you have been issued a valid key by uCheck and are not using a sample from this document are providing this correctly in your request.

### Request rejected

```json
{
  "response": {
    "success": "false",
    "error": "request rejected, last request at 2018-07-24 03:31:27, requests can only be made every 600 seconds"
  }
}
```

You are trying to make a repeat result request too soon after the last successful request. You can only make result requests every 10 minutes.

### Company account disabled

```json
{
  "response": {
    "success": "false",
    "error": "company account disabled"
  }
}
```

The company account that is being used is not enabled for API use.

### HTTP 429

We throttle all requests to 4 per second. If you make too many requests within this period, we will return a http 429 code and restrict access for 60 minutes.

## Version history

| Version | Date | Description |
|---------|------|-------------|
| 1.0     | Initial Draft | Initial draft                     |
| 1.1     | 01/07/2019    | Split out individual end points   |
| 1.2     | 20/01/2020    | Added DBS status, endpoint now v2 |
| 1.3     | 02/07/2020    | Additional of flags in request    |