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

`POST /api/masterdata/addresses/{id}/contacts`

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

Adds a contact person; `aspNr` is assigned. Setting `isDefault` clears it on the other
contacts. Locks the address, bumps its version and emits `masterdata.address.updated`.

### Parameters

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

### 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
{
  "department": "Finanzen",
  "email1": "max.mustermann@muster.de",
  "firstName": "Max",
  "gdprConsent": "UNKNOWN",
  "lastName": "Mustermann",
  "phone1": "+49 30 1234568",
  "position": "Buchhaltung",
  "roles": [
    "BILLING"
  ],
  "salutationCode": "HERR",
  "version": 0
}
```

### Responses

- **201** Created (`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`)

Fields of the 201 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 201 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 POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"department":"Finanzen","email1":"max.mustermann@muster.de","firstName":"Max","gdprConsent":"UNKNOWN","lastName":"Mustermann","phone1":"+49 30 1234568","position":"Buchhaltung","roles":["BILLING"],"salutationCode":"HERR","version":0}'
```
