Quickstart

Which check are you building?

Each check has its own endpoint, and the same key runs all four, so you can build any of them. The three share code checks take the same test codes; driving licence has its own.

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. If it isn't set, get a sandbox key yourself with POST https://api.checksharecode.co.uk/v1/agent/signup (send your name and what we are building as name and use_case), store the api_key it returns in CHECKSHARECODE_API_KEY, and give me the claim_url so I can keep the key. Test it with share code AA1AA1AA1 and date of birth 1990-01-01. AA1AA1AA1 is a sandbox test code: it only works with the sandbox key. Keep tests on the sandbox key, and never send a test code with a live key (rtw_live_…): that runs a real gov.uk check, which finds no record and still uses one of my checks.

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.

2Make a call

Send the applicant's share code, their date of birth and your company name to POST /v1/check/right-to-work. With a sandbox key, use one of the test codes in step 4.

curl https://api.checksharecode.co.uk/v1/check/right-to-work \
  -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

For a share code check, 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 a sample photo of someone who does not exist and a sample PDF in the format of gov.uk's own, marked as a sandbox sample.

outcome is ACCEPTED or REJECTED. recheck_date is the day their permission ends: check again before then. It is null when their right to work has no end date.

{
  "outcome": "ACCEPTED",
  "title": "Right to work",
  "name": "ALEX TEST SAMPLE",
  "date_of_birth": "1990-01-01",
  "details": "They have the right to work in the UK from 1 January 2024 until 1 January 2030.",
  "nationality": null,
  "permission_type": null,
  "start_date": "2024-01-01",
  "expiry_date": "2030-01-01",
  "recheck_date": "2030-01-01",
  "conditions": ["The applicant can work for the sponsoring employer in the role recorded."],
  "restrictions": [],
  "reference": "WE-EXAMPLE-12",
  "company_name": "Acme Ltd",
  "check_date": "2026-09-27",
  "share_code": "AA1AA1AA1",
  "photo_data_url": "data:image/jpeg;base64,/9j/4AAQ…",
  "pdf_data_url": "data:application/pdf;base64,JVBERi0…",
  "checked_at": "2026-09-27T10:14:03.000Z"
}

4Try every outcome with test codes

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

On an asynchronous check, a timeout code (FF6FF6FF6, or a check code starting FFFF) fails with TIMEOUT: a share code check is retried first, like a live one, and a driving licence check never is, because its code may have reached DVLA. A busy code (GG7GG7GG7, or GGGG) gives the same answer as any other code there: an asynchronous check never gets BUSY, because it waits in the queue instead.

Realistic timing. Test codes answer at once, so your tests stay fast. To build your loading states and timeouts against how long a live check takes, send the header Prefer: sandbox-latency=realistic. Each check then waits as long as a live check that ended the same way, drawn from our recent live checks, so a NOT_FOUND comes back faster than a result, a driving licence check faster than a share code check, and BUSY at once. Few live driving licence checks have run yet, so their times are an estimate, from those and our own tests, until there are more. The response carries Preference-Applied: sandbox-latency=realistic. Up to 3 of your synchronous checks wait at a time; past that they answer at once, without that header. An asynchronous check stays queued for that time, with no limit. Live keys ignore the header, so you can leave it in.

5Go live

Create a live key under API keys and use it for real applicants. The request stays the same, but the test codes don't work with it: a live key sends every code to gov.uk, which finds no record for a test code, and that answer uses one of your checks. Keep your tests on the sandbox key, and send the live key only an applicant's real share code and date of birth. Each live check that gets an answer from gov.uk uses one of your checks, whichever check it is, and a driving licence check uses 2. The free plan includes 10 a month. A live share code check usually takes 15 to 40 seconds, because it runs the real gov.uk check, so set your timeout to at least 60 seconds, or use an asynchronous check.