Get started

Quickstart

Your first check takes 10 seconds: copy the code in step 2 and run it. It uses your sandbox key, which returns test data and never uses one of your checks.

Using a coding agent? Paste this into Claude Code, Cursor or Copilot and it will do the steps below for you. See Build with an agent

Prompt

Add UK right-to-work checks to this project using the Check Share Code API. Follow the quickstart: https://checksharecode.co.uk/docs/quickstart.md. Read my API key from the CHECKSHARECODE_API_KEY environment variable (sandbox keys are at https://checksharecode.co.uk/app/keys). Test it with share code AA1AA1AA1 and date of birth 1990-01-01.

1Get your sandbox key

Every account gets one when it signs up, on API keys. Put it in an environment variable called CHECKSHARECODE_API_KEY.

Sign up free and your sandbox key is filled in here and in every example. The examples read it from CHECKSHARECODE_API_KEY.Log in

2Make a call

Send the applicant's share code, their date of birth and your company name. With a sandbox key, use one of the test codes in step 4.

curl https://checksharecode.co.uk/api/check \
  -H "authorization: Bearer $CHECKSHARECODE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "share_code": "AA1AA1AA1",
    "date_of_birth": "1990-01-01",
    "company_name": "Acme Ltd"
  }'

3Read the response

outcome is ACCEPTED or REJECTED. Keep reference and the PDF as your record of the check. On a live check, photo_data_url and pdf_data_url hold the applicant's photo and the gov.uk PDF. The sandbox returns null for both.

200 OK

{
  "outcome": "ACCEPTED",
  "title": "Right to work",
  "name": "ALEX TEST SAMPLE",
  "date_of_birth": "1990-01-01",
  "nationality": "Indian",
  "permission_type": "Skilled Worker visa",
  "start_date": "2024-01-01",
  "expiry_date": "2027-01-01",
  "conditions": ["The applicant can work for the sponsoring employer in the role recorded."],
  "restrictions": [],
  "reference": "WE-EXAMPLE-12",
  "share_code": "AA1AA1AA1",
  "photo_data_url": null,
  "pdf_data_url": null,
  "checked_at": "2026-09-27T10:14:03.000Z"
}

4Try every outcome with test codes

In the sandbox any valid date of birth works. Each code below returns a fixed answer, so you can build your error handling before going live.

share_code	Status	You get
AA1AA1AA1	200	ACCEPTED, Skilled Worker visa with an expiry date
BB2BB2BB2	200	REJECTED, with a restriction
CC3CC3CC3	404	NOT_FOUND: gov.uk doesn't recognise the code
DD4DD4DD4	404	DOB_MISMATCH: code found, date of birth wrong
EE5EE5EE5	502	GOVUK_UNEXPECTED: gov.uk had a problem
Anything else	200	ACCEPTED, indefinite leave to remain

5Go live

Create a live key under API keys and swap it in. The request stays the same: send the applicant's real share code and date of birth. Each live check that gets an answer from gov.uk uses one of your checks. The free plan includes 10 a month.

Field	What to send
share_code	The 9-character code the applicant gives you, letters and numbers, e.g. AB1CD2EF3. Spaces and lowercase are fine: ab1 cd2 ef3 works too.
date_of_birth	The applicant's date of birth as YYYY-MM-DD, e.g. 1990-01-01. It must match the share code, and the applicant must be at least 16.
company_name	Your organisation's name, 1–200 characters. gov.uk records it as the employer making the check.