# Get Barred Results

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

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

```{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 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")*

```json
{
  "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](#response-description))
  and the `issueDate`.
- If there are no matching applications you will receive a `[]` blank array
  response.

### Example 1 – Matches

```json
{
  "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

```json
[]
```

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

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

### Missing method

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

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

### Invalid or missing date

```json
{
  "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

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

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

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

### The company has not been enabled

```json
{
  "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

```json
{
  "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 |