# UK RTW Share Code Checker (`organic_welcome/uk-rtw-share-code-checker`) Actor Automate UK right to work checks via the official GOV.UK share code service. Supports single and batch checks, extracts check details and work restrictions, classifies outcomes, and can optionally return the worker photo. - **URL**: https://apify.com/organic\_welcome/uk-rtw-share-code-checker.md - **Developed by:** [Sam](https://apify.com/organic_welcome) (community) - **Categories:** Automation, Developer tools, Other - **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, NaN bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.10 / completed right-to-work check This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 Checker Check a job applicant's right to work in the UK using their **Home Office share code** and **date of birth** — via the official [GOV.UK employer checking service](https://www.gov.uk/view-right-to-work). Returns one dataset item per check with the GOV.UK check details, extracted work conditions and restrictions, outcome classification, and an optional compressed worker photo. Supports single checks and batch processing. --- ### When to use this Under the **Immigration, Asylum and Nationality Act 2006**, UK employers must verify the right to work of any employee who is not a British or Irish citizen before they start work. Non-British/Irish workers generate a 9-character share code (starting with **W**) via their UKVI account, which employers use alongside the worker's date of birth to verify their status. This actor automates that employer-side verification step. --- ### Input #### Single check ```json { "shareCode": "W1X2Y3Z4A", "dateOfBirth": "1990-06-15", "companyName": "Acme Contractors Ltd", "include_image": false, "allow_sponsorship": true, "allow_student": true } ```` #### Batch check ```json { "companyName": "Acme Contractors Ltd", "include_image": true, "allow_sponsorship": false, "allow_student": true, "checks": [ { "shareCode": "W1X2Y3Z4A", "dateOfBirth": "1990-06-15", "companyName": "Acme Contractors Ltd", "reference": "candidate-001" }, { "shareCode": "W9A8B7C6D", "dateOfBirth": "1985-03-22", "companyName": "Acme Contractors Ltd", "reference": "candidate-002" } ] } ``` Input fields: - `shareCode` (`string`, required for single checks): 9-character share code starting with `W`. - `dateOfBirth` (`string`, required for single checks): Worker's DOB in `DD/MM/YYYY` or `YYYY-MM-DD` format. - `companyName` (`string`, required): Employer name entered into the GOV.UK service. For batch runs, item-level `companyName` is used when present, otherwise the top-level value is used as a fallback. - `checks` (`array`, required for batch checks): Array of `{shareCode, dateOfBirth, companyName, reference}` objects. - `reference` (`string`, optional): Your own reference ID, passed through to output. - `include_image` (`boolean`, optional): Include the worker photo as a compressed JPEG data URL. - `allow_sponsorship` (`boolean`, optional): If `false`, applicants requiring sponsorship are marked `REJECTED`. - `allow_student` (`boolean`, optional): If `false`, applicants with student visa work restrictions are marked `REJECTED`. - `proxyConfiguration` (`object`, recommended): Apify proxy config. Residential proxies are recommended for repeated checks. *** ### Output Each check produces one record in the dataset: ```json { "code": 200, "status": { "govuk_check_details": { "check_date": "Demo check", "company_name": "Demo Employer Ltd", "reference_number": "DEMO-REF-001" }, "details": { "data": { "conditions": ["Demo mode: this is a synthetic result used for health checks and Store previews."], "restrictions": [] }, "expiry_date": "31 December 2099", "name": "DEMO APPLICANT", "start_date": "1 January 2026", "summary": "Demo mode: this synthetic applicant has the right to work in the UK." }, "image": null, "outcome": "ACCEPTED", "outcome_reason": null, "title": "Right to work (Demo)" }, "error": null, "checkedAt": "2026-04-05T19:48:09.899Z", "shareCode": "WDEMO0000", "reference": "demo-healthcheck", "demo": true } ``` #### Response shape - `code`: HTTP-style result code returned by the actor. - `status.govuk_check_details`: Metadata shown on the GOV.UK result page. - `status.details`: Extracted worker name, summary, start and expiry dates, conditions, and restrictions. - `status.image`: Compressed base64 JPEG data URL when `include_image` is enabled and a photo is present. - `status.outcome`: Actor decision, one of `ACCEPTED`, `REFUSED`, `REJECTED`, or `UNKNOWN`. - `status.outcome_reason`: Additional rejection or refusal reason when available. - `shareCode` and `reference`: Request identifiers passed through at the top level. - `demo`: Present and `true` when the actor returns a synthetic demo result. - `error`: Error message for technical failures or explicit `NOT_FOUND` responses. #### Codes - `200`: Check completed and the actor classified the worker as `ACCEPTED` or `REFUSED`. - `422`: Check completed but the actor classified the result as `REJECTED` or `UNKNOWN`. - `404`: `status` is `NOT_FOUND`. GOV.UK did not recognise the supplied details. - `500`: `status` is `ERROR`. A technical error occurred during the run. #### Outcomes - `ACCEPTED`: Worker appears to have the right to work under the current actor rules. - `REFUSED`: Worker appears not to have the right to work. - `REJECTED`: Worker has a right to work result, but was rejected by your configured sponsorship or student filters. - `UNKNOWN`: The page was reached but the result could not be confidently classified. *** ### Notes - Share codes must start with **W** — codes starting with R (right to rent) or S (immigration status) will not work on this service - Share codes are valid for **90 days** from issue - `dateOfBirth` must exactly match the worker's Home Office record - `companyName` is required by the GOV.UK flow and is recorded in the output - When `include_image` is enabled, the actor returns the worker photo as a compressed JPEG data URL to reduce payload size - This actor automates the standard employer-side GOV.UK check. You remain responsible for retaining evidence of the check per Home Office guidance (download the PDF confirmation where required) - Residential proxies are recommended to avoid rate limiting on repeated checks *** ### Support Raise issues via the Apify console or contact via the actor page. # Actor input Schema ## `shareCode` (type: `string`): The 9-character right-to-work share code provided by the worker (must start with W). Use for single checks. ## `dateOfBirth` (type: `string`): The worker's date of birth. Accepts DD/MM/YYYY or YYYY-MM-DD format. ## `companyName` (type: `string`): The name of the employer conducting the check. Required by the GOV.UK service. ## `checks` (type: `array`): For batch processing — provide an array of {shareCode, dateOfBirth, companyName, reference} objects. If provided, the fields above are ignored. ## `include_image` (type: `boolean`): Whether to include the worker's photo in the output as a compressed JPEG data URL (base64-encoded). ## `allow_sponsorship` (type: `boolean`): Accept or reject applicants that require employer sponsorship (e.g. Skilled Worker visa holders). Set to false to mark these as REJECTED. ## `allow_student` (type: `boolean`): Accept or reject applicants on student visas with restricted working hours. Set to false to mark these as REJECTED. ## `proxyConfiguration` (type: `object`): Optional proxy settings. Recommended to use Apify Residential proxies to avoid rate limiting. ## Actor input object example ```json { "shareCode": "WMRKK37WH", "dateOfBirth": "02/01/1962", "companyName": "Acme Contractors Ltd", "checks": [ { "shareCode": "W1X2Y3Z4A", "dateOfBirth": "02/01/1990", "companyName": "Acme Ltd", "reference": "candidate-001" }, { "shareCode": "W9A8B7C6D", "dateOfBirth": "1985-03-22", "companyName": "Acme Ltd", "reference": "candidate-002" } ], "include_image": false, "allow_sponsorship": true, "allow_student": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # 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 = { "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("organic_welcome/uk-rtw-share-code-checker").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 = { "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], } } # Run the Actor and wait for it to finish run = client.actor("organic_welcome/uk-rtw-share-code-checker").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 '{ "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call organic_welcome/uk-rtw-share-code-checker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=organic_welcome/uk-rtw-share-code-checker", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "UK RTW Share Code Checker", "description": "Automate UK right to work checks via the official GOV.UK share code service. Supports single and batch checks, extracts check details and work restrictions, classifies outcomes, and can optionally return the worker photo.", "version": "0.0", "x-build-id": "lmLjzNq7jgsiSU23V" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/organic_welcome~uk-rtw-share-code-checker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-organic_welcome-uk-rtw-share-code-checker", "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/organic_welcome~uk-rtw-share-code-checker/runs": { "post": { "operationId": "runs-sync-organic_welcome-uk-rtw-share-code-checker", "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/organic_welcome~uk-rtw-share-code-checker/run-sync": { "post": { "operationId": "run-sync-organic_welcome-uk-rtw-share-code-checker", "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", "properties": { "shareCode": { "title": "Share Code", "type": "string", "description": "The 9-character right-to-work share code provided by the worker (must start with W). Use for single checks." }, "dateOfBirth": { "title": "Date of Birth", "type": "string", "description": "The worker's date of birth. Accepts DD/MM/YYYY or YYYY-MM-DD format." }, "companyName": { "title": "Company Name", "type": "string", "description": "The name of the employer conducting the check. Required by the GOV.UK service." }, "checks": { "title": "Batch Checks", "type": "array", "description": "For batch processing — provide an array of {shareCode, dateOfBirth, companyName, reference} objects. If provided, the fields above are ignored." }, "include_image": { "title": "Include Image", "type": "boolean", "description": "Whether to include the worker's photo in the output as a compressed JPEG data URL (base64-encoded).", "default": false }, "allow_sponsorship": { "title": "Allow Sponsorship", "type": "boolean", "description": "Accept or reject applicants that require employer sponsorship (e.g. Skilled Worker visa holders). Set to false to mark these as REJECTED.", "default": true }, "allow_student": { "title": "Allow Student Visas", "type": "boolean", "description": "Accept or reject applicants on student visas with restricted working hours. Set to false to mark these as REJECTED.", "default": true }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Optional proxy settings. Recommended to use Apify Residential proxies to avoid rate limiting." } } }, "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 } } } } } } } } } } ```