API Integration Guide

Step-by-Step Integration Guide

Follow these steps to integrate the UK Right to Work share code API into your application. Ensure you have received your custom API key from in your email inbox, or have signed up via RapidAPI.

1. Use the Correct Endpoint
   The API is accessible in two different locations, the direct route of api.ukrtwchecker.co.uk/rtw, or, for requests via RapidAPI: https://uk-right-to-work-sharecode-checker.p.rapidapi.com/rtw

   • For RapidAPI: Please use the following endpoint:
     • https://uk-right-to-work-sharecode-checker.p.rapidapi.com/rtw
   • For Custom Keys: Please add the following endpoint:
     • https://api.ukrtwchecker.co.uk/rtw
2. Add Headers to your request:
   In order to authenticate your identity with the API, you'll need to include your API keys as a request header. The required header will differ based on whether you signed up via the website, or via RapidAPI.

   • For RapidAPI: Please add the following headers:
     • - 'X-RapidAPI-Host': "uk-right-to-work-sharecode-checker.p.rapidapi.com"
     • - 'X-RapidAPI-Key': "YOUR_RAPIDAPI_KEY"
   • For Custom Keys: Please add the following header:
     • - 'X-UKRTWAPI-SECRET': "YOUR_SECRET_KEY"
3. Prepare your API request with the parameters:
   • company_name: Your company name (string)
   • code: Share code to check (required)
   • forename: Applicant's first name (required)
   • surname: Applicant's last name (required)
   • dob: Applicant's date of birth in UK format (DD-MM-YYYY) (required)
   • Optional:
   • allow_student: Boolean (true or false) - Whether you would like to accept or reject student share codes (default: true)
   • allow_sponsorship:: Boolean (true or false) - Whether you would like to accept or reject share codes from people who require sponsorship (default: true)
   • include_image:: Boolean (true or false) - Whether you would like to include the applicant's profile image as a base64 encoded string in the response body (default: false).
4. Choose your preferred programming language or tool

   Below, you will see that there are some examples of how to send a request to the api via a handful popular languages and frameworks. More examples are available on the RapidAPI listing.

5. Execute the code to perform the right to work check.

   Ensure that you replace X-UKRTWAPI-SECRET (or X-RapidAPI-Key) with your secret key.

      # Python
      import requests

      #url = "https://uk-right-to-work-sharecode-checker.p.rapidapi.com/rtw" for rapidapi
      #url = "https://api.ukrtwchecker.co.uk/rtw" for custom keys

      querystring = {
        "company_name": "UK RTW Checker Ltd.",
        "allow_student": "true",
        "allow_sponsorship": "false",
        "code": "W123X456Y",
        "forename": "John",
        "surname": "Doe",
        "dob": "07-09-1999"
      }
      
      #RapidAPI
      '''
      headers = {
        'X-RapidAPI-Host': "uk-right-to-work-sharecode-checker.p.rapidapi.com",
        'X-RapidAPI-Key': "YOUR_RAPIDAPI_KEY"
      }
      '''
      
      #Custom
      '''
      headers = {
        'X-UKRTWAPI-SECRET': "YOUR_SECRET_KEY"
      }
      '''

      response = requests.request("GET", url, headers=headers, params=querystring)

      print(response.text)