UK Share Code API
Making a Request to the API requires you to have an API key. You can obtain an API key by signing up via the home page or the pricing page.
You can authenticate your requests by providing the API key as a value to the following HTTP header. X-UKRTWAPI-SECRET
You can make a request using any language, library or technology that can send HTTP requests. The base url is https://app.ukrtwchecker.co.uk
Please see the `Endpoints` section to view sample code for each endpoint. We also have a list of guides and integrations on our website.
The Applicant's Share Code. This is usually 8-11 characters, a mixture of letters and numbers, starting with 'R'.
The Applicant's date of birth (in the format dd-mm-yyyy).
The Applicant's first name(s).
The Applicant's surname(s)
Specify whether you're a 'landlord' or an 'agent'.
Your name (if checker_type is set to 'landlord'), or your company name (if checker_type is set to 'agent')
Include an image of the applicant in the response. Returned as base64 encoded string. Can be set to “true” or “false”. (default: “false”).
The Applicant's Share Code. This is usually 8-11 characters, a mixture of letters and numbers, starting with 'W'.
The Applicant's date of birth (in the format dd-mm-yyyy).
The Applicant's first name(s).
The Applicant's surname(s)
The name of your company. This is required by the government for auditing purposes.
Accept or Reject applicants that require sponsorship. Can be set to “true” or “false”. (default: “true”).
Accept or Reject applicants that have student visas. Can be set to “true” or “false”. (default: “true”).
Include an image of the applicant in the response. Returned as base64 encoded string. Can be set to “true” or “false”. (default: “false”).
Include the official pdf report containing all of the right to work information in the response. Returned as a (very long) base64 encoded string. Can be set to "true" or "false". (default: "false")
The individual's Share Code. This is usually 8-11 characters, a mixture of letters and numbers, starting with 'S'.
The Applicant's date of birth (in the format dd-mm-yyyy).
The Applicant's first name(s).
The Applicant's surname(s)
The name of your company. This is required by the government for auditing purposes.
The job title of the person(s) carrying out the check, for example, 'HR Manager'
The reason that the check is being carried out, must be set to one of the below constants:
DRIVING_LICENCE - To check if the individual is eligible for a driving licence
LOAN - To check if the individual is eligible for a student loan
EDUCATION_OR_TRAINING - To check if the individual is eligible for education or training
TRAVEL - To check if the individual is eligible for travel
HEALTH_INSURANCE_CARD - To check if the individual is eligible for a health insurance card
PERSONAL_FINANCE - To check if the individual is eligible for personal finance (including bank and building society accounts, loans, credit cards and mortgages)
HOMELESSNESS_ASSISTANCE_OR_COUNCIL_HOUSING - To check if the individual is eligible for homelessness assistance or council housing
OTHER - Another Reason
A string detailing the reason for the check, this is required if check_reason is set to 'other'.
Include an image of the applicant in the response. Returned as base64 encoded string. Can be set to “true” or “false”. (default: “false”).
Include the official pdf report containing all of the individual's immigration information in the response. Returned as a (very long) base64 encoded string. Can be set to "true" or "false". (default: "false")
Get the check date, company name and check reference number associated with the gov.uk check.
Right to work conditions and restrictions. This might include information about how many hours an applicant can work per week, industries or roles that they are not permitted to work in etc.
Details of the check, usually acts as a summary.
When their right to work/rent expires, formatted as dd-mm-yyyy
The full name of the applicant as it appears on the government document.
Result of the check given the parameters (including configurable parameters)
ACCEPTED - Right to Work/Rent verified, configured parameters/conditions all satisfied.
REJECTED - Right to Work/Rent not verified, code found but failed some configured parameters/conditions.
NOT_FOUND - Share code not valid
SHARE_CODE_LOCKED - Share code locked, usually means there have been too many checks on that share code in a time frame. Usually resolved by waiting for 10 minutes and trying again.
SHARE_CODE_EXPIRED - Share code was valid, but has since expired. (Note that this only shows up on the first check after expiry, from then on, it will return STATUS_NOT_FOUND).
When the Applicant's Right to Work/Rent is valid from, formatted as dd-mm-yyyy.
Title of the check (usually, this is “Right to Work” or "Right to Rent").
The Applicant's image encoded as a base64 string.
Only present if the share code has been rejected due to configured parameters (such as allow_student, allow_sponsorship).
SPONSORSHIP - Applicant requires sponsorship, and the check was configured to reject applicants requiring sponsorship.
STUDENT - Applicant has a student visa, and the check was configured to reject applicants on student visas.
Mock the response for a valid share code.
Mock the response for an invalid share code (code not found by the relevant Government service).
Mock the response for a valid share code, but the name provided does not match the name associated with the share code.
Mock the response for a valid right to work share code for an applicant that requires sponsorship. (this is useful if you'd like to test the behaviour of the allow_sponsorship parameter.
Mock the response for a valid right to work share code for an applicant that has a student visa. (this is useful if you'd like to test the behaviour of the allow_student parameter.
Mock the response for a share code that is valid, but has expired.
Mock the response for a share code that has been locked.
Select Language:
Select Endpoint:
Request
import requests url = "https://app.ukrtwchecker.co.uk/rtw" headers = { "X-UKRTWAPI-SECRET": "YOUR_API_KEY" } params = { "code": "TEST_ACCEPTED", "forename": "John", "surname": "Doe", "dob": "07-09-1999", "company_name": "UK RTW Checker Ltd.", "allow_student": "true", "allow_sponsorship": "true" } response = requests.get(url, headers=headers, params=params) if response.status_code == 200: print(response.json()) else: print(f"Error: {response.status_code}", response.text)Response
{ "code": 200, "status": { "conditions": "N/A", "govuk_check_details": { "check_date": "16 June 2025", "company_name": "UK Share Code API", "reference_number": "WE-G98V497-OI" }, "details": "They have permission to work in the UK until 30 March 2028", "expiry_date": "30/03/2028", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD +wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII", "pdf": "JVBERi0xLjEKMSAwIG9iajw8IC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVu ZG9iagoyIDAgb2JqPDwgL1R5cGUvUGFnZXMvS2lkc1szIDAgUl0vQ291bnQgMT4+ ZW5kb2JqCjMgMCBvYmo8PCAvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJv eFswIDAgMSAxXS9Db250ZW50cyA0IDAgUj4+ZW5kb2JqCjQgMCBvYmo8PCAvTGVu Z3RoIDA+PnN0cmVhbQplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA1CjAwMDAwMDAw MDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDUzIDAwMDAw IG4gCjAwMDAwMDAxMDMgMDAwMDAgbiAKMDAwMDAwMDE3OCAwMDAwMCBuIAp0cmFp bGVyPDwgL1Jvb3QgMSAwIFIgL1NpemUgNT4+CnN0YXJ0eHJlZgoyMjMKJSVFT0YK ", "name": "JOHN DOE", "outcome": "ACCEPTED", "start_date": "08/02/2025", "title": "Right to work" }}
© Copyright all rights reserved.
© Copyright all rights reserved.
