Careers API
The careers API is the public part of HR's recruiting: the open postings of a tenant's careers page and applications to them. It needs no API key and no token – it is meant for browsers on the tenant's own website and for custom careers pages. Everything else about postings and applications (pipeline, access, mail) is the authenticated recruiting API.
A tenant switches its careers page on under Einstellungen › Personal › Bewerbermanagement ›
Karriereseite; it needs the tenant's subdomain (e.g. muster-gmbh, set once in the HR settings), and
the page lives on the tenant's host (https://muster-gmbh.<tenant host domain>/karriere). All routes live
under /api/hr/v1/careers/{subdomain}; an unknown subdomain or a switched-off page answers 404.
Read the open postings
| Call | Returns |
|---|---|
GET /careers/{subdomain} |
the page (company, title, intro, colour) and its open postings |
GET /careers/{subdomain}/postings |
only the postings, newest first |
GET /careers/{subdomain}/postings/{number} |
one posting with its description (Markdown), the application form and the consent text |
Only published postings inside their publication window are listed; closed ones answer 404. The
answers contain no internal ids, units or access lists. Render descriptions as Markdown without
raw HTML – they are tenant text.
Browsers may call GET /careers/{subdomain}/postings from another origin only if that origin is listed under
Websites für das Widget. The careers site offers a ready-made widget for that; the settings page shows
the code with the right host:
<div data-cc-jobs="muster-gmbh"></div>
<script src="https://muster-gmbh.<tenant host domain>/karriere/embed/jobs.js" async></script>
Take an application
- Fetch a captcha challenge with
GET /careers/{subdomain}/challengeand solve it with the ALTCHA widget or library (proof of work, a few hundred milliseconds in a browser). A challenge is valid for 15 minutes and counts once. - Send the application to
POST /careers/{subdomain}/postings/{number}/applications: JSON without files, ormultipart/form-datawith the JSON partapplicationfirst and then the files (cv,attachment,answer.<key>for file questions). Put the solved payload intoaltchaand the consent text'sversionintoconsentVersion; leave the honeypot fieldwebsiteempty. - The answer is always
202 {"status":"pending"}. The applicant receives a mail with a link to the tenant's careers page; the application exists only once they confirm it there (POST /careers/confirm). Unconfirmed applications are deleted with their files after 24 hours.
Files are checked for malware before anybody opens them: at most 10 files of 10 MB each (PDF, Word,
OpenDocument, JPEG, PNG, HEIC). Errors use the usual shape and name only what the
applicant can fix (field); 422 infected refuses a file with malware, 413 too_large a body
that is too big, 503 unavailable means the page takes no applications right now.
Limits
The routes are limited per client IP address, not per key (rate limits):
reads 5 requests per second (bursts of 50), challenges 1 per second (bursts of 20), applications one
per 20 seconds (bursts of 5). Beyond that, a few applications per address and day and per posting and
hour are accepted; more answer 202 as well but are not processed.