Submitting and resuming an application with the Public Careers API
Send a candidate application to a vacancy, handle the result, and let candidates save a partly finished application and come back to it.
Send a candidate application to a vacancy, handle the result, and let candidates save a partly finished application and come back to it.
This guide is for web developers building a custom careers page. You need the form definition and, if the form has file fields, the document ids from Getting the application form and uploading files with the Public Careers API. Error codes are listed in Public Careers API responses, errors and rate limits.
Step 3: submit the application
POST /api/public/careers/{slug}/jobs/{jobId}/apply
Send JSON with these fields.
| Field | Required | Notes |
|---|---|---|
fullName | Yes | Up to 200 characters |
email | Yes | Up to 254 characters |
gdprConsent | Yes | Must be true |
responses | Yes | The answers. Can be empty. Up to 500 entries |
phone | No | International format, for example +447700900123 |
smsOptIn | No | True when the candidate ticked the text message box under the phone field. It only counts when a phone number is sent. Without it the candidate gets no texts |
coverLetter | No | Up to 10,000 characters |
sessionToken | If any answer carries a documentId | From the form response |
gapExplanations, gapReasons | No | JSON text keyed by date range, formatted startDate_endDate. Up to 10,000 characters each |
source | No | The slug of the option picked from sources. Up to 50 characters |
sourceDetails | No | Free text for an Other source |
channel | No | The job board the candidate came from. Up to 50 characters |
referralLinkId | No | Employee referral link id, if the address carried one |
internalToken | No | Needed to apply for a vacancy that is only on the internal careers page |
Each entry in responses has these fields.
| Field | Notes |
|---|---|
fieldId | Required. The id from the application form |
value | Text answers, up to 10,000 characters |
selectedOptions | For multi-select and checkbox fields, up to 200 entries |
documentId | For file fields, from the upload |
entryIndex | Zero-based entry number in a repeating group |
- Phone numbers need the country code.
07700 900123is rejected. Convert it to+447700900123first. This is the most common reason a custom form fails. - Text messages. Text messages are an add-on. Send
smsOptInas true only when the candidate ticked the consent box, and word that box as the hosted page does. - Attribution. If your links carry a
srcparameter, send its value aschannel. It takes priority oversource. Asourcethat is not in the sources list returns400 INVALID_CANDIDATE_SOURCE. - Confirmation email. Recruit sends the acknowledgement. Do not send your own or the candidate gets two.
- A 201 response means the application was accepted, not that the candidate passed any screening questions. A candidate who fails a knock-out question still gets a 201 and the application is marked for your recruiters. Show the same confirmation either way.
- Do not retry blindly. A second submission with the same email returns
409 DUPLICATE_APPLICATION.
POST /api/public/careers/acme/jobs/JOB_ID/apply
Host: api.hireroadrecruit.com
Content-Type: application/json
{
"fullName": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+447700900123",
"gdprConsent": true,
"sessionToken": "SESSION_TOKEN",
"channel": "indeed",
"responses": [
{ "fieldId": "FIELD_FIRST_NAME", "value": "Jane" },
{ "fieldId": "FIELD_CV", "documentId": "doc_..." },
{ "fieldId": "FIELD_LANGUAGES", "selectedOptions": ["English", "Welsh"] }
]
}
A successful call returns applicationId and a message. The apply call is limited to 20 per minute, and 60 per 15 minutes, for each IP address.
Save and return
Save and return lets a candidate fill in what they can, receive a private link by email and finish later. Offer it only when saveAndReturnEnabled is true in the application form response.
POST /api/public/careers/{slug}/jobs/{jobId}/save-draft
The body is the same as the apply call without the gap fields. Only name, email and consent are checked, so unfinished later pages are accepted. The response gives resumeLink and resumeExpiresAt. The candidate also gets the link by email, and it runs out in line with the vacancy's closing date, so tell them when. No application exists until the candidate submits. Save draft is limited to 20 per minute for each IP address.
Resuming a saved application
The link opens the resume page hosted by Recruit, which handles the rest. If you would rather host that step yourself, these calls work with the token from the link.
GET /api/public/resume/{token}returns the vacancy, the form fields and the candidate's answers.POST /api/public/resume/{token}/autosavekeeps in-progress edits. Required answers are not checked at this stage.POST /api/public/resume/{token}/uploaduploads a file for a field on the resumed form.POST /api/public/resume/{token}/resendemails the link to the candidate again.POST /api/public/resume/{token}/submittakes{ "responses": [ ] }in the same shape as the apply call.
The final submit checks required answers, repeating group limits, date order and employment gap explanations, exactly as a first submit does. A resumed application cannot skip them. A link that is wrong or past its expiry returns 404 NOT_FOUND.