## Draft a postal address from text or an image (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/postal-addresses:draft`

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

Extracts a postal address (e.g. a delivery address) of the address from pasted text or an image (`url` and `email` are not used). Nothing is stored.

### 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": "Lieferanschrift: Muster GmbH, Lager Nord, Industriestraße 12, 22113 Hamburg"
}
```

### 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` (PostalAddress, required): One postal address (Anschrift). Needs a street, PO box or city. At most one default per kind.
  - `addressLine2` (string): Additional address line (max length 255)
  - `ansNr` (integer): Number within the address; assigned when 0 or omitted
  - `city` (string): City (max length 128)
  - `countryCode` (string): ISO 3166-1 alpha-2 (default `"DE"`)
  - `county` (string): Kreis (Landkreis or kreisfreie Stadt) (max length 128)
  - `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`.
  - `deliveryNote` (string): Note for deliveries
  - `distanceKm` (number, nullable, read-only): Driving distance in km (0.1 km) from the tenant profile (`TenantProfile`) to this postal address by car, computed asynchronously after geocoding. While `routeStatus` is `PENDING` it is the value from before the last change (being recalculated); absent unless `DONE` or `PENDING`.
  - `district` (string): District (max length 128)
  - `driveMinutes` (integer, nullable, read-only): Driving time in minutes (rounded up), see `distanceKm`
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `fax` (string): E.164
  - `geocodePrecision` (string, read-only): How exact the coordinates are (house number, street, city or locality, postal code area); set with `DONE`. (one of `HOUSE`, `STREET`, `LOCALITY`, `POSTCODE`)
  - `geocodeStatus` (string, read-only): Geocoding of the postal address, asynchronous after the save (never during a request). `PENDING`: new, or street, postal code, city or country changed; `DONE`: `latitude`/`longitude` set; `FAILED`: no such place, or the geocoder stayed unreachable for five attempts; `SKIPPED`: no postal code, or geocoding is switched off. (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`)
  - `geocodedAt` (string (date-time), read-only): Time of the last geocoding attempt
  - `gln` (string): Global Location Number with check digit
  - `id` (string (uuid)): Keep the id when replacing the address aggregate
  - `info` (string): Info text
  - `isBlocked` (boolean): Blocked postal address (never a billing or shipping default)
  - `isDefaultBilling` (boolean): Default billing address (at most one)
  - `isDefaultDunning` (boolean): Default dunning address (at most one)
  - `isDefaultInfo` (boolean): Default address for information (at most one)
  - `isDefaultService` (boolean): Default service address (at most one)
  - `isDefaultShipping` (boolean): Default shipping address (at most one)
  - `latitude` (number, nullable, read-only): WGS 84, set by the geocoding of masterdata (self-hosted Photon) after the save; ignored on writes. A change of street, postal code, city or country removes it until the postal address is geocoded again. (max 90)
  - `longitude` (number, nullable, read-only): WGS 84 (max 180)
  - `municipality` (string): Gemeinde (max length 128)
  - `name1` (string): First name line
  - `name2` (string): Second name line
  - `name3` (string): Third name line
  - `phone` (string): E.164
  - `poBox` (string): PO box
  - `poBoxCity` (string): City of the PO box
  - `poBoxPostalCode` (string): Postal code of the PO box
  - `postalCode` (string): Postal code (max length 32)
  - `region` (string): Bundesland: ISO 3166-2 code matching the country
  - `routeApproximate` (boolean, read-only): True when the tenant profile or this postal address is geocoded only to the locality or postal code area
  - `routeStatus` (string, read-only): Routing from the tenant profile, asynchronous (never during a request). `PENDING`: waiting for geocoding or the router (also after a move of this postal address or of the tenant profile); `DONE`: `distanceKm` and `driveMinutes` set; `FAILED`: the router stayed unreachable for five attempts; `SKIPPED`: no coordinates, outside the routable area, or routing is switched off; `NO_ORIGIN`: the tenant profile has no coordinates; `NO_ROUTE`: no road connection. (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`, `NO_ORIGIN`, `NO_ROUTE`)
  - `routedAt` (string (date-time), read-only): Time of the last routing attempt
  - `street` (string): Street with house number (max length 255)
  - `validationStatus` (string, read-only): OpenPLZ check of postal code, city and street (DE, AT, CH, LI), run on writes that add a postal address or change its postal code, city, street or country; unchanged rows keep their status. An unknown postal code (or one without the format of its country: DE five digits, AT, CH, LI four) answers `400` (`postalCode`: „Unbekannte Postleitzahl.“), a city that does not belong to it `400` (`city`: „Ort passt nicht zur Postleitzahl.“). `VERIFIED`: the street line starts with a street of the postal code (case-insensitive, `ß` = `ss`, `str.` = `straße`; the line keeps the house number). `STREET_UNKNOWN`: postal code and city are known, the street is not (saved). In both cases `municipality`, `county` and `region` are taken from OpenPLZ and are read-only. `NOT_CHECKED`: OpenPLZ unreachable or switched off, or stored before the check, or the checks of the save took longer than 8 s. `NOT_SUPPORTED`: another country. (one of `VERIFIED`, `STREET_UNKNOWN`, `NOT_CHECKED`, `NOT_SUPPORTED`)
  - `vatId` (string): VAT ID of this postal address
  - `version` (integer): Version of this postal address (child updates)
  - `website` (string (uri)): Website
- `duplicates` (array of ChildDuplicate, required): Postal addresses 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": {
    "city": "Bodenmais",
    "countryCode": "DE",
    "name1": "Hotel Waldblick Bodenmais",
    "postalCode": "94249",
    "street": "Waldweg 7"
  },
  "duplicates": [],
  "fieldSources": {
    "city": "text",
    "name1": "text",
    "postalCode": "text",
    "street": "text"
  },
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Lieferanschrift: Muster GmbH, Lager Nord, Industriestraße 12, 22113 Hamburg"}'
```
