Sign-up endpoints: register your interest and job alerts in the Public Careers API
Add the register your interest talent pool form and the job alerts sign-up to a custom careers page.
Add the register your interest talent pool form and the job alerts sign-up to a custom careers page.
This guide is for web developers building a custom careers page. You need your careers slug first, and the matching sign-up must be switched on in Settings > Company > Careers Page. Job alerts has the settings and candidate emails. This guide covers the calls only.
Register your interest
This is a talent pool sign-up for people who want to hear about future roles. Show it only when registerYourInterest.enabled is true in the careers page settings.
GET /api/public/careers/{slug}/register-interest/form
Returns the form your team chose in Settings > Company > Careers Page, as fields and, where it has file fields, an uploadSession. Files go to POST /api/public/careers/{slug}/register-interest/upload, which takes the same three parts as a job upload: file, fieldId and sessionToken. This call is limited to 30 per minute.
POST /api/public/careers/{slug}/register-interest
| Field | Required | Notes |
|---|---|---|
email | Yes | Up to 254 characters |
gdprConsent | Yes | Must be true |
firstName, lastName, phone | No | Phone in international format, for example +447700900123 |
responses | No | Answers to the form above, in the same shape as the apply call |
The response is a short confirmation message. An email that is already registered returns 409 ALREADY_EXISTS. Show your normal confirmation for that too, so your form never tells a stranger that an address is in your talent pool. Limited to 5 per minute for each IP address.
Servers that hold a key can read the same form with GET /api/v1/register-your-interest. Listing vacancies with the Public Careers API explains how keys work.
Job alerts
Candidates can ask for an email when a matching vacancy is published. Show the sign-up only when jobAlertsEnabled is true.
POST /api/public/careers/{slug}/job-alerts
| Field | Required | Notes |
|---|---|---|
firstName, lastName | Yes | |
email | Yes | Up to 254 characters |
criteria | No | Object with departments, jobTypes, jobTimes and locations, each a list of text values. Up to 20 values per list, each up to 100 characters |
Fill the choices from the departments and facets calls so candidates only pick values that exist. The job times in the facets use the organisation's own wording, so the alert form shows the same labels as the careers page. The four jobAlertsHide switches in the careers page settings tell you which choices to leave out.
The response is { "subscribed": true } whether or not the address was already on the list. Confirmation and unsubscribe links are in the emails Recruit sends, so you build nothing for those. Alerts go out only for vacancies that are live on the public careers page, so a vacancy that is hidden, expired or only on the internal careers page sends none. Limited to 5 per minute for each IP address.