Get Barred Results¶

Tip

API reference: View the v2 OpenAPI definition ›.

Overview¶

The Get Barred Results API returns barred-list results for applications whose results match a requested date, as JSON. Authenticate with your unique organisation key in the JSON body, supplying a method and date.

This document outlines the get barred results API included within the uCheck HR Platform, describing the service itself and the requirements that must be fulfilled to use this service.

Prior to use of either API endpoint, a company account must be set up and location IP address registered such that they can be entered into the uCheck firewall and used for logging requests.

You will be issued with one key for each organization that you wish to access the API.

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 process.

%%{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 getBarredResults 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 a representative of uCheck’s business development team and registers with uCheck for the ‘Get Barred Results’ API
Customer provides IP address(es) to be white listed
Customer makes a JSON request including
- Unique organization key
- Method
- Date
Statuses will be returned for all applications that have results matching the requested date.

Request format¶

Property	Value
API URL endpoint	`https://api.ucheck.co.uk/getBarredResults/v1`
Request type	`POST`
POST data required	Key = `json`, Value = JSON-encoded object with `key`, `method` and `date`

Status are raw ‘POSTED’ in the form of a JSON encoded string
JSON request must include the following key pairs
- key*: [“Unique organization key”]*
- method: “date” (date is the only method currently supported)
- date: [“date”] ( example “1999-01-29”)

{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "method": "date",
  "date": "2023-01-19"
}

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

Response format¶

A successful request returns HTTP 200.
Each entry contains your unique identifier (customerUID), your company code (companyCode), the result (see Response Description) and the issueDate.
If there are no matching applications you will receive a [] blank array response.

Example 1 – Matches¶

{
  "HR00000001": {
    "customerUID": "123456",
    "companyCode": "ORG1",
    "result": "no match found",
    "issueDate": "2023-02-13 12:49:39"
  },
  "HR00000002": {
    "customerUID": "234567",
    "companyCode": "ORG1",
    "result": "already complete",
    "issueDate": "2023-02-13 15:45:01"
  },
  "HR00000003": {
    "customerUID": "345678",
    "companyCode": "ORG1",
    "result": "await certificate",
    "issueDate": "2020-02-13 15:55:23"
  }
}

Example 2 – No matches¶

[]

The above is a blank JSON array.

Response description¶

A successful response is a JSON object keyed by uCheck HR reference. Each entry describes one applicant’s barred-list result.

Field	Example	Description
(object key)	`"HR00000001"`	uCheck’s unique HR reference code for this applicant.
`customerUID`	`"123456"`	Your unique ID for the application.
`companyCode`	`"ORG1"`	Your company code.
`result`	`"no match found"`	The barred-list result — one of the values below.
`issueDate`	`"2023-02-13 12:49:39"`	The date and time the result was issued.

Possible result values:

no match found
await certificate
wait
already complete

Note

await certificate and wait mean the same thing: you must wait to see the certificate before making a decision. Because the data is supplied manually by the DBS, either value may be returned.

Error responses¶

All error responses will be sent with an HTTP 400 “Bad Request Response” header.

Examples follow.

No JSON provided¶

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

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

Invalid key element¶

{
  "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, also that you are providing this correctly in your request.

Missing method¶

{
  "response": {
    "success": "false",
    "error": "element missing [method]"
  }
}

The “method”:”date” element is missing from the request json.

Invalid or missing date¶

{
  "response": {
    "success": "false",
    "error": "required date 'date:yyyy-mm-dd' must be specified when using date method"
  }
}

The date is missing or incorrectly formatted

Invalid format¶

{
  "response": {
    "success": "false",
    "error": "incorrectly formatted json request"
  }
}

The format of the request is not a valid json string.

Request rejected¶

{
  "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.

The company has not been enabled¶

{
  "response": {
    "success": "false",
    "error": "company account not enabled for api"
  }
}

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

Company account disabled¶

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

The company account has been suspended.

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