# Get Result

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

Returns all completed check results for your organisation on a given date (or
date range), as JSON keyed by uCheck HR reference. Authenticate with your unique
organisation **key** in the JSON body.

This endpoint must be enabled for your account by uCheck before it can be used.

## Overview

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

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

One unique key will be supplied per organisation unit. You may be issued with many keys depending on the size of your company, you should check with your uCheck representative if you are unsure on this.

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

```{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 GetResult service]):::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 'Results Service'

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

- Customer makes a JSON request including

  - Unique organization key

  - Method to check via (`date` or `daterange`)

  - Date to check for results

- ALL results will be returned for the date requested

## Request format

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

- Results 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/DateRange)*

  - date: *(yyyy-mm-dd*, *any historical date, including today's date)*

  - *OR fromdate/todate (yyyy-mm-dd, date cannot be older than 30 days from today)*

i.e.

Example 1, single date

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

Example 2, date range

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "method": "daterange",
  "fromdate": "2020-06-05",
  "todate": "2020-07-01"
}
```

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

  - A results section for each product selected for that application.

    - You get a response for an application only that has a result issued on the requested date or date range as defined in the JSON request.

    - You may get multiple product responses if two checks are completed on the same date or within the specified date range\
      (i.e. DBS and RTW are both completed on 2020-07-01 and this is the date you request, or they both complete within the date range you specify).

    - You will not get the results for date you request if not completed on the specified date or date range.\
      (i.e. HR0000001 has a results for DBS on 2020-07-01 and RTW 2020-07-02, if you requests the results for 2020-07-01 or date range 2020-06-05 to 2020-07-01 you will only get the DBS result)

- If there are no results for that date you will receive a [] blank array response.

### Example 1 – DBS Std / Enh

```json
{
  " HR00000001": {
    "customerUID": "",
    "forename": "Peter",
    "surname": "Brown",
    "email": "peter.brown@example.com",
    "dateOfBirth": "1988-06-07",
    "companyCode": "MGCARE",
    "dbs": {
      "disclosureNumber": "001234567890",
      "disclosureIssueDate": "2018-01-01 00:00:00",
      "disclosureType": "enhanced",
      "disclosureStatus": "clear"
    }
  },
  "HR00000002": {
    "customerUID": "",
    "forename": "Sarah",
    "surname": "Jones",
    "email": "sarah.jones@example.com",
    "dateOfBirth": "1988-06-07",
    "companyCode": "MGCARE",
    "dbs": {
      "disclosureNumber": "001234567891",
      "disclosureIssueDate": "2018-01-01 00:00:00",
      "disclosureType": "enhanced",
      "disclosureStatus": "wait"
    }
  }
}
```

### Example 2 – Basic Criminal (Disclosure Scotland and DBS)

```json
{
  " HR00000001": {
    "customerUID": "",
    "forename": "Peter",
    "surname": "Brown",
    "email": "peter.brown@example.com",
    "dateOfBirth": "1988-06-07",
    "companyCode": "MGCARE",
    "basic": {
      "basicDisclosureType": "Disclosure Scotland",
      "basicDisclosureNumber": "0400000220783435",
      "basicDisclosureIssueDate": "2018-01-01 00:00:00",
      "disclosureStatus": "clear"
    }
  },
  "HR00000002": {
    "customerUID": "",
    "forename": "Sarah",
    "surname": "Jones",
    "email": "sarah.jones@example.com",
    "dateOfBirth": "1988-06-07",
    "companyCode": "MGCARE",
    "basic": {
      "basicDisclosureType": "DBS Basic",
      "basicDisclosureNumber": "0000000123456789",
      "basicDisclosureIssueDate": "2018-01-01 00:00:00",
      "disclosureStatus": "clear"
    }
  }
}
```

### Example 3 – RTW

Returned for historic RTW checks only.

```json
{
  " HR00000001":
  {
    "customerUID" : "",
    "forename" : "Peter",
    "surname" : "Brown",
    "email" : "peter.brown@example.com",
    "dateOfBirth" : "1988-06-07",
    "companyCode" : "MGCARE",
    "rtw":
    {
      "rtwType" : "permanent",
      "WorkingLimitations" : "false",
      "rtwLimitationType" : "none",
      "rtwLimitationValue" : "0",
      "rtwDocuments":
      [
        {
          "rtwDocumentType" : "passport",
          "rtwDocumentExpiry" : ""
        }
        {
          "rtwDocumentType" : "other1",
          "rtwDocumentExpiry" : ""
        }
      ],
      "ElectronicVerification" : "true",
      "ElectronicVerificationStatus" : "SUCCESS",
      "rtwEmployerSig" : "John Smith",
      "rtwApplicantSig" : "Peter Brown",
      "rtwCompletionDate" : "2016-07-15 12:10:17"
    }
  },
  "HR00000002":
```

………

### Example 4 – Multiple Result

```json
{
  " HR00000001":
  {
    "customerUID" : "",
    "forename" : "Peter",
    "surname" : "Brown",
    "email" : "peter.brown@example.com",
    "dateOfBirth" : "1988-06-07",
    "companyCode" : "MGCARE",
    "rtw":
    {
      "rtwType" : "permanent",
      "WorkingLimitations" : "false",
      "rtwLimitationType" : "none",
      "rtwLimitationValue" : "0",
      "rtwDocuments":
      [
        {
          "rtwDocumentType" : "passport",
          "rtwDocumentExpiry" : ""
        }
        {
          "rtwDocumentType" : "other1",
          "rtwDocumentExpiry" : ""
        }
      ],
      "ElectronicVerification" : "true",
      "ElectronicVerificationStatus" : "SUCCESS",
      "rtwEmployerSig" : "John Smith",
      "rtwApplicantSig" : "Peter Brown",
      "rtwCompletionDate" : "2016-07-15 12:10:17"
    },
    "dbs":
    {
      "disclosureNumber" : "001234567891",
      "disclosureIssueDate" : "2018-01-01 00:00:00",
      "disclosureType" : "enhanced",
      "disclosureStatus" : "wait"
    }
  }
}
```

### Example 5 – No matches

```json
[]
```

The above is a blank JSON array.

## Response description

A successful response contains a **results header** identifying the applicant,
followed by one section per product that has a result on the requested date (or
within the requested date range).

### Results header

| Field | Example | Description |
|-------|---------|-------------|
| `uCheckReference` | `"HR000000123"` | uCheck's unique HR reference code for this applicant. |
| `customerUID` | `""` | A customer UID, if supplied to uCheck via a Request API when the application was started by the uCheck API process; otherwise blank. |
| `forename` | `"Peter"` | Applicant forename. |
| `surname` | `"Brown"` | Applicant surname. |
| `email` | `"peter.brown@example.com"` | Applicant email address. |
| `dateOfBirth` | `"1988-06-07"` | Applicant date of birth. |
| `companyCode` | `"MGCARE"` | Company requesting the checks. |

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

### DBS Result

| Field | Example | Description |
|-------|---------|-------------|
| `disclosureNumber` | `"001234567890"` | Disclosure number issued by DBS. |
| `disclosureIssueDate` | `"2018-01-01 00:00:00"` | Date of disclosure issue. |
| `disclosureType` | `"enhanced"` | Type of disclosure application (`standard` or `enhanced`). |
| `disclosureStatus` | `"clear"` | Disclosure status (`clear`, or `wait` i.e. wait to see the certificate). |

### Basic Result

| Field | Example | Description |
|-------|---------|-------------|
| `basicDisclosureType` | `"Disclosure Scotland"` | Basic check type (`Disclosure Scotland` or `DBS Basic`). |
| `basicDisclosureNumber` | `"0000000123456789"` | Basic disclosure number (issued by either Disclosure Scotland or DBS). |
| `basicDisclosureIssueDate` | `"2018-01-01 00:00:00"` | Basic disclosure issue date. |
| `disclosureStatus` | `"clear"` | Disclosure status (`clear`, or `wait` i.e. wait to see the certificate). |

### Right to Work Result

RTW can no longer be requested. This block is only returned for historic RTW
checks, so their results can still be retrieved.

| Field | Example | Description |
|-------|---------|-------------|
| `rtwType` | `"permanent"` | RTW type (`permanent` or `limited`). |
| `rtwWorkingLimitations` | `"false"` | Does the applicant have any working limitations? |
| `rtwLimitationType` | `"none"` | If working limitations are present, what are they (`none` or `hours`, i.e. number of hours allowed to work). |
| `rtwLimitationValue` | `"0"` | If a working limitation is present, its value (e.g. how many hours the applicant is allowed to work). |
| `rtwDocuments` | *(array)* | Details of all RTW documents uploaded to support this applicant (up to 20). `rtwDocumentExpiry` is only populated when `rtwType` is `limited` and the document is not of type `other`. See the example below. |
| `ElectronicVerification` | `"true"` | Was a document submitted for electronic verification? |
| `ElectronicVerificationStatus` | `"SUCCESS"` | If a document (e.g. a passport) was electronically verified, did it pass? (`FAILURE`, `SUCCESS` or `NOT TESTED`). |
| `rtwEmployerSig` | `"John Smith"` | eSignature of employer. |
| `rtwApplicantSig` | `"Peter Brown"` | eSignature of applicant. |
| `rtwCompletionDate` | `"2018-01-01 00:00:00"` | Date of RTW completion. |

`rtwDocuments` array format:

```json
"rtwDocuments": [
  {
    "rtwDocumentType": "passport",
    "rtwDocumentExpiry": ""
  },
  {
    "rtwDocumentType": "other1",
    "rtwDocumentExpiry": ""
  }
]
```

### Digital Right to Work Result (DRTW)

| Field | Example | Description |
|-------|---------|-------------|
| `rtwType` | `"Time Limited"` | RTW verification outcome (`Continuous`, `Time Limited`, `Rejected`, or empty). |
| `WorkingLimitations` | `"No"` | Whether the applicant has working limitations (`Yes` / `No`). |
| `rtwLimitationType` | `"yes"` | Indicates if working limitations are present — `yes`, `no` or empty. |
| `rtwLimitationValue` | `""` | Explanation of the limitations, if present. Can be empty. |
| `rtwDocumentType` | `"Passport"` | Document type used (`Passport`, `Sharecode`, or empty). |
| `ElectronicVerification` | `"true"` | Was a document submitted for electronic verification? |
| `ElectronicVerificationStatus` | `"SUCCESS"` | Verification outcome (`SUCCESS`, `FAILURE` or `NOT TESTED`). |
| `EmployersNextStep` | `"Imposter Check"` | What the employer should do next (`Check Documents` or `Imposter Check`). |
| `DateFollowUpCheckRequired` | `"2026-09-23 00:00:00"` | When the next check is required (present only when `rtwType` is `Time Limited`). |
| `DigitalIDProvider` | `"TrustID"` | The provider that performed the check (`TrustID`, `Yoti`, or empty). |
| `rtwCompletionDate` | `"2018-01-01 00:00:00"` | Date of RTW completion. |

### DBS Digital Right to Work Result (DBSDRTW)

| Field | Example | Description |
|-------|---------|-------------|
| `rtwType` | `"Time Limited"` | RTW type (`Time Limited`, `Rejected` or `Continuous`). |
| `WorkingLimitations` | `"No"` | Does the applicant have any working limitations? |
| `rtwLimitationType` | `"yes"` | Indicates if working limitations are present — `yes`, `no` or empty. |
| `rtwLimitationValue` | `"They can work in the UK until the date specified on the Home Office report."` | If a working limitation is present, the explanation of the limitations. Can be empty. |
| `ElectronicVerification` | `"true"` | Was a document submitted for electronic verification? |
| `ElectronicVerificationStatus` | `"SUCCESS"` | If a document was electronically verified, did it pass? (`FAILURE`, `SUCCESS` or `NOT TESTED`). |
| `EmployersNextStep` | `"Imposter Check"` | What the employer should do next. |
| `DateFollowUpCheckRequired` | `"2028-05-21 00:00:00"` | When the next check is required, or empty if not present. |
| `DigitalIDProvider` | `"TrustID"` | The provider that performed the check. Can be empty if not set. |
| `rtwCompletionDate` | `"2018-01-01 00:00:00"` | Date of RTW completion. |

### ACH Result

| Field | Example | Description |
|-------|---------|-------------|
| `ccjCount` | `"2"` | Count of any CCJs. |
| `ivaCount` | `"1"` | Count of any IVAs. |
| `bkyCount` | `"0"` | Count of any bankruptcies. |

### IDC Result

| Field | Example | Description |
|-------|---------|-------------|
| `overallStatus` | `"PASS"` | `PASS` or `FAIL`. |
| `onHALO` | `"1"` | Record on mortality list. |
| `addrOnElectoral` | `"0"` | Address is on the electoral roll if `1`. |
| `dobOnElectoral` | `"0"` | DOB is on the electoral roll if `1`. |
| `addrOnCreditList` | `"1"` | Address is on the credit list if `1`. |
| `dobOnCreditList` | `"1"` | DOB is on the credit list if `1`. |

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

### Element missing

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

Please ensure you are providing all elements are per the spec. The error will indicate which one it requires.

### Invalid date

```json
{
  "response": {
    "success": "false",
    "error": "invalid date 2018-55-01 provided"
  }
}
```

Please ensure you are passing valid dates and in the format yyyy-mm-dd

### Date greater than

```json
{"response":{"todate cannot be greater than 30 days from now (32 difference)"}
```

Please ensure you are passing valid dates for the fromdate/todate that is less than 30 days from today's date.

### 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    | Error info added        |
| 1.2     | 02/07/2020    | Added date range search |
| 1.3     | 28/02/2023    |                         |
| 1.4     | 19/05/2026    | Add ACH, IDC & DBSDRTW  |