## Draft a contact person from text or an image (tenant:masterdata:write)

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

Module: Master data · operationId: `draftContactPerson` · Tag: Drafts · Auth: access token (`Authorization: Bearer <accessToken>`)

Extracts a contact person of the address from pasted text or an image (`url` and `email` are
not used). Nothing is stored. `duplicates` lists contacts of the same address that look the same.

### Parameters

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

### Request body

`application/json` (required)

- `email` (string): Email address whose domain is looked up (address drafts only) (max length 320)
- `imageData` (string): Base64 image or data URI (business card, scanned letter); read via OCR after a malware scan (an image with a finding, or when the scan is unavailable, is not read and a warning on imageData says why) (max length 3145728)
- `mimeType` (string): `image/*` or `application/pdf` (max length 64)
- `text` (string): Pasted text: email signature, letterhead, delivery address … (max length 20000)
- `url` (string): Website or imprint URL (address drafts only) (max length 2048)

Example:

```json
{
  "text": "Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"
}
```

### Responses

- **200** The draft (`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`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)
- **429** Too many AI drafts or imprint lookups of this person – wait `Retry-After` seconds ([rate limits](/guides/rate-limits)) (`application/json`)
- **502** The AI could not read the input (`application/json`)
- **503** The AI is not reachable (`application/json`)

Fields of the 200 answer:

- `aiAvailable` (boolean, required): False when the AI was not available
- `draft` (ContactPerson, required): One contact person (Ansprechpartner). Needs a first or last name; at most one default contact.
  - `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)
- `duplicates` (array of ChildDuplicate, required): Contact persons of the same address that look the same
  - `id` (string (uuid), required): Id of the existing contact person or postal address
  - `label` (string, required): Name or street line of the existing entry
  - `number` (integer, required): `aspNr` or `ansNr`
  - `reason` (string, required): Why it looks the same (EMAIL, NAME or POSTAL_CODE)
- `fieldSources` (FieldSources, required): Where each pre-filled field (JSON name) came from
- `warnings` (array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sources
  - `message` (string, required): German hint
  - `field` (string): JSON name of the draft field (empty for the whole draft)

Example 200 answer:

```json
{
  "aiAvailable": true,
  "draft": {
    "email1": "info@hotel-waldblick.example",
    "firstName": "Markus",
    "lastName": "Pongratz",
    "phone1": "+49992477810",
    "position": "Inhaber",
    "salutationCode": "HERR"
  },
  "duplicates": [],
  "fieldSources": {
    "email1": "text",
    "firstName": "text",
    "lastName": "text",
    "phone1": "text",
    "position": "text"
  },
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"}'
```
