# 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}`](/reference/hr/getCareerSite) | the page (company, title, intro, colour) and its open postings |
| [`GET /careers/{subdomain}/postings`](/reference/hr/listCareerPostings) | only the postings, newest first |
| [`GET /careers/{subdomain}/postings/{number}`](/reference/hr/getCareerPosting) | 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:

```html
<div data-cc-jobs="muster-gmbh"></div>
<script src="https://muster-gmbh.<tenant host domain>/karriere/embed/jobs.js" async></script>
```

## Take an application

1. Fetch a captcha challenge with [`GET /careers/{subdomain}/challenge`](/reference/hr/getCareerChallenge)
   and solve it with the [ALTCHA](https://altcha.org) widget or library (proof of work, a few hundred
   milliseconds in a browser). A challenge is valid for 15 minutes and counts once.
2. Send the application to
   [`POST /careers/{subdomain}/postings/{number}/applications`](/reference/hr/submitCareerApplication): JSON
   without files, or `multipart/form-data` with the JSON part `application` **first** and then the files
   (`cv`, `attachment`, `answer.<key>` for file questions). Put the solved payload into `altcha` and
   the consent text's `version` into `consentVersion`; leave the honeypot field `website` empty.
3. 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`](/reference/hr/confirmCareerApplication)). 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](/guides/errors) 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](/guides/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.
