Integration prerequisites¶

Complete the applicable onboarding steps with uCheck before connecting an API client. The setup depends on the endpoints, products, and organisation units you intend to use.

This guide separates the setup required before your first UAT request from the testing and approval required before Live access. Your uCheck representative will confirm which steps apply to your integration.

Before your first UAT request¶

Register your organisation and API services. Confirm the submission, results, status, or report services that your client will use.
Confirm the Head Offices and organisation units. In UAT, uCheck issues one key per Head Office (HO). In Live, keys are issued per organisation unit, so larger organisations may receive multiple Live keys.
Confirm endpoint and product access. The required services, check products, and options such as Digital ID must be enabled for the account.
Supply your source IP addresses. Give uCheck the public outbound IP address or addresses that will call UAT so they can be registered for firewall access and request logging.
Receive UAT credentials. Do not use example keys from this documentation; uCheck will issue working credentials for your organisation and environment.
Use the correct endpoint version. The retained endpoints are individually versioned as v1 or v2; use the version documented for each endpoint.

Note

Account creation does not necessarily enable every API or product. Confirm the complete list of endpoints and products you need with your uCheck representative before testing.

Credentials and environments¶

UAT and Live use different hosts and separately issued keys. A UAT key does not work against Live, and a Live key must not be used for test submissions.

v2 credentials¶

The retained v2 endpoints are individually versioned as v1 or v2. They normally receive an encrypted organisation key in the request body and use mixed XML or JSON contracts.

In UAT, uCheck issues one key per Head Office (HO). In Live, keys are issued per organisation unit, so an integration acting for several units may receive multiple Live keys. Confirm which environment, Head Office, or organisation unit each key belongs to. uCheck may also issue an account name and password for the HR Platform; API requests use the issued API key in the format required by the endpoint.

Treat every key as a secret:

store it in a server-side secret store;
do not commit it to source control or put it in client-side code;
do not log it or include it in support screenshots; and
contact your uCheck representative if it must be rotated or reissued.

See Authentication for key placement and Endpoint versions for the endpoint families.

Account and product configuration¶

Confirm that the account is enabled for each service your client calls. Results, Result Report, Status, and Barred Results access may be enabled separately. A valid key does not by itself guarantee access to every service.

For submission endpoints, confirm that each required check product is active on the account. Add Applicant Request rejects products that are not enabled, and Digital ID must also be available to the account before it can be requested.

UAT acceptance before Live¶

Use UAT for integration and acceptance testing. Do not send test submissions to Live. If further testing is needed after go-live, contact uCheck to arrange it.

These are the acceptance paths for the retained v2 submission APIs:

API	Documented UAT acceptance path
Add Applicant / Add Application	Supply sample XML for review; submit it after UAT access is granted; complete the further staged application scenarios; verify receipt and allocation of pushed results if that is part of the agreed integration; complete QA/internal sign-off and sign the applicable terms before Live access. uCheck may request further testing.
Add Applicant Request	Submit five test requests to a known email address, confirm receipt of the email and returned `tracking_id`, then continue to the next API test or receive Live keys if this is the only API being integrated. The links in the test emails are not expected to work.

The detailed XML scenarios remain in the Add Applicant test schedule; they are not duplicated here.

For Results, Result Report, Status, Barred Results, and other enabled services, confirm the required UAT evidence with your uCheck representative. Their source specifications require service registration and IP allowlisting but do not define one common fixed acceptance schedule.

Live credentials are issued only after the applicable testing and approvals are complete.

Client implementation readiness¶

Before requesting Live access, make sure the client:

generates stable, unique customer or application references wherever the endpoint requires them;
prevents accidental duplicate submissions — some submission APIs process duplicates rather than detecting them;
respects the limit documented for each endpoint instead of applying one global request rate;
serialises requests and controls retries where parallel or repeat requests are restricted;
handles authentication, validation, throttling, maintenance, and unexpected server errors, including HTTP 401/403, 429, 503, and endpoint-specific error bodies; and
records enough non-sensitive request context to investigate failures without recording API keys or applicant data unnecessarily.

A request rejected for validation or throttling should not be retried unchanged. Correct the payload or wait for the endpoint’s documented retry window. See the individual endpoint guide for its exact limits and error contract.

Next steps¶

Review Authentication.
For an existing integration, see the v2 Endpoints and Endpoint versions.
Follow each selected endpoint guide for its request, response, validation, rate-limit, and error details.

Integration prerequisites¶

Before your first UAT request¶

Credentials and environments¶

v2 credentials¶

Account and product configuration¶

UAT acceptance before Live¶

Client implementation readiness¶

Pre-call checklist¶

Before UAT¶

Before Live¶

Next steps¶