ConnectCloud Developers

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

  1. Fetch a captcha challenge with GET /careers/{subdomain}/challenge and 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.
  2. Send the application to POST /careers/{subdomain}/postings/{number}/applications: 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). 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.

View as Markdown