# 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.

Base URL: `https://checksharecode.co.uk` · Auth: `authorization: Bearer <key>` · Web version: https://checksharecode.co.uk/docs/quickstart

> **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](https://checksharecode.co.uk/docs/agents.md)

```text
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.
```

## 1. Get your sandbox key

Every account gets one when it signs up, on [API keys](https://checksharecode.co.uk/app/keys). Put it in an environment variable called `CHECKSHARECODE_API_KEY`.

Your sandbox key is on https://checksharecode.co.uk/app/keys (it starts `rtw_test_`). Read it from `CHECKSHARECODE_API_KEY`.

## 2. Make 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:

```bash
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"
  }'
```

Node.js:

```js
const res = await fetch('https://checksharecode.co.uk/api/check', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.CHECKSHARECODE_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    share_code: 'AA1AA1AA1',
    date_of_birth: '1990-01-01', // YYYY-MM-DD
    company_name: 'Acme Ltd',
  }),
});

const result = await res.json();
if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.outcome); // "ACCEPTED" or "REJECTED"
```

Python:

```python
import os
import requests

res = requests.post(
    "https://checksharecode.co.uk/api/check",
    headers={"authorization": f"Bearer {os.environ['CHECKSHARECODE_API_KEY']}"},
    json={
        "share_code": "AA1AA1AA1",
        "date_of_birth": "1990-01-01",  # YYYY-MM-DD
        "company_name": "Acme Ltd",
    },
    timeout=60,
)
result = res.json()
if not res.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result["outcome"])  # "ACCEPTED" or "REJECTED"
```

## 3. Read 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:

```json
{
  "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"
}
```

## 4. Try 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 |

## 5. Go live

Create a live key under [API keys](https://checksharecode.co.uk/app/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. |

See also: [Overview](https://checksharecode.co.uk/docs.md) · [POST /api/check](https://checksharecode.co.uk/docs/api/check.md)