Add Applicant Request¶

Tip

API reference: View the v2 OpenAPI definition ›.

Unlike Add Applicant / Add Application, 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.

%%{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 to uCheck via the API endpoint]:::step C{uCheck determines if request is valid}:::decision D[Rejection error response returned to customer]:::step E([End]):::endpoint F[Application request successful and email sent to applicant]:::step G[Success response sent 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:

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

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

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

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

{
  "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)¶

{
  "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)¶

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

Basic check supplier

DS Denotes Disclosure Scotland Check

Glossary¶

Field definitions have moved to the consolidated Glossary.

Version history¶

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