# Right To Work Checker

> Free API to verify UK right-to-work share codes against the official gov.uk online checking service. Returns structured JSON including outcome (ACCEPTED or REJECTED), applicant name, photo, conditions, dates, gov.uk audit reference, and the gov.uk-rendered PDF.

This document is the long-form context for AI agents. It inlines the homepage copy, the FAQ, and the API error codes so an LLM can ingest everything in one request.

## Overview

Right To Work Checker is a free public HTTP API. Submit a UK share code, applicant date of birth, and employer company name. The service drives a real browser session against gov.uk/view-right-to-work, parses the result page, and returns structured JSON. There is no caching, no persistence, no signup, no rate-card.

- **Endpoint:** `POST /api/check`
- **Response time:** median ~15 seconds (live gov.uk dependency)
- **Cost:** free
- **Data retention:** zero — no check results are stored server-side
- **Affiliation:** none with HM Government, the Home Office, or gov.uk

## Request example

```http
POST /api/check HTTP/1.1
Content-Type: application/json

{
  "share_code": "AB1CD2EF3",
  "date_of_birth": "1990-01-01",
  "company_name": "Acme Ltd"
}
```

## Response example (200 OK)

```json
{
  "outcome": "ACCEPTED",
  "title": "Right to work",
  "name": "JANE EXAMPLE DOE",
  "date_of_birth": "1990-01-01",
  "nationality": null,
  "permission_type": null,
  "start_date": null,
  "expiry_date": null,
  "conditions": ["They can work in any job."],
  "restrictions": [],
  "reference": "WE-EXAMPLE-12",
  "share_code": "AB1CD2EF3",
  "photo_data_url": "data:image/jpeg;base64,...",
  "pdf_data_url":   "data:application/pdf;base64,...",
  "checked_at": "2026-05-11T15:19:13.711Z"
}
```

## Error codes

| Code               | HTTP | Meaning                                                        |
|--------------------|------|----------------------------------------------------------------|
| INVALID_INPUT      | 400  | Validation failed (bad share code, bad DOB, empty company).    |
| NOT_FOUND          | 404  | gov.uk reports the share code does not exist.                  |
| DOB_MISMATCH       | 404  | Share code exists but DOB does not match.                      |
| BUSY               | 503  | Concurrency cap reached. Retry after the Retry-After interval. |
| GOVUK_UNEXPECTED   | 502  | Parser could not find expected elements on the result page.    |
| TIMEOUT            | 504  | gov.uk did not respond in 20s.                                 |
| INTERNAL           | 500  | Anything else.                                                 |

## Frequently asked questions

### What is a UK right-to-work share code?

A 9-character code issued by the UK Home Office that an applicant generates at gov.uk/prove-right-to-work and shares with an employer or landlord. The code expires 90 days after creation and lets the recipient view the applicant’s current right-to-work status on gov.uk.

### How long does a check take?

Around 10–15 seconds. The service drives a real browser session against gov.uk/view-right-to-work, fills the form, and returns the parsed result. There is no caching — every check is live.

### What does the API response include?

The applicant’s name, outcome (ACCEPTED or REJECTED), title (“Right to work” or “Right to rent”), visa permission type and dates where shown, conditions, the gov.uk reference number, the applicant’s photo as a base64 JPEG, and the gov.uk-rendered PDF as base64.

### Is this affiliated with the UK government?

No. This service is not endorsed by, run by, or affiliated with HM Government, the Home Office, or gov.uk. It automates the public right-to-work check on a visitor’s behalf using their own share code.

### What does it cost?

Nothing. The API is free to use. No signup, no API key, no rate-card.