## 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; `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:

```json
{
  "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:

```json
{
  "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

```bash
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}'
```
