Skip to content
English
  • There are no suggestions because the search field is empty.

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.

FieldNotes
companyName
logoUrl, headerImageUrlOptional
brandColorHex colour, for example #6366F1. Optional
headlineDefaults to Join Our Team
tagline, intro
metaTitle, metaDescriptionThe page title defaults to Careers
socialLinksObject with optional linkedin, twitter and glassdoor addresses
privacyPolicyUrlOptional. Use it for your privacy link
jobAlertsEnabledShow the job alerts sign-up when true
registerYourInterestObject: enabled, pageHeader, formTemplateId
locationImagesEnabledWhen true, jobs can carry a location picture
availableLanguagesLanguages 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.

ParameterDefaultNotes
page1Minimum 1
limit201 to 100
searchMatches the job title only, not the description. Up to 200 characters
departmentExact match. Up to 100 characters
employmentTypeExact match, one of the values below
jobTimeExact match. Up to 100 characters
locationExact match. Up to 200 characters. Use it for a drop-down built from facets
locationSearchPartial match on location. Up to 200 characters. Use it for a free text box
languageen-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.

FieldNotes
idUse it for the detail, form and apply calls
title
departmentOptional
location
locationImageUrlOptional. Present when location pictures are on and the location has one
employmentTypeOne of the values above
salaryMin, salaryMax, salaryCurrencyOptional
salaryPeriodOptional. Tells you whether to show per hour, per month and so on
salaryTypeOptional. A descriptor such as Competitive, used in place of a range
publishedAtEmpty if never published
closingDateOptional
internalReferenceYour 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.

FieldNotes
description, requirements, benefitsHTML written in the rich text editor. Requirements and benefits are optional
applicationFormPagesOrdered page names. More than one means a multi-page form
attachmentsOptional. Each has documentId, filename, mimeType and sizeBytes
applyButtonEnabledWhether 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.

  • closingDate is 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 closingDate with 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/jobs
  • GET /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.