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

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.

FieldRequiredNotes
fullNameYesUp to 200 characters
emailYesUp to 254 characters
gdprConsentYesMust be true
responsesYesThe answers. Can be empty. Up to 500 entries
phoneNoInternational format, for example +447700900123
smsOptInNoTrue 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
coverLetterNoUp to 10,000 characters
sessionTokenIf any answer carries a documentIdFrom the form response
gapExplanations, gapReasonsNoJSON text keyed by date range, formatted startDate_endDate. Up to 10,000 characters each
sourceNoThe slug of the option picked from sources. Up to 50 characters
sourceDetailsNoFree text for an Other source
channelNoThe job board the candidate came from. Up to 50 characters
referralLinkIdNoEmployee referral link id, if the address carried one
internalTokenNoNeeded to apply for a vacancy that is only on the internal careers page

Each entry in responses has these fields.

FieldNotes
fieldIdRequired. The id from the application form
valueText answers, up to 10,000 characters
selectedOptionsFor multi-select and checkbox fields, up to 200 entries
documentIdFor file fields, from the upload
entryIndexZero-based entry number in a repeating group
  • Phone numbers need the country code. 07700 900123 is rejected. Convert it to +447700900123 first. This is the most common reason a custom form fails.
  • Text messages. Text messages are an add-on. Send smsOptIn as true only when the candidate ticked the consent box, and word that box as the hosted page does.
  • Attribution. If your links carry a src parameter, send its value as channel. It takes priority over source. A source that is not in the sources list returns 400 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}/autosave keeps in-progress edits. Required answers are not checked at this stage.
  • POST /api/public/resume/{token}/upload uploads a file for a field on the resumed form.
  • POST /api/public/resume/{token}/resend emails the link to the candidate again.
  • POST /api/public/resume/{token}/submit takes { "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.