Listing vacancies with the Public Careers API
Read your careers page settings, filter values and live vacancies, and the server job feed that uses a key.
Read your careers page settings, filter values and live vacancies, and the server job feed that uses a key.
This guide is for web developers building a custom careers page. You need your careers slug, and your website allowed for browser calls if you call from the browser. See Building a custom careers page with the Public Careers API for both. Response wrapping and error codes are in Public Careers API responses, errors and rate limits.
Careers page settings and filters
GET /api/public/careers/{slug}
Returns your branding and the display options set in Settings > Company > Careers Page. Call it once when your page loads.
| Field | Notes |
|---|---|
companyName | |
logoUrl, headerImageUrl | Optional |
brandColor | Hex colour, for example #6366F1. Optional |
headline | Defaults to Join Our Team |
tagline, intro | |
metaTitle, metaDescription | The page title defaults to Careers |
socialLinks | Object with optional linkedin, twitter and glassdoor addresses |
privacyPolicyUrl | Optional. Use it for your privacy link |
jobAlertsEnabled | Show the job alerts sign-up when true |
registerYourInterest | Object: enabled, pageHeader, formTemplateId |
locationImagesEnabled | When true, jobs can carry a location picture |
availableLanguages | Languages you can pass as language |
A set of true or false switches follows, all false unless your team turns them on. Each one means hide: hideHeader, hideBanner, hidePrivacyPolicyLink, hideDepartmentFilter, hideJobTypeFilter, hideJobTimeFilter, hideLocationFilter, hideLocationSearch, hideJobTitleSearch, hideVacancyReference. Four more apply to the job alerts form: jobAlertsHideDepartmentFilter, jobAlertsHideJobTypeFilter, jobAlertsHideJobTimeFilter, jobAlertsHideLocationFilter. Honour them. Your recruitment team sets them expecting the same result on your site as on the hosted page.
GET /api/public/careers/{slug}/departments returns a list of department names that have at least one live vacancy, in alphabetical order. Use it to fill a department filter without empty options.
GET /api/public/careers/{slug}/facets returns the other filter values, with blanks removed.
{
"success": true,
"data": {
"jobTypes": ["full_time", "part_time"],
"jobTimes": ["Days", "Nights"],
"locations": ["Leeds", "Manchester"]
}
}
Job types and job times come from live vacancies. Locations are the live vacancy locations plus every active location set up in Recruit, even one with no live vacancy, so a candidate can pick it and see an empty result. If your organisation has its own Job Time wording, jobTimes returns that wording, so the values above are only an example. Pass the values back as employmentType, jobTime and location on the job list. The jobTime parameter accepts either the organisation's wording or the stored value.
Vacancy list
GET /api/public/careers/{slug}/jobs
Returns live, externally published vacancies, newest published first. Internal only roles, hidden roles, and roles past their closing date or posting expiry are left out for you.
| Parameter | Default | Notes |
|---|---|---|
page | 1 | Minimum 1 |
limit | 20 | 1 to 100 |
search | Matches the job title only, not the description. Up to 200 characters | |
department | Exact match. Up to 100 characters | |
employmentType | Exact match, one of the values below | |
jobTime | Exact match. Up to 100 characters | |
location | Exact match. Up to 200 characters. Use it for a drop-down built from facets | |
locationSearch | Partial match on location. Up to 200 characters. Use it for a free text box | |
language | en-GB or cy |
Allowed employmentType values: full_time, part_time, contract, temporary, internship, permanent, casual, bank, fixed_term, contractor, self_employed, apprenticeship, voluntary, placement, graduate. Anything else returns 400 VALIDATION_ERROR.
Paging details sit inside data:
{ "jobs": [ ], "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
Each vacancy in jobs has these fields.
| Field | Notes |
|---|---|
id | Use it for the detail, form and apply calls |
title | |
department | Optional |
location | |
locationImageUrl | Optional. Present when location pictures are on and the location has one |
employmentType | One of the values above |
salaryMin, salaryMax, salaryCurrency | Optional |
salaryPeriod | Optional. Tells you whether to show per hour, per month and so on |
salaryType | Optional. A descriptor such as Competitive, used in place of a range |
publishedAt | Empty if never published |
closingDate | Optional |
internalReference | Your vacancy reference. Optional |
Show salary defensively. A vacancy might have a range, a descriptor such as Competitive, or nothing. Check salaryType first, then the minimum and maximum, and show nothing if neither is there.
GET /api/public/careers/acme/jobs?page=1&limit=20&department=Finance
Host: api.hireroadrecruit.com
Vacancy detail and attachments
GET /api/public/careers/{slug}/jobs/{jobId}
Returns everything in the list entry plus these fields.
| Field | Notes |
|---|---|
description, requirements, benefits | HTML written in the rich text editor. Requirements and benefits are optional |
applicationFormPages | Ordered page names. More than one means a multi-page form |
attachments | Optional. Each has documentId, filename, mimeType and sizeBytes |
applyButtonEnabled | Whether to show an apply button |
Clean the HTML before you put it on your page, and style it so headings and lists display properly. On this call location and employmentType can be missing if your organisation hides those details on the vacancy page.
closingDateis the effective close: the earlier of the vacancy's own closing date and your careers page posting expiry. It can be earlier than the date your team sees in Recruit.- A closed vacancy still returns a normal response, so an old link can land on a page that says the vacancy has closed. Compare
closingDatewith the current time and show that message. An application to it is refused anyway.
GET /api/public/careers/{slug}/jobs/{jobId}/attachments/{documentId}/download
Returns the file itself, not JSON. Link to this address directly. It allows 5 requests per minute per IP address, and every failure returns the same 404 DOCUMENT_NOT_AVAILABLE, so you cannot tell a wrong id from a withdrawn file.
Server to server job feed
Servers can use a key instead of a slug.
GET /api/v1/jobsGET /api/v1/jobs/{jobId}GET /api/v1/register-your-interest
Send the key in an X-Api-Key header. The key identifies your organisation, so there is no slug in the address. The jobs call takes the same parameters and returns the same shape as the public list, without internal only vacancies.
- Only System Admin users can create, list or revoke keys. Keys begin
nrk_. The full key is shown once when it is created and cannot be shown again, so store it in a secret manager straight away. Ask your account manager if you need help creating one. - A key can only read these three calls. It cannot see candidates or applications and cannot change anything.
- A key does not expire. It works until it is revoked, so treat it as a long-lived password.
- Use it from a server only. Never put it in browser code or a mobile app.
For most sites the public calls above, made from your server, do the same job with nothing to keep secret.