User Facing Verification Form

This guide demonstrates how to integrate the UK Share Code API into a Next.js application that lets applicants submit their share code, forename, surname, and date of birth — and receive an instant right-to-work result.

Prerequisites

Node.js v14+
React v16+
npm or yarn
An API key from the pricing page

Getting Started

1. Clone the repository

git clone git@github.com:jamesoneill997/uk-rtw-checker-form.git
cd uk-rtw-checker-form

2. Install dependencies

npm install
# or
yarn install

3. Set up environment variables

Create a .env.local file in the project root:

NEXT_PUBLIC_RAPIDAPI_HOST=uk-right-to-work-sharecode-checker.p.rapidapi.com
NEXT_PUBLIC_RAPIDAPI_KEY=your_rapidapi_key
RTW_COMPANY_NAME=Your Company Name
RTW_ALLOW_SPONSORSHIP=false
RTW_ALLOW_STUDENT=true

4. Run the development server

npm run dev
# or
yarn dev

Open http://localhost:3000 in your browser.

API Endpoint

The check is handled by src/app/api/check-rtw/route.tsx.

Example request

GET /api/check-rtw?share_code=W123X456Y&forename=John&surname=Doe&dob=07-09-1999

Example response

{
  "data": {
    "code": 200,
    "status": {
      "outcome": "REJECTED",
      "rejected_reason": "STUDENT",
      "name": "John Doe",
      "expiry_date": "30/03/2028",
      "start_date": "12/04/2024",
      "title": "Right to work"
    }
  }
}

Project Structure

src/app/api/check-rtw/route.tsx — API route that calls the share code service
src/app/ — main application components and pages
next.config.mjs — Next.js configuration
tailwind.config.ts — Tailwind CSS configuration

Troubleshooting

Ensure all environment variables are set correctly in .env.local
Check the browser console and terminal for error messages
Verify your API key has the necessary permissions

Check out the project on GitHub for more details.