UK Share Code
API
UK Share Code
API
UK Share Code
API
Every request must include an API key. Obtain one by signing up on the sign up page.
Pass your API key as the value of the following HTTP header with every request:
X-UKRTWAPI-SECRET: <your-api-key>All endpoints are relative to:
https://app.ukrtwchecker.co.ukAny HTTP library works. See the code panel on the right for ready-to-run samples in Python, Node, Java, Go, cURL, and more. Send check parameters as a JSON body with Content-Type: application/json. GET requests with query-string parameters are also accepted for backwards compatibility, but POST is recommended to avoid PII appearing in server logs and URLs.
/rtrValidate an applicant's Right to Rent in the UK.
codeRequiredThe applicant's Share Code (8–11 chars, letters + numbers, starts with 'R').
dobRequiredDate of birth in dd-mm-yyyy format.
forenameRequiredThe applicant's first name(s).
surnameRequiredThe applicant's surname(s).
checker_typeRequiredSet to 'landlord' or 'agent'.
checker_nameRequiredYour name (if landlord) or company name (if agent).
include_imageOptionalReturn a base64-encoded applicant image. Default: false.
/rtwValidate an applicant's Right to Work in the UK. /v2/rtw returns additional structured fields.
codeRequiredShare Code (8–11 chars, starts with 'W').
dobRequiredDate of birth in dd-mm-yyyy format.
forenameRequiredThe applicant's first name(s).
surnameRequiredThe applicant's surname(s).
company_nameRequiredYour company name — required by the government for auditing.
allow_sponsorshipOptionalAccept or reject applicants requiring sponsorship. Default: true.
allow_studentOptionalAccept or reject applicants on student visas. Default: true.
include_imageOptionalReturn a base64-encoded applicant image. Default: false.
include_pdfOptionalReturn the official PDF report as a base64 string. Default: false.
/immigrationValidate an individual's immigration status. Currently in beta.
codeRequiredShare Code (8–11 chars, starts with 'S').
dobRequiredDate of birth in dd-mm-yyyy format.
forenameRequiredThe individual's first name(s).
surnameRequiredThe individual's surname(s).
company_nameRequiredYour company name — required for audit purposes.
checker_job_titleRequiredJob title of the person conducting the check, e.g. 'HR Manager'.
check_reasonRequiredReason for the check. Must be one of:
DRIVING_LICENCEEligibility for a driving licenceLOANEligibility for a student loanEDUCATION_OR_TRAININGEligibility for education or trainingTRAVELEligibility for travelHEALTH_INSURANCE_CARDEligibility for a health insurance cardPERSONAL_FINANCEPersonal finance (bank accounts, loans, credit cards, mortgages)HOMELESSNESS_ASSISTANCE_OR_COUNCIL_HOUSINGHomelessness assistance or council housingOTHERAnother reason (requires check_reason_other)check_reason_otherOptionalFree-text reason — required only when check_reason is set to OTHER.
include_imageOptionalReturn a base64-encoded applicant image. Default: false.
include_pdfOptionalReturn the official immigration PDF as a base64 string. Default: false.
/usageReturns how many checks you have performed in the current billing period. Only available on subscription plans.
/credit_packReturns all active credit packs associated with your account.
The top-level response wraps a status object with the following fields:
outcomeOverall result of the verification check.
ACCEPTEDRight to Work/Rent verified — all configured conditions satisfied.REJECTEDRight to Work/Rent not verified — code found but failed configured conditions.NOT_FOUNDShare code is not valid.SHARE_CODE_LOCKEDShare code is locked (too many recent checks). Usually resolves after ~10 minutes.SHARE_CODE_EXPIREDShare code was valid but has expired.govuk_check_detailsThe check date, company name, and gov.uk reference number.
conditionsWork conditions and restrictions (e.g. hours per week, restricted industries).
detailsA human-readable summary of the check.
nameThe applicant's full name as it appears on the government record.
start_dateWhen the right to work/rent is valid from (dd-mm-yyyy).
expiry_dateWhen the right to work/rent expires (dd-mm-yyyy).
imageThe applicant's photo, base64-encoded. Only present when include_image=true.
rejected_reasonPresent when the check is rejected due to a configured parameter filter.
SPONSORSHIPApplicant requires sponsorship and the check was configured to reject such applicants.STUDENTApplicant has a student visa and the check was configured to reject student visa holders.titleLabel for the type of check (e.g. "Right to Work", "Right to Rent").
Use these special share codes to test your integration without consuming quota. Optional parameters (e.g. include_image) apply in test mode too.
TEST_ACCEPTED/rtw, /v2/rtw, /rtr, /immigration
Mock a valid share code.
TEST_NOT_FOUND/rtw, /v2/rtw, /rtr, /immigration
Mock an invalid share code (not found).
TEST_NAME_MISMATCH/rtw, /v2/rtw, /rtr, /immigration
Mock a valid code where the name does not match.
TEST_SPONSOR/rtw, /v2/rtw
Mock a valid code for an applicant requiring sponsorship. Useful for testing allow_sponsorship.
TEST_STUDENT/rtw, /v2/rtw
Mock a valid code for a student visa holder. Useful for testing allow_student.
TEST_EXPIRED/rtw, /v2/rtw, /rtr
Mock a valid but expired share code.
TEST_LOCKED/rtw, /v2/rtw, /rtr, /immigration
Mock a locked share code.
Language
Endpoint
import requests
response = requests.post(
"https://app.ukrtwchecker.co.uk/rtw",
headers={"X-UKRTWAPI-SECRET": "YOUR_API_KEY"},
json={
"code": "TEST_ACCEPTED",
"forename": "John",
"surname": "Doe",
"dob": "07-09-1999",
"company_name": "UK RTW Checker Ltd.",
"allow_student": "true",
"allow_sponsorship": "true",
},
)
print(response.json()){
"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"
}}UK Share Code
API
© 2026 UK Share Code API. All rights reserved.