Save retention, consent and the applicant mailbox (hr:recruiting:manage)
PUT /api/hr/v1/recruiting/settings
Module: HR · operationId: setRecruitingSettings · Tag: Recruiting · Auth: access token (Authorization: Bearer <accessToken>)
A changed consentText gets a new consentVersion; applications store the version they accepted. Publishing the careers page (career.enabled) needs the tenant's subdomain (400, field subdomain) and a mailbox (409 no_mailbox).
Request body
application/json (required)
career(CareerSite): The tenant's public careers page on its host (https://<subdomain>.<tenant host domain>/karriere). Publishing it needs the tenant's subdomain (HR settings;400fieldsubdomain) and a recruiting mailbox (409 no_mailbox).color(string): Accent colour #rrggbb; empty for the defaultcompany(string): The employer named on the page and in the postings' structured data (max length 200)enabled(boolean): The page and the public API answer for the tenant's subdomainintro(string): Markdown above the postings (max length 20000)origins(array of string): Websites (https://host) that may embed the list of postingssubdomain(string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has nonetitle(string): Title of the careers page (max length 200)url(string, read-only): The page; empty without a subdomain (or where the platform has no tenant hosts)
consentText(string): The data-protection consent applicants accept (max length 5000)consentVersion(integer, read-only): Version of the consent text; counts its changesfromName(string): Sender name and signature of applicant mail (max length 200)mailboxId(string): The comms mailbox (consumer recruiting) applicant mail is sent from and answered to; empty: no applicant mailprivacyUrl(string): https link to the privacy noticeretentionDays(integer): Rejected, withdrawn and hired applications are deleted this long after they closed (default 183, AGG) (max 3650)talentPoolMonths(integer): How long applications of people who agreed to the talent pool are kept (max 60)updatedAt(string (date-time), read-only): When the settings were last changedupdatedBy(string, read-only): Who last changed the settings (e-mail)version(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
Example:
{
"career": {
"color": "#0a7c66",
"company": "Muster IT-Systemhaus GmbH",
"enabled": true,
"intro": "Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.",
"origins": [
"https://www.muster-it.example"
],
"subdomain": "demo",
"title": "Karriere bei Muster IT",
"url": "https://demo.on.example.com/karriere"
},
"consentText": "Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.",
"consentVersion": 2,
"fromName": "Muster IT-Systemhaus GmbH – Personal",
"mailboxId": "5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91",
"privacyUrl": "https://www.muster-it.example/datenschutz",
"retentionDays": 183,
"talentPoolMonths": 12,
"updatedAt": "2026-10-20T08:45:00Z",
"updatedBy": "clara.becker@muster-it.example",
"version": 4
}
Responses
- 200 Saved (
application/json) - 400 Error (
application/json) - 409 Error (
application/json)
Fields of the 200 answer:
career(CareerSite): The tenant's public careers page on its host (https://<subdomain>.<tenant host domain>/karriere). Publishing it needs the tenant's subdomain (HR settings;400fieldsubdomain) and a recruiting mailbox (409 no_mailbox).color(string): Accent colour #rrggbb; empty for the defaultcompany(string): The employer named on the page and in the postings' structured data (max length 200)enabled(boolean): The page and the public API answer for the tenant's subdomainintro(string): Markdown above the postings (max length 20000)origins(array of string): Websites (https://host) that may embed the list of postingssubdomain(string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has nonetitle(string): Title of the careers page (max length 200)url(string, read-only): The page; empty without a subdomain (or where the platform has no tenant hosts)
consentText(string): The data-protection consent applicants accept (max length 5000)consentVersion(integer, read-only): Version of the consent text; counts its changesfromName(string): Sender name and signature of applicant mail (max length 200)mailboxId(string): The comms mailbox (consumer recruiting) applicant mail is sent from and answered to; empty: no applicant mailprivacyUrl(string): https link to the privacy noticeretentionDays(integer): Rejected, withdrawn and hired applications are deleted this long after they closed (default 183, AGG) (max 3650)talentPoolMonths(integer): How long applications of people who agreed to the talent pool are kept (max 60)updatedAt(string (date-time), read-only): When the settings were last changedupdatedBy(string, read-only): Who last changed the settings (e-mail)version(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
Example 200 answer:
{
"career": {
"color": "#0a7c66",
"company": "Muster IT-Systemhaus GmbH",
"enabled": true,
"intro": "Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.",
"origins": [
"https://www.muster-it.example"
],
"subdomain": "demo",
"title": "Karriere bei Muster IT",
"url": "https://demo.on.example.com/karriere"
},
"consentText": "Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.",
"consentVersion": 2,
"fromName": "Muster IT-Systemhaus GmbH – Personal",
"mailboxId": "5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91",
"privacyUrl": "https://www.muster-it.example/datenschutz",
"retentionDays": 183,
"talentPoolMonths": 12,
"updatedAt": "2026-10-20T08:45:00Z",
"updatedBy": "clara.becker@muster-it.example",
"version": 4
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/hr/v1/recruiting/settings' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"career":{"color":"#0a7c66","company":"Muster IT-Systemhaus GmbH","enabled":true,"intro":"Wir betreuen mit rund 25 Kolleginnen und Kollegen die IT von Mittelstand, Praxen und Kanzleien in Ostbayern.","origins":["https://www.muster-it.example"],"subdomain":"demo","title":"Karriere bei Muster IT","url":"https://demo.on.example.com/karriere"},"consentText":"Ich bin einverstanden, dass die Muster IT-Systemhaus GmbH meine Angaben zur Bearbeitung meiner Bewerbung speichert und verarbeitet.","consentVersion":2,"fromName":"Muster IT-Systemhaus GmbH – Personal","mailboxId":"5a7c9e1a-3c5e-4a7c-8e1a-3c5e7a9c1e91","privacyUrl":"https://www.muster-it.example/datenschutz","retentionDays":183,"talentPoolMonths":12,"updatedAt":"2026-10-20T08:45:00Z","updatedBy":"clara.becker@muster-it.example","version":4}'