# UK Right to Work Share Code Check (`matthewiiv/uk-right-to-work-share-code-check`) Actor
Verify a UK right-to-work share code against gov.uk and get structured JSON: outcome, name, permission type, expiry, conditions, applicant photo and a PDF certificate.
- **URL**: https://apify.com/matthewiiv/uk-right-to-work-share-code-check.md
- **Developed by:** [Matthew Sharp](https://apify.com/matthewiiv) (community)
- **Categories:** Developer tools, Automation, Other
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
Pay per usage
This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage
## What's an Apify Actor?
Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## 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](https://checksharecode.co.uk?ref=apify), 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](https://checksharecode.co.uk/signup?ref=apify) — 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](https://checksharecode.co.uk/pricing?ref=apify).
### 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 |
```json
{
"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):
```json
{
"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](https://docs.apify.com/api/v2), 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](https://checksharecode.co.uk/docs?ref=apify) and
[OpenAPI spec](https://checksharecode.co.uk/openapi.json).
### 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](https://checksharecode.co.uk/legal/privacy)). 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](https://checksharecode.co.uk/docs?ref=apify)
- Contact: [checksharecode.co.uk/contact](https://checksharecode.co.uk/contact)
# Actor input Schema
## `shareCode` (type: `string`):
The 9-character gov.uk share code the applicant gave you (case-insensitive, spaces and dashes allowed), e.g. AB1CD2EF3.
## `dateOfBirth` (type: `string`):
Applicant date of birth in ISO 8601 format (YYYY-MM-DD), e.g. 1990-01-01.
## `companyName` (type: `string`):
Your company name — gov.uk records it against the check.
## `apiKey` (type: `string`):
Your API key from checksharecode.co.uk (free tier available — sign up and create a key in the dashboard). Use rtw\_test\_… for sandbox runs (unmetered, never hits gov.uk) or rtw\_live\_… for real checks. Leave empty to run a free demo check — the run uses the sandbox and returns a simulated result.
## Actor input object example
```json
{
"shareCode": "AB1CD2EF3",
"dateOfBirth": "1990-01-01",
"companyName": "Example Ltd"
}
```
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"shareCode": "AB1CD2EF3",
"dateOfBirth": "1990-01-01",
"companyName": "Example Ltd"
};
// Run the Actor and wait for it to finish
const run = await client.actor("matthewiiv/uk-right-to-work-share-code-check").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"shareCode": "AB1CD2EF3",
"dateOfBirth": "1990-01-01",
"companyName": "Example Ltd",
}
# Run the Actor and wait for it to finish
run = client.actor("matthewiiv/uk-right-to-work-share-code-check").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"shareCode": "AB1CD2EF3",
"dateOfBirth": "1990-01-01",
"companyName": "Example Ltd"
}' |
apify call matthewiiv/uk-right-to-work-share-code-check --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=matthewiiv/uk-right-to-work-share-code-check",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "UK Right to Work Share Code Check",
"description": "Verify a UK right-to-work share code against gov.uk and get structured JSON: outcome, name, permission type, expiry, conditions, applicant photo and a PDF certificate.",
"version": "0.1",
"x-build-id": "WjbiutQ3tOh6xPERH"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/matthewiiv~uk-right-to-work-share-code-check/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-matthewiiv-uk-right-to-work-share-code-check",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/matthewiiv~uk-right-to-work-share-code-check/runs": {
"post": {
"operationId": "runs-sync-matthewiiv-uk-right-to-work-share-code-check",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/matthewiiv~uk-right-to-work-share-code-check/run-sync": {
"post": {
"operationId": "run-sync-matthewiiv-uk-right-to-work-share-code-check",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"shareCode",
"dateOfBirth",
"companyName"
],
"properties": {
"shareCode": {
"title": "Share code",
"type": "string",
"description": "The 9-character gov.uk share code the applicant gave you (case-insensitive, spaces and dashes allowed), e.g. AB1CD2EF3."
},
"dateOfBirth": {
"title": "Date of birth",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string",
"description": "Applicant date of birth in ISO 8601 format (YYYY-MM-DD), e.g. 1990-01-01."
},
"companyName": {
"title": "Company name",
"type": "string",
"description": "Your company name — gov.uk records it against the check."
},
"apiKey": {
"title": "Check Share Code API key",
"type": "string",
"description": "Your API key from checksharecode.co.uk (free tier available — sign up and create a key in the dashboard). Use rtw_test_… for sandbox runs (unmetered, never hits gov.uk) or rtw_live_… for real checks. Leave empty to run a free demo check — the run uses the sandbox and returns a simulated result."
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```