## Replace a contact person (tenant:masterdata:write)

`PUT /api/masterdata/addresses/{id}/contacts/{cid}`

Module: Master data · operationId: `updateContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

The body carries the `version` of the contact person (not of the address); `aspNr` is kept. Bumps the address version and emits `masterdata.address.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `cid` | path | string (uuid) | yes | Contact person id |

### Request body

`application/json` (required)

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `customFields` (CustomFields): Values of tenant-defined fields (`/api/masterdata/field-defs`) by key. On write the map is merged into the stored values; `null` removes a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer `400`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)

Example:

```json
{
  "aspNr": 2,
  "availableFrom1": "08:00",
  "availableTo1": "16:00",
  "customFields": {},
  "doNotCall": false,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "emailOptOut": false,
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "languageCode": "de",
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "preferredChannel": "PHONE",
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "timezone": "Europe/Berlin",
  "version": 3
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Malformed body or query parameter (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)
- **404** Not found in the caller's tenant (or merged, see `code`) (`application/json`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 200 answer:

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `customFields` (CustomFields): Values of tenant-defined fields (`/api/masterdata/field-defs`) by key. On write the map is merged into the stored values; `null` removes a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer `400`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)
- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aspNr":2,"availableFrom1":"08:00","availableTo1":"16:00","customFields":{},"doNotCall":false,"email1":"katrin.stadler@alpenhotel-seeblick.example","emailOptOut":false,"firstName":"Katrin","gdprConsent":"UNKNOWN","id":"8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a","isActive":true,"isBlocked":false,"isDefault":false,"languageCode":"de","lastName":"Stadler","letterSalutation":"Sehr geehrte Frau Stadler","phone1":"+498652987612","position":"Empfangsleitung und IT","postalAddressAnsNr":1,"preferredChannel":"PHONE","roles":["TECHNICAL","SUPPORT"],"salutationCode":"FRAU","timezone":"Europe/Berlin","version":3}'
```
