ConnectCloud Developers

Add a postal address (tenant:masterdata:write)

POST /api/masterdata/addresses/{id}/postal-addresses

Module: Master data · operationId: createPostalAddress · Tag: Postal addresses · Auth: access token (Authorization: Bearer <accessToken>)

Adds a postal address; ansNr is assigned. The first postal address of an address becomes the default billing and shipping address. Bumps the address version and emits masterdata.address.updated.

Parameters

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

Request body

application/json (required)

  • 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

Example:

{
  "city": "Hamburg",
  "countryCode": "DE",
  "deliveryNote": "Anlieferung Tor 3",
  "isDefaultShipping": false,
  "name1": "Muster GmbH",
  "name2": "Lager Nord",
  "postalCode": "22113",
  "street": "Industriestraße 12",
  "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:

  • 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
  • addressVersion (integer, required): New version of the address

Example 201 answer:

{
  "addressVersion": 8,
  "ansNr": 1,
  "city": "Schönau am Königssee",
  "countryCode": "DE",
  "geocodeStatus": "PENDING",
  "id": "2c4e6a8c-0d2f-4b4c-9e6a-8c0e2a4c6e8a",
  "isDefaultBilling": true,
  "name1": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "postalCode": "83471",
  "routeStatus": "PENDING",
  "street": "Seestraße 4",
  "validationStatus": "VERIFIED",
  "version": 3
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"city":"Hamburg","countryCode":"DE","deliveryNote":"Anlieferung Tor 3","isDefaultShipping":false,"name1":"Muster GmbH","name2":"Lager Nord","postalCode":"22113","street":"Industriestraße 12","version":0}'

View as Markdown · Interactive reference · OpenAPI