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.
- Get the application form. This also gives you a token for uploads.
- Upload each file. Each upload returns a document id.
- 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.
| Field | Notes |
|---|---|
fields | The form fields, in order |
pages | Ordered page names |
pageConditions | Rules that show or hide a whole page, in the same style as showWhen below |
sources | Options for How did you hear about us, each with a name and a slug |
gapAnalysis | Employment gap settings, described below |
gapReasonsEnabled, monthYearDatesEnabled | Whether to collect a reason for each gap, and whether history dates are month and year only |
uploadSession | token, expiresAt, maxFileSize and allowedMimeTypes |
saveAndReturnEnabled | Whether to offer save and finish later |
Each field has these properties.
| Field | Notes |
|---|---|
id | Send this back as fieldId. Do not send fieldKey |
fieldKey | Optional name that says what the field means, such as first_name, email, cv or cover_letter |
label, type, required | |
order, page | Order within the page, and the zero-based page number matching pages |
placeholder, helpText | Optional |
options | Choices for drop-down, multi-select and checkbox fields |
showWhen | Optional rule that decides when the field appears |
requiredWhen | Optional rule that makes the field required only in some cases |
repeatable, repeatableGroupId, repeatableGroupLabel | Mark a field as part of a repeating group |
repeatableMin, repeatableMax | Fewest and most entries a repeating group takes |
minChars, maxChars, minWords, maxWords | Optional length limits on text answers |
contentKind, contentUrl, contentCaption, contentBody | Used 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
showWhenrule 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
repeatableGroupIdmake 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 withentryIndex. RespectrepeatableMinandrepeatableMax. - 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.enabledis true. Then look backlookBackYearsyears across the dates the candidate enters, flag any gap at least as long as the threshold (thresholdMonthsmonths, orthresholdDaysdays whenthresholdUnitis days), and collect an explanation whererequireExplanationsis true. Send the explanations ingapExplanations, orgapReasonswhere the form uses reasons. - If the form changes while the candidate is on it. A submit can come back with
GAP_EXPLANATIONS_REQUIREDwhen 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) andallowedMimeTypesfrom 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 itselffieldId: theidof the file fieldsessionToken: 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.