ConnectCloud Developers

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; 400 field subdomain) and a recruiting mailbox (409 no_mailbox).
    • color (string): Accent colour #rrggbb; empty for the default
    • company (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 subdomain
    • intro (string): Markdown above the postings (max length 20000)
    • origins (array of string): Websites (https://host) that may embed the list of postings
    • subdomain (string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has none
    • title (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 changes
  • fromName (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 mail
  • privacyUrl (string): https link to the privacy notice
  • retentionDays (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 changed
  • updatedBy (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; 400 field subdomain) and a recruiting mailbox (409 no_mailbox).
    • color (string): Accent colour #rrggbb; empty for the default
    • company (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 subdomain
    • intro (string): Markdown above the postings (max length 20000)
    • origins (array of string): Websites (https://host) that may embed the list of postings
    • subdomain (string, read-only): The tenant's subdomain (HR settings), the address of the page; empty while the tenant has none
    • title (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 changes
  • fromName (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 mail
  • privacyUrl (string): https link to the privacy notice
  • retentionDays (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 changed
  • updatedBy (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}'

View as Markdown · Interactive reference · OpenAPI