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

Getting the application form and uploading files with the Public Careers API

Fetch the application form for a vacancy, build it from the form definition, and upload candidate files before the application is submitted.

Fetch the application form for a vacancy, build it from the form definition, and upload candidate files before the application is submitted.

This guide is for web developers building a custom careers page. You need your careers slug and a vacancy id from the vacancy list, which Listing vacancies with the Public Careers API covers. Submitting the answers comes next, in Submitting and resuming an application with the Public Careers API.

The three calls

Applying is three calls, in this order, because each returns something the next one needs.

  1. Get the application form. This also gives you a token for uploads.
  2. Upload each file. Each upload returns a document id.
  3. Submit the answers, including the document ids.

Skipping the first call is the most common mistake. The upload token is only issued there.

Step 1: get the application form

GET /api/public/careers/{slug}/jobs/{jobId}/application-form

Forms are set up in Recruit and differ by vacancy. Build the form from this response and never from a fixed list of fields, or your site breaks the first time someone edits a form.

FieldNotes
fieldsThe form fields, in order
pagesOrdered page names
pageConditionsRules that show or hide a whole page, in the same style as showWhen below
sourcesOptions for How did you hear about us, each with a name and a slug
gapAnalysisEmployment gap settings, described below
gapReasonsEnabled, monthYearDatesEnabledWhether to collect a reason for each gap, and whether history dates are month and year only
uploadSessiontoken, expiresAt, maxFileSize and allowedMimeTypes
saveAndReturnEnabledWhether to offer save and finish later

Each field has these properties.

FieldNotes
idSend this back as fieldId. Do not send fieldKey
fieldKeyOptional name that says what the field means, such as first_name, email, cv or cover_letter
label, type, required
order, pageOrder within the page, and the zero-based page number matching pages
placeholder, helpTextOptional
optionsChoices for drop-down, multi-select and checkbox fields
showWhenOptional rule that decides when the field appears
requiredWhenOptional rule that makes the field required only in some cases
repeatable, repeatableGroupId, repeatableGroupLabelMark a field as part of a repeating group
repeatableMin, repeatableMaxFewest and most entries a repeating group takes
minChars, maxChars, minWords, maxWordsOptional length limits on text answers
contentKind, contentUrl, contentCaption, contentBodyUsed by display blocks. The kind is image, video or text

Field types are text, email, phone, url, textarea, file, dropdown, checkbox, date, multi_select, content, signature, image, heading. The content and heading types are for display only. Show them and send no answer for them.

Conditions, repeating groups and gaps

  • Conditional fields. Check each field's showWhen rule against the answers so far and hide the field when the rule is not met. A hidden required field is not enforced on submission, and answers to hidden fields are thrown away. If you show every field, candidates get stopped by requirements that should not apply to them.
  • Repeating groups. Fields that share a repeatableGroupId make a block the candidate can add to, usually employment or education history. Send one answer per field per entry and number the entries from zero with entryIndex. Respect repeatableMin and repeatableMax.
  • Date order. On submit, an employment or education end date that falls before its start date is refused. Check the order in the browser before the candidate moves on. A saved draft keeps half-filled dates as typed.
  • Employment gaps. Only look for gaps when gapAnalysis.enabled is true. Then look back lookBackYears years across the dates the candidate enters, flag any gap at least as long as the threshold (thresholdMonths months, or thresholdDays days when thresholdUnit is days), and collect an explanation where requireExplanations is true. Send the explanations in gapExplanations, or gapReasons where the form uses reasons.
  • If the form changes while the candidate is on it. A submit can come back with GAP_EXPLANATIONS_REQUIRED when the gap rule was switched on after you loaded the form. Fetch the form again, keep what the candidate typed and ask for the missing explanations.
  • Upload session. The token belongs to this one vacancy and lasts one hour. Read maxFileSize (in bytes) and allowedMimeTypes from the response rather than copying today's values into your code, and check files in the browser before uploading.

Step 2: upload a file

POST /api/public/careers/{slug}/jobs/{jobId}/upload

Send multipart form data, once for each file field. The parts are:

  • file: the file itself
  • fieldId: the id of the file field
  • sessionToken: the token from the form response

The default limits are 10 MB per file, and PDF, Word (.doc and .docx), RTF, plain text, OpenDocument text, PNG and JPEG files. Recruit checks the contents of the file as well as the declared type, so an .exe renamed to .pdf is refused with 400 INVALID_FILE_TYPE.

{
  "documentId": "doc_...",
  "filename": "jane-smith-cv.pdf",
  "size": 184320,
  "mimeType": "application/pdf"
}

Keep the documentId. The file is not attached to anything until you send it in step 3. Uploading again with the same token and field replaces the earlier file. Files that are never submitted are deleted after 7 days. Uploads are limited to 30 per minute and 60 per five minutes for each IP address.

POST /api/public/careers/acme/jobs/JOB_ID/upload
Host: api.hireroadrecruit.com
Content-Type: multipart/form-data

file: (the file, for example jane-smith-cv.pdf)
fieldId: FIELD_ID
sessionToken: SESSION_TOKEN

Renewing an expired upload session

If the hour runs out, the upload returns 401 with the code UPLOAD_SESSION_EXPIRED. Fetch the application form again for a fresh token, or renew the session, and retry. Keep what the candidate has typed while you do.

POST /api/public/careers/{slug}/jobs/{jobId}/upload-session/renew

Send { "sessionToken": "..." } to get a new session. Files already uploaded stay attached. A renewed session has a maximum total lifetime, so a candidate who leaves a form open for days will need to start the uploads again. This call is limited to 30 per minute.