UK Right to Work Share Code Check

Verify a UK right-to-work share code against gov.uk in one run and get back structured JSON: the outcome, the applicant's name, permission type, start/expiry dates, any conditions or restrictions, the gov.uk audit reference, the applicant's photo, and a PDF certificate of the check.

UK employers must check a candidate's right to work before they start. gov.uk only offers a manual web form — there is no official API. This Actor gives you the same check as clean JSON, so you can plug right-to-work verification into an onboarding pipeline, ATS, HR system, background-check flow, or spreadsheet workflow instead of clicking through the form and screenshotting the result.

Under the hood it calls the Check Share Code API, which drives a real gov.uk check session and parses the result. The Actor is free — you bring your own API key (free tier available, no card required).

What is a share code?

A share code is a 9-character code (like AB1CD2EF3) that a candidate generates on gov.uk to prove their right to work in the UK. An employer enters the code and the candidate's date of birth on gov.uk to see the official result. This Actor automates that step and returns the result as structured data, plus the evidence you need to keep on file: the applicant photo and a PDF certificate with the gov.uk audit reference.

Why use this Actor?

• Structured JSON, not a web page — outcome, permission type, expiry, conditions, restrictions, and audit reference as machine-readable fields.
• Evidence included — applicant photo (photo.jpg) and PDF certificate (certificate.pdf) saved to the run's key-value store.
• Clear failure modes — wrong share code, date-of-birth mismatch, and expired codes end the run with an explicit structured status, not a silent empty result.
• Free sandbox — test keys simulate every outcome without ever contacting gov.uk, so you can build your integration end to end before running a real check.
• No scraping to maintain — gov.uk markup changes are handled by the API behind the Actor, not by your code.

Try it without a key

Run the Actor with the prefilled defaults and no API key — it performs a demo check against the free sandbox and returns a realistic simulated result (marked demo: true, no photo/PDF). Real checks need an API key:

Getting an API key

1. Sign up at checksharecode.co.uk — the free tier includes 10 checks/month, no card required.
2. Create an API key in the dashboard.
3. Use an rtw_test_… key to develop (sandbox: unmetered, never contacts gov.uk, returns realistic simulated results) and an rtw_live_… key for real checks.

Paid tiers with higher volume start at £14/month — see pricing.

Input

Field	Example	Notes
shareCode	AB1CD2EF3	9 characters, case-insensitive, spaces/dashes allowed
dateOfBirth	1990-01-01	ISO 8601 (YYYY-MM-DD)
companyName	Acme Ltd	Your company name — gov.uk records it against the check
apiKey	rtw_test_…	Secret — from your checksharecode.co.uk dashboard

{
  "shareCode": "AB1CD2EF3",
  "dateOfBirth": "1990-01-01",
  "companyName": "Acme Ltd",
  "apiKey": "rtw_test_..."
}

Sandbox share codes

With an rtw_test_… key, magic share codes simulate each outcome: AA1AA1AA1 (accepted, Skilled Worker visa with conditions), BB2BB2BB2 (rejected), CC3CC3CC3 (not found), DD4DD4DD4 (date-of-birth mismatch); any other code returns accepted / indefinite leave to remain. Sandbox responses carry no photo or PDF.

Output

One dataset row per run (also saved as OUTPUT in the key-value store):

{
  "outcome": "ACCEPTED",
  "title": "Right to work",
  "name": "JANE EXAMPLE DOE",
  "date_of_birth": "1990-01-01",
  "nationality": "Netherlands",
  "permission_type": "Settled status",
  "start_date": null,
  "expiry_date": null,
  "conditions": [],
  "restrictions": [],
  "reference": "WE-EXAMPLE-12",
  "share_code": "AB1CD2EF3",
  "checked_at": "2026-01-01T12:00:00.000Z",
  "photo_url": "https://api.apify.com/v2/key-value-stores/…/records/photo.jpg",
  "pdf_url": "https://api.apify.com/v2/key-value-stores/…/records/certificate.pdf"
}

• outcome is ACCEPTED or REJECTED — gov.uk's answer to "can this person work for you".
• Time-limited permissions (e.g. Skilled Worker visas) include expiry_date and often conditions — store these; you may need a follow-up check before expiry.
• On live checks, the applicant photo and the PDF certificate are stored as files in the run's key-value store and linked from the row. Keep the PDF — it carries the gov.uk reference and is your evidence the check was done.

When a check can't return a result

The run fails with a structured status message so your automation can branch on it:

Status message starts with	Meaning	What to do
NOT_FOUND	Share code wrong, expired, or cancelled	Ask the candidate for a fresh code
DOB_MISMATCH	Code exists but date of birth doesn't match	Re-check the DOB you entered
INVALID_INPUT	Malformed share code or date	Fix the input format
QUOTA_EXCEEDED	Monthly included checks used up	Upgrade at checksharecode.co.uk
INVALID_KEY / UNAUTHENTICATED	Bad or revoked API key	Check the key in your dashboard
BUSY / RATE_LIMITED	Temporary throttling	Retry after a short wait

Automating it

Run the Actor on a schedule, from the Apify API, or from the Apify SDK like any other Actor, and read the result from the default dataset. Typical patterns:

• Onboarding pipeline — trigger a run when a candidate submits their share code and date of birth; branch on outcome and file the PDF.
• Re-check before expiry — schedule a run ahead of a stored expiry_date for time-limited permissions.

If you'd rather call the underlying REST API directly (no Apify run in the loop), the same check is one POST — see the API docs and OpenAPI spec.

Data handling & compliance

Right-to-work checks process personal data, so the pipeline is deliberately stateless: the Check Share Code API keeps no copy of the applicant's data — no database, no cache, nothing persisted server-side (see the privacy policy). Results exist only in your Apify dataset and key-value store, under your account's retention settings, and run logs never contain the share code, name, or date of birth.

This is an independent developer tool, not affiliated with or endorsed by the Home Office or GOV.UK. It automates the same publicly documented check an employer performs manually; responsibility for meeting Home Office guidance on right-to-work checks stays with the employer.

Support

• API docs: checksharecode.co.uk/docs
• Contact: checksharecode.co.uk/contact