Checks

Immigration status

POST https://checksharecode.co.uk/api/check/immigration-status checks a person's UK immigration status on gov.uk, for a bank, lender, university, council or anyone else who needs it. Everything you send to this endpoint is here, and only that. A live check usually takes 15 to 40 seconds, so set your timeout to at least 60 seconds, or use the async endpoint.

What you send

Authorizationstringheaderrequired

Bearer followed by your key. rtw_test_… keys return sandbox data. rtw_live_… keys run a real check.

Example: Bearer rtw_live_…

share_codestringrequired

The 9-character code the person made at gov.uk/view-prove-immigration-status. These codes start with S; a right to work or right to rent code won’t open this check. Spaces and lower case are fine: we remove spaces and upper-case it.

Example: AB1CD2EF3

date_of_birthstringrequired

The applicant's date of birth as YYYY-MM-DD. It must match the share code, and they must be at least 16.

Example: 1990-01-01

company_namestringrequired

Your organisation's name, 1 to 200 characters. gov.uk asks you to include your local office or branch name, and records it as the organisation making the check.

Example: Example Bank, Leeds branch

job_titlestringrequired

The job title of the person making the check, 1 to 200 characters. gov.uk records it on the check.

Example: Account opening officer

purposestringrequired

Why you are checking, as gov.uk asks: one of driving_licence, student_loan, education_or_training, health_insurance_card, personal_finance, homelessness_or_council_housing, travel, other. gov.uk records its own words for it, which come back in purpose.

Example: personal_finance

other_purposestring

Your reason, 1 to 200 characters. Required when purpose is other, and refused otherwise.

Example: Eligibility for a hardship grant

gov.uk shows a status rather than a yes or no, so outcome is always ACCEPTED and the answer is in status, valid_until, activities and restrictions; see the fields. Don’t send checker_type: it is for right to rent, and is refused here with 400 INVALID_INPUT. You don’t need check either. If you send it, it must be immigration_status.

Save the photo and PDF if you need a record: we keep a copy of the check for up to 7 days only to investigate problems, then delete it.

curl https://checksharecode.co.uk/api/check/immigration-status \
  -H "authorization: Bearer $CHECKSHARECODE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "share_code": "AB1CD2EF3",
    "date_of_birth": "1990-01-01",
    "company_name": "Example Bank, Leeds branch",
    "job_title": "Account opening officer",
    "purpose": "personal_finance"
  }'

200 OK

{
  "outcome": "ACCEPTED",
  "title": "Immigration status",
  "name": "JANE EXAMPLE DOE",
  "date_of_birth": "1990-01-01",
  "nationality": "CAN",
  "status": "Skilled Worker",
  "valid_from": "2024-01-01",
  "valid_until": "2027-01-01",
  "activities": [
    "live in the UK until 1 January 2027",
    "study, subject to Academic Technology Approved Scheme (ATAS) conditions",
    "travel in and out of the country"
  ],
  "restrictions": ["They cannot access public funds."],
  "reference": "SC-EXAMPLE-12",
  "company_name": "Example Bank, Leeds branch",
  "job_title": "Account opening officer",
  "purpose": "Personal finance (including bank and building society accounts, loans, credit cards and mortgages)",
  "check_date": "2026-10-02",
  "share_code": "AB1CD2EF3",
  "photo_data_url": "data:image/jpeg;base64,/9j/4AAQ…",
  "pdf_data_url": "data:application/pdf;base64,JVBERi0…",
  "checked_at": "2026-10-02T10:14:03.000Z"
}

Try it

Sign up to try it with your sandbox key. It sends this request from the page and shows the answer, free, with test data.Log in

The same for every check

These are written once, for this endpoint, right to work and right to rent alike.

Response fieldsWhat each check returns ErrorsEvery code, and what to do Rate limits and quotaOne allowance for every check WebhooksFor asynchronous checks