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/*orapplication/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:
{
"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-Afterseconds (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 availabledraft(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 omittedcity(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;nullremoves a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer400.deliveryNote(string): Note for deliveriesdistanceKm(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. WhilerouteStatusisPENDINGit is the value from before the last change (being recalculated); absent unlessDONEorPENDING.district(string): District (max length 128)driveMinutes(integer, nullable, read-only): Driving time in minutes (rounded up), seedistanceKmemail1(string (email)): First e-mail addressemail2(string (email)): Second e-mail addressfax(string): E.164geocodePrecision(string, read-only): How exact the coordinates are (house number, street, city or locality, postal code area); set withDONE. (one ofHOUSE,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/longitudeset;FAILED: no such place, or the geocoder stayed unreachable for five attempts;SKIPPED: no postal code, or geocoding is switched off. (one ofPENDING,DONE,FAILED,SKIPPED)geocodedAt(string (date-time), read-only): Time of the last geocoding attemptgln(string): Global Location Number with check digitid(string (uuid)): Keep the id when replacing the address aggregateinfo(string): Info textisBlocked(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 linename2(string): Second name linename3(string): Third name linephone(string): E.164poBox(string): PO boxpoBoxCity(string): City of the PO boxpoBoxPostalCode(string): Postal code of the PO boxpostalCode(string): Postal code (max length 32)region(string): Bundesland: ISO 3166-2 code matching the countryrouteApproximate(boolean, read-only): True when the tenant profile or this postal address is geocoded only to the locality or postal code arearouteStatus(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:distanceKmanddriveMinutesset;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 ofPENDING,DONE,FAILED,SKIPPED,NO_ORIGIN,NO_ROUTE)routedAt(string (date-time), read-only): Time of the last routing attemptstreet(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) answers400(postalCode: „Unbekannte Postleitzahl.“), a city that does not belong to it400(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 casesmunicipality,countyandregionare 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 ofVERIFIED,STREET_UNKNOWN,NOT_CHECKED,NOT_SUPPORTED)vatId(string): VAT ID of this postal addressversion(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 sameid(string (uuid), required): Id of the existing contact person or postal addresslabel(string, required): Name or street line of the existing entrynumber(integer, required):aspNroransNrreason(string, required): Why it looks the same (EMAIL, NAME or POSTAL_CODE)
fieldSources(FieldSources, required): Where each pre-filled field (JSON name) came fromwarnings(array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sourcesmessage(string, required): German hintfield(string): JSON name of the draft field (empty for the whole draft)
Example 200 answer:
{
"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
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"}'