# Add Applicant Request

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

Unlike [Add Applicant](add-applicant.md) / [Add Application](add-application.md),
which submit a full application, Add Applicant Request **emails an invitation
link** to the applicant, who then completes their own forms. It authenticates
with an encrypted **company** key supplied in the JSON body.


## Overview

This document outlines the 'Add Applicant Request' API service which is part of the uCheck HR Platform, describing the service itself and the requirement that must be fulfilled to use this service.

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.

### Overview diagram

Below is a flow chart of the API 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([uCheck 'Add Applicant Request' API]):::endpoint
    B[Customer submits application request<br/>to uCheck via the API endpoint]:::step
    C{uCheck determines if<br/>request is valid}:::decision
    D[Rejection error response<br/>returned to customer]:::step
    E([End]):::endpoint
    F[Application request successful<br/>and email sent to applicant]:::step
    G[Success response sent<br/>to customer]:::step
    H([End]):::endpoint

    A ==> B ==> C
    C -- Failure --> D --> E
    C -- Success --> F ==> G ==> H

    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;
    classDef decision fill:#f28e00,stroke:#112e51,stroke-width:2px,color:#ffffff;
```

### Process explanation

- Customer registers with uCheck for the 'Add Applicant API'

  - Customer will need to supply uCheck with a list of IP's they will use to connect to the UAT environment.

  - Customer will be issued with a unique 'key' which is required to be submitted with every request as a means of customer identification. (On the live system you will be issued one key per unique organization entity)

  - The customer will be expected to submit 5 test requests to a known email address where they will confirm receipt of the email and the returned tracking_id (note links in the email will not work).

  - On successful completion of this, the customer will either move onto testing the next API in the process, or if this is to be the only API used, live keys will be issued to access the Live end point.

  - NOTE: the live endpoints should not be used to make test submissions, if you wish to make test requests please contact uCheck support team who will arrange further testing for you.

- Customer Responsibilities

  - All specified request details, as per this document, must be complied with.

  - The customer MUST supply a 'unique applicant ID' per request.

    - It is the customers responsibility to maintain the 'uniqueness' of this ID.

  - The customer MUST NOT flood the service with requests, in the event of uCheck detecting any irregular activity the requesting account will be disabled.

  - The customer MUST control the requests made to the system. If too many requests are made at one time you will receive a HTTP 403 error. Requests are limited to 4 per second.

  - Duplicate requests are not detected and will be processed.

  - If uCheck detect multiple duplicate requests through routine log reviews the requesting account may be disabled.

### Request submission

| Property | Value |
|----------|-------|
| API URL endpoint | `https://api.ucheck.co.uk/addApplicantRequest/v2` |
| Request type | `POST` |
| POST data required | Key = `json`, Value = JSON-encoded object with the applicant request details |

Submission is a `POST` request with a single POST parameter named `json`,
containing a JSON-encoded object with the applicant request details.

- At least one product must be selected; a request with no selections returns an error.
- You cannot add more products once the applicant has completed the forms.

A minimal request supplies the applicant details plus at least one product:

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "forename": "John",
  "surname": "Smith",
  "email": "john.smith@email.com",
  "uniqueid": "abc123456",
  "applicantpay": "n",
  "dbscheck": "y",
  "dbschecklevel": "enhanced"
}
```

#### Request fields

| Field | Required | Values | Description |
|-------|----------|--------|-------------|
| `key` | Yes | as supplied | Encrypted organisation key issued by uCheck. |
| `forename` | Yes | text | Applicant forename. |
| `surname` | Yes | text | Applicant surname. |
| `email` | Yes | email address | Applicant email address (where the invitation is sent). |
| `uniqueid` | Yes | text, 1–100 chars | Your own unique reference for the application. |
| `applicantpay` | Yes | `y` / `n` | Whether the applicant pays for the checks during the application. |
| `dbscheck` | Optional | `y` / `n` | Request a DBS Standard / Enhanced check. |
| `dbschecklevel` | Required if `dbscheck=y` | `standard`, `enhanced`, `enhanced-isa`, `standard-vol`, `enhanced-vol`, `enhanced-isa-vol` | Level of DBS check. |
| `basiccheck` | Optional | `y` / `n` | Request a Basic disclosure check. |
| `basicchecksupplier` | Required if `basiccheck=y` | `dbs` / `ds` | Basic check supplier — DBS or Disclosure Scotland. |
| `dbsdigitalid` | Optional | `y` / `n` | Add Digital ID verification to a DBS / Basic check. |
| `dbsdrtwcheck` | Optional | `y` / `n` | Request a DBS Digital Right to Work check. |
| `drtwcheck` | Optional | `y` / `n` | Request a standalone Digital Right to Work check (no criminal record check). |
| `idcheck` | Optional | `y` / `n` | Request an Identity Check. |
| `achcheck` | Optional | `y` / `n` | Request an Adverse Credit History check. |

Any field not listed above is rejected as an unknown field.

#### Valid product combinations

At least one product must be selected. The following rules are enforced — a
request that breaks any of them is rejected with a `400` error:

- **DBS and Basic are mutually exclusive** — you cannot set both `dbscheck=y` and
  `basiccheck=y` in the same request.
- **`dbscheck=y`** requires `dbschecklevel`.
- **`basiccheck=y`** requires `basicchecksupplier` (`dbs` or `ds`).
- **`dbsdigitalid=y`** is only valid alongside `dbscheck=y`, or `basiccheck=y`
  with `basicchecksupplier=dbs`. It is **not** valid with `basicchecksupplier=ds`.
- **`dbsdrtwcheck=y`** requires `dbsdigitalid=y`.
- **`drtwcheck=y`** is the standalone Right to Work product. It cannot be
  combined with `dbsdrtwcheck`, `dbscheck` or `basiccheck` (use `dbsdrtwcheck`
  when a criminal record check is also needed), so `dbsdigitalid` must be
  omitted or `n`.
- Each requested product must be **enabled on your account**, and Digital ID must
  be available for your account to use `dbsdigitalid`.
- Products that uCheck has **disabled or deprecated** are rejected even when they
  are enabled on your account, with the error `Product … is no longer available`.

#### Example requests

DBS Enhanced check with optional DBS Digital ID, where the applicant is requested
to complete their ID check digitally:

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "forename": "John",
  "surname": "Smith",
  "email": "john.smith@email.com",
  "uniqueid": "1111111111",
  "applicantpay": "n",
  "dbscheck": "y",
  "dbschecklevel": "enhanced",
  "dbsdigitalid": "y"
}
```

DBS Basic check:

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "forename": "John",
  "surname": "Smith",
  "email": "john.smith@email.com",
  "uniqueid": "1111111111",
  "applicantpay": "n",
  "basiccheck": "y",
  "basicchecksupplier": "dbs"
}
```

Adverse Credit History, with the applicant requested to pay for the check:

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "forename": "John",
  "surname": "Smith",
  "email": "john.smith@email.com",
  "uniqueid": "1111111111",
  "applicantpay": "y",
  "achcheck": "y"
}
```

Standalone Digital Right to Work (DRTW) check, with no criminal record check:

```json
{
  "key": "YOUR_ENCRYPTED_API_KEY",
  "forename": "John",
  "surname": "Smith",
  "email": "john.smith@email.com",
  "uniqueid": "1111111111",
  "applicantpay": "n",
  "drtwcheck": "y"
}
```

### Response description

#### Success (HTTP 200)

```json
{
  "response": {
    "success": "true",
    "tracking_id": 11
  }
}
```

`tracking_id` is a unique identifier for the applicant request, which can be used
to track the applicant's progress.

#### Failure (HTTP 400)

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

The `error` field describes the reason for the failure.

### Data format

| **Value** | **Constraint** | **Constraint Value** | **Mandatory/Optional (M / O)** |
|----|----|----|----|
| key | As supplied | As supplied by uCheck | M |
| forename | Regular expression | /^[a-zA-Z '-]{1,60}+\$ | M |
| surname | Regular expression | /^[a-zA-Z '-]{1,50}+\$ | M |
| email | Regular expression | /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\[a-zA-Z]{2}+\$/ | M |
| uniqueid | Regular expression | /^[a-zA-Z0-9 '\\\]{1,100}+\$/ | M |
| applicantpay | y/n | /^[yn]{1}+\$/ | M |
| dbscheck * | y/n | /^[yn]{1}+\$/ | O |
| dbschecklevel | Must be in list | See appendix A | M – if dbscheck =y |
| idcheck | y/n | /^[yn]{1}+\$/ | O |
| achcheck | y/n | /^[yn]{1}+\$/ | O |
| basiccheck * | y/n | /^[yn]{1}+\$/ | O |
| basicchecksupplier | Must be in list | See appendix A | M – if basiccheck=y |
| dbsdigitalid | y/n | /^[yn]{1}+\$/ | O – only valid for DBS checks |
| dbsdrtwcheck | y/n | /^[yn]{1}+\$/ | O – requires dbsdigitalid=y |
| drtwcheck | y/n | /^[yn]{1}+\$/ | O – not valid with dbsdrtwcheck, dbscheck or basiccheck |

* Selection of DBS checks and Basic checks are mutually exclusive.\
Appendix A

#### DBS Level list

| Value            | Description                                       |
|------------------|---------------------------------------------------|
| standard         | Standard Level Check                              |
| standard-vol     | Volunteer Standard Level Check                    |
| enhanced         | Enhanced Level Check                              |
| enhanced-vol     | Volunteer Enhanced Level Check                    |
| enhanced-isa     | Enhanced Level Check With Adults Barred           |
| enhanced-isa-vol | Volunteer Enhanced Level Check With Adults Barred |

If you are unsure of the level of DBS check you need please query with our Customer Support Team.

2.  Basic check supplier

- DBS

- DS

* DS Denotes Disclosure Scotland Check

### Glossary

Field definitions have moved to the consolidated [Glossary](../glossary.md).

## Version history

| Version | Date | Description |
|---------|------|-------------|
| 1 |  |  |
| 2 |  | Mandate product selection. Updated endpoints for v2. Updated guidance. |