Developer

API Documentation

The same data that runs the site, in your own code. Search live UK visa-sponsor jobs, look up licensed companies, pull sponsor scores and visa stats. REST API, metered by credits. Manage your API keys • View the MCP tool reference

Quick Start

Get your API key

Create an API key from the Developer Dashboard. API access is included in Pro and Agency plans.

Make your first request

bash

curl "https://huntukvisasponsors.com/public/v1/search/jobs?q=software+engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Watch your credit balance

Every response includes X-RateLimit-Remaining, and you should pay attention to it. Credits reset on the 1st of each month; if you run out before then, you'll get 429s until reset. Don't retry-loop on a 429. It won't help. Wait for the reset or upgrade.

Authentication

Every request needs your API key as a Bearer token in the Authorization header.

bash

curl "https://huntukvisasponsors.com/public/v1/stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Treat your key like a password

Anyone who finds your key can burn through your monthly credits before you notice. Don't put it in browser code, mobile apps, or anywhere public. Secret-scanners crawl GitHub constantly. Call the API from a server you control and only send your frontend the rows it actually needs.

Rate Limiting

There's a monthly credit budget. Search endpoints cost 5 credits, detail lookups 1–3, reference data 1. Each endpoint card below shows its exact cost. MCP tool calls pull from the same pool, so search_jobs over MCP costs the same as GET /search/jobs.

Plan	Credits / Month
agency	160,000
pro	7,000

Response Headers

Header	Description
X-RateLimit-Limit	Your plan's monthly credit budget
X-RateLimit-Cost	Credit cost of this request
X-RateLimit-Remaining	Credits remaining for the current month

Handling Rate Limits

Once you blow through your monthly budget you'll get 429 Too Many Requests until the next reset. Watch X-RateLimit-Remaining on every response so you see it coming, instead of getting surprised at midnight on the 30th.

Company Endpoints

GET/company/{idOrSlug}

2 credits

Get detailed company profile including sponsorship status, company size, industry, website, and Companies House data.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/jobs

5 credits

List current job openings from a specific company. Supports pagination and filtering.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug
`location`query	string[]	no	Filter by one or more location names (repeat the param to pass multiple)
`limit`query	number	no	Page size (default 20, max 100)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/jobs?location=value" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/jobs/facets

3 credits

Get aggregated facet counts for a company's jobs (by location, occupation code, etc.).

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/jobs/facets" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/related

3 credits

Get companies related to the specified company, based on industry, size, and location similarity.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/related" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{id}/visa_stats

3 credits

Get a company's visa sponsorship statistics including historical Certificates of Sponsorship (CoS) data by visa type and year.

Name	Type	Required	Description
`id`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/id_here/visa_stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Job Endpoints

GET/job/{idOrSlug}

2 credits

Get detailed information about a specific job posting including title, description, location, salary, company details, and application link.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Job ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/job/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Search Endpoints

GET/search/companies

5 credits

Search licensed visa sponsor companies. Filter by name, industry, location, company size, and sponsor licence status.

Name	Type	Required	Description
`q`query	string	no	Free-text query (company name, keyword)
`company`query	string	no	Filter by company name (lowercase)
`visaType`query	string[]	no	Filter by one or more visa/licence type slugs
`location`query	string[]	no	Filter by company city/location names
`companySize`query	string[]	no	Filter by company size bucket (e.g. '1-50')
`industry`query	string[]	no	Filter by SIC section industry name
`minRecentVisaCount`query	number	no	Minimum number of recent visa issuances
`includeRecruitmentAgency`query	boolean	no	Include recruitment agencies. Default false
`jobCreatedAtAfter`query	string	no	Only include companies with jobs created at or after this RFC3339 timestamp
`view`query	string	no	Response detail level. Default minimal
`size`query	number	no	Page size (default 10, max 50)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/search/companies?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/search/jobs

5 credits

Search for visa-sponsored jobs. Supports keyword search, filters for location, occupation code, company size, industry, and more.

Name	Type	Required	Description
`q`query	string	no	Free-text search query (e.g. 'software engineer')
`company`query	string	no	Filter by company name (lowercase)
`job`query	string	no	Filter by job title (lowercase)
`visaType`query	string	no	Filter by visa/licence type slug (e.g. 'skilled-worker')
`location`query	string[]	no	Filter by one or more location names (repeat the param to pass multiple)
`occupationCode`query	string[]	no	Filter by SOC occupation codes (e.g. '2137')
`companySize`query	string[]	no	Filter by company size bucket (e.g. '51-200')
`industry`query	string[]	no	Filter by SIC section industry name
`minSponsorScore`query	number	no	Minimum sponsor score (0-100). Default 0
`minOccupationConfidence`query	number	no	Minimum occupation-classification confidence (0-100)
`includeUnclassifiedOcc`query	boolean	no	Include jobs whose occupation code is unclassified. Default true
`minRelevance`query	number	no	Minimum text-search relevance score (0-1)
`includeRecruitmentAgency`query	boolean	no	Include jobs from recruitment agencies. Default false
`jobCreatedAtAfter`query	string	no	Only return jobs created at or after this RFC3339 timestamp
`jobCreatedAtBefore`query	string	no	Only return jobs created at or before this RFC3339 timestamp
`searchTime`query	string	no	RFC3339 anchor timestamp for time-decay relevance scoring. Pass the same value across paginated requests to keep cursor ordering stable
`postedWithin`query	string	no	Only return jobs posted within this time window
`view`query	string	no	Response detail level. Default minimal
`size`query	number	no	Page size (default 10, max 50)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/search/jobs?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/search/location

1 credit

Autocomplete location search. Returns matching UK locations for use as filter values in job or company searches.

Name	Type	Required	Description
`q`query	string	no	Location name fragment to search for (e.g. 'Manch')
`limit`query	number	no	Maximum number of results (1-1000, default 10)
`offset`query	number	no	Pagination offset (default 0)
`orderBy`query	string	no	Result ordering. Default location

bash

curl "https://huntukvisasponsors.com/public/v1/search/location?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Reference Endpoints

GET/sicsection

1 credit

List all Standard Industrial Classification (SIC) sections used to categorize company industries.

bash

curl "https://huntukvisasponsors.com/public/v1/sicsection" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/stats

1 credit

Get platform-wide statistics including total jobs, companies, and sponsored visa counts.

bash

curl "https://huntukvisasponsors.com/public/v1/stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/visa-types

1 credit

List all UK visa types tracked on the platform (Skilled Worker, Global Talent, etc.).

bash

curl "https://huntukvisasponsors.com/public/v1/visa-types" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

User Endpoints

Job Alerts

GET/user/alerts

1 credit

List your job alert subscriptions.

bash

curl "https://huntukvisasponsors.com/public/v1/user/alerts" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/alerts

1 credit

Create a new job alert subscription with keyword, location, and frequency filters.

Name	Required	Description
`jobKeyword`body	no	Keyword query for the alert (e.g. 'data scientist')
`location`body	no	Optional location filter
`frequencyInDays`body	yes	How often (in days) the alert is delivered. 1 = daily

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/alerts" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frequencyInDays":"frequencyInDays_value","jobKeyword":"jobKeyword_value","location":"location_value"}'

DELETE/user/alerts/{id}

1 credit

Delete a job alert subscription.

Name	Type	Required	Description
`id`path	string	yes	Alert ID

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/alerts/id_here" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Company Bookmarks

GET/user/bookmark/companies

1 credit

List your bookmarked companies.

bash

curl "https://huntukvisasponsors.com/public/v1/user/bookmark/companies" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/bookmark/companies

1 credit

Bookmark a company by its ID.

Name	Type	Required	Description
`id`body		yes	Company ID (CUID)

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/bookmark/companies" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"id_value"}'

DELETE/user/bookmark/companies/{id}

1 credit

Remove a company from your bookmarks.

Name	Type	Required	Description
`id`path	string	yes	Company ID (CUID)

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/bookmark/companies/id_here" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Job Bookmarks

GET/user/bookmark/jobs

1 credit

List your bookmarked jobs.

bash

curl "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/bookmark/jobs

1 credit

Bookmark a job by its ID or slug.

Name	Type	Required	Description
`idOrSlug`body		yes	Job ID (CUID) or URL slug

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idOrSlug":"idOrSlug_value"}'

DELETE/user/bookmark/jobs/{idOrSlug}

1 credit

Remove a job from your bookmarks.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Job ID (CUID) or URL slug

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Error Responses

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

json

{
  "error": "rate limit exceeded, cost: 5 credits"
}

Status	Meaning
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks permission (e.g. free tier)
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded, check Retry-After header
500	Internal Server Error — unexpected server issue

Developer

API Documentation

Quick Start

Get your API key

Create an API key from the Developer Dashboard. API access is included in Pro and Agency plans.

Make your first request

bash

curl "https://huntukvisasponsors.com/public/v1/search/jobs?q=software+engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Watch your credit balance

Authentication

Every request needs your API key as a Bearer token in the Authorization header.

bash

curl "https://huntukvisasponsors.com/public/v1/stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Treat your key like a password

Rate Limiting

Plan	Credits / Month
agency	160,000
pro	7,000

Response Headers

Header	Description
X-RateLimit-Limit	Your plan's monthly credit budget
X-RateLimit-Cost	Credit cost of this request
X-RateLimit-Remaining	Credits remaining for the current month

Handling Rate Limits

Company Endpoints

GET/company/{idOrSlug}

2 credits

Get detailed company profile including sponsorship status, company size, industry, website, and Companies House data.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/jobs

5 credits

List current job openings from a specific company. Supports pagination and filtering.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug
`location`query	string[]	no	Filter by one or more location names (repeat the param to pass multiple)
`limit`query	number	no	Page size (default 20, max 100)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/jobs?location=value" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/jobs/facets

3 credits

Get aggregated facet counts for a company's jobs (by location, occupation code, etc.).

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/jobs/facets" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{idOrSlug}/related

3 credits

Get companies related to the specified company, based on industry, size, and location similarity.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/company-name-abc123xyz456/related" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/company/{id}/visa_stats

3 credits

Get a company's visa sponsorship statistics including historical Certificates of Sponsorship (CoS) data by visa type and year.

Name	Type	Required	Description
`id`path	string	yes	Company ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/company/id_here/visa_stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Job Endpoints

GET/job/{idOrSlug}

2 credits

Get detailed information about a specific job posting including title, description, location, salary, company details, and application link.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Job ID (CUID) or URL slug

bash

curl "https://huntukvisasponsors.com/public/v1/job/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Search Endpoints

GET/search/companies

5 credits

Search licensed visa sponsor companies. Filter by name, industry, location, company size, and sponsor licence status.

Name	Type	Required	Description
`q`query	string	no	Free-text query (company name, keyword)
`company`query	string	no	Filter by company name (lowercase)
`visaType`query	string[]	no	Filter by one or more visa/licence type slugs
`location`query	string[]	no	Filter by company city/location names
`companySize`query	string[]	no	Filter by company size bucket (e.g. '1-50')
`industry`query	string[]	no	Filter by SIC section industry name
`minRecentVisaCount`query	number	no	Minimum number of recent visa issuances
`includeRecruitmentAgency`query	boolean	no	Include recruitment agencies. Default false
`jobCreatedAtAfter`query	string	no	Only include companies with jobs created at or after this RFC3339 timestamp
`view`query	string	no	Response detail level. Default minimal
`size`query	number	no	Page size (default 10, max 50)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/search/companies?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/search/jobs

5 credits

Search for visa-sponsored jobs. Supports keyword search, filters for location, occupation code, company size, industry, and more.

Name	Type	Required	Description
`q`query	string	no	Free-text search query (e.g. 'software engineer')
`company`query	string	no	Filter by company name (lowercase)
`job`query	string	no	Filter by job title (lowercase)
`visaType`query	string	no	Filter by visa/licence type slug (e.g. 'skilled-worker')
`location`query	string[]	no	Filter by one or more location names (repeat the param to pass multiple)
`occupationCode`query	string[]	no	Filter by SOC occupation codes (e.g. '2137')
`companySize`query	string[]	no	Filter by company size bucket (e.g. '51-200')
`industry`query	string[]	no	Filter by SIC section industry name
`minSponsorScore`query	number	no	Minimum sponsor score (0-100). Default 0
`minOccupationConfidence`query	number	no	Minimum occupation-classification confidence (0-100)
`includeUnclassifiedOcc`query	boolean	no	Include jobs whose occupation code is unclassified. Default true
`minRelevance`query	number	no	Minimum text-search relevance score (0-1)
`includeRecruitmentAgency`query	boolean	no	Include jobs from recruitment agencies. Default false
`jobCreatedAtAfter`query	string	no	Only return jobs created at or after this RFC3339 timestamp
`jobCreatedAtBefore`query	string	no	Only return jobs created at or before this RFC3339 timestamp
`searchTime`query	string	no	RFC3339 anchor timestamp for time-decay relevance scoring. Pass the same value across paginated requests to keep cursor ordering stable
`postedWithin`query	string	no	Only return jobs posted within this time window
`view`query	string	no	Response detail level. Default minimal
`size`query	number	no	Page size (default 10, max 50)
`after`query	string	no	Forward pagination cursor from a previous response
`before`query	string	no	Backward pagination cursor from a previous response

bash

curl "https://huntukvisasponsors.com/public/v1/search/jobs?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/search/location

1 credit

Autocomplete location search. Returns matching UK locations for use as filter values in job or company searches.

Name	Type	Required	Description
`q`query	string	no	Location name fragment to search for (e.g. 'Manch')
`limit`query	number	no	Maximum number of results (1-1000, default 10)
`offset`query	number	no	Pagination offset (default 0)
`orderBy`query	string	no	Result ordering. Default location

bash

curl "https://huntukvisasponsors.com/public/v1/search/location?q=engineer" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Reference Endpoints

GET/sicsection

1 credit

List all Standard Industrial Classification (SIC) sections used to categorize company industries.

bash

curl "https://huntukvisasponsors.com/public/v1/sicsection" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/stats

1 credit

Get platform-wide statistics including total jobs, companies, and sponsored visa counts.

bash

curl "https://huntukvisasponsors.com/public/v1/stats" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

GET/visa-types

1 credit

List all UK visa types tracked on the platform (Skilled Worker, Global Talent, etc.).

bash

curl "https://huntukvisasponsors.com/public/v1/visa-types" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

User Endpoints

Job Alerts

GET/user/alerts

1 credit

List your job alert subscriptions.

bash

curl "https://huntukvisasponsors.com/public/v1/user/alerts" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/alerts

1 credit

Create a new job alert subscription with keyword, location, and frequency filters.

Name	Required	Description
`jobKeyword`body	no	Keyword query for the alert (e.g. 'data scientist')
`location`body	no	Optional location filter
`frequencyInDays`body	yes	How often (in days) the alert is delivered. 1 = daily

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/alerts" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"frequencyInDays":"frequencyInDays_value","jobKeyword":"jobKeyword_value","location":"location_value"}'

DELETE/user/alerts/{id}

1 credit

Delete a job alert subscription.

Name	Type	Required	Description
`id`path	string	yes	Alert ID

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/alerts/id_here" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Company Bookmarks

GET/user/bookmark/companies

1 credit

List your bookmarked companies.

bash

curl "https://huntukvisasponsors.com/public/v1/user/bookmark/companies" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/bookmark/companies

1 credit

Bookmark a company by its ID.

Name	Type	Required	Description
`id`body		yes	Company ID (CUID)

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/bookmark/companies" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"id_value"}'

DELETE/user/bookmark/companies/{id}

1 credit

Remove a company from your bookmarks.

Name	Type	Required	Description
`id`path	string	yes	Company ID (CUID)

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/bookmark/companies/id_here" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Job Bookmarks

GET/user/bookmark/jobs

1 credit

List your bookmarked jobs.

bash

curl "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

POST/user/bookmark/jobs

1 credit

Bookmark a job by its ID or slug.

Name	Type	Required	Description
`idOrSlug`body		yes	Job ID (CUID) or URL slug

bash

curl -X POST "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idOrSlug":"idOrSlug_value"}'

DELETE/user/bookmark/jobs/{idOrSlug}

1 credit

Remove a job from your bookmarks.

Name	Type	Required	Description
`idOrSlug`path	string	yes	Job ID (CUID) or URL slug

bash

curl -X DELETE "https://huntukvisasponsors.com/public/v1/user/bookmark/jobs/company-name-abc123xyz456" \
  -H "Authorization: Bearer huvs_YOUR_API_KEY"

Error Responses

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

json

{
  "error": "rate limit exceeded, cost: 5 credits"
}

Status	Meaning
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks permission (e.g. free tier)
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded, check Retry-After header
500	Internal Server Error — unexpected server issue