Create an address (tenant:masterdata:write)
POST /api/masterdata/addresses
Module: Master data · operationId: createAddress · Tag: Addresses · Auth: access token (Authorization: Bearer <accessToken>)
Stores a new address with its child collections. An empty adrNr is assigned from the
ADDRESS number range, an empty searchTerm is derived from the name. The first postal
address becomes the default billing and shipping address, the first bank account the
default account. Omitted purchaseOrderRequired is true. A customerNumber or supplierNumber
another live address of the tenant has answers 409 customer_number_taken / supplier_number_taken
(field and details.fields name the field). Emits masterdata.address.created.
Request body
application/json (required)
statusCode(string, required): Code ofaddress-statuses(required). Its flags decide therolesversion(integer, required): Optimistic locking version; send the version you read (ignored on create)accountOwner(string): Account owner (responsible person) in CRM (max length 255)accountType(string): Individual or collective account (one ofINDIVIDUAL,COLLECTIVE; default"INDIVIDUAL")additionalName(string): Name addition (second name line) (max length 255)adrNr(string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)annualRevenue(number, nullable): Annual revenuebankAccounts(array of BankAccount): Bank accountsiban(string, required): Unique per addressaccountHolder(string): Account holder (max length 255)bankName(string): Name of the bank (max length 128)bic(string): BICid(string (uuid)): Id of the bank accountisDefault(boolean): At most one; the first account is the default when none is set
blockReason(string): Cleared whenisBlockedis false (max length 255)blockedAt(string (date-time), read-only): Time of the general blockblockedBy(string, read-only): Actor of the general blockcommercialRegister(string): Commercial register number (Handelsregister) (max length 128)companyName(string): Company name (required forpartyTypeCOMPANY) (max length 255)contactPersons(array of ContactPerson): Contact persons (Ansprechpartner)aspNr(integer): Number within the address; assignedavailableFrom1(string, nullable): Reachable from (HH:MM)availableFrom2(string, nullable): Second time window: reachable from (HH:MM)availableTo1(string, nullable): AfteravailableFrom1availableTo2(string, nullable): AfteravailableFrom2birthday(string (date), nullable): Birthday (YYYY-MM-DD)blockReason(string, read-only): Reason of the blockblockedAt(string (date-time), read-only): Time of the blockblockedBy(string, read-only): Actor of the blockcustomFields(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.department(string): DepartmentdoNotCall(boolean): Do not callemail1(string (email)): First e-mail addressemail2(string (email)): Second e-mail addressemailOptOut(boolean): No marketing e-mailsfax(string): E.164firstName(string): First name (max length 128)gdprConsent(string): GDPR consent state (one ofUNKNOWN,GRANTED,DENIED,REVOKED; default"UNKNOWN")gdprConsentDate(string (date), nullable): Required whengdprConsentis GRANTEDid(string (uuid)): Id of the contact personinfo(string): Info textisActive(boolean): False whenleftAtis set (defaulttrue)isBlocked(boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set withPOST /addresses/{id}/contacts/{cid}/blockisDefault(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; setsisActivefalseletterSalutation(string): Salutation line of letterslinkedinUrl(string (uri)): LinkedIn profile (max length 255)mobile(string): E.164namePrefix(string): Name prefixnameSuffix(string): Name suffixphone1(string): E.164phone2(string): E.164portalUserId(string): Linked desk portal user (max length 255)position(string): PositionpostalAddressAnsNr(integer, nullable):ansNrof a postal address of the same addresspreferredChannel(string): Preferred contact channel (one ofEMAIL,PHONE,MOBILE,LETTER,PORTAL)reportsToAspNr(integer, nullable):aspNrof the manager within the same address (no cycles)roles(array of string): Roles in the buying centre or for ticket routingsalutationCode(string): Code ofsalutationstimezone(string): IANA time zonetitle(string): Titleversion(integer): Version of this contact (child updates)
createdAt(string (date-time), read-only): Creation timecreatedBy(string, read-only): Who created the address (subject of the token)creditLimit(number, nullable): Credit limitcreditorAccountNo(string): Creditor account. WithglAccountLengthg it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)currencyCode(string): ISO 4217customFields(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.customerNo(string, read-only): Tenant customer number (from the token)customerNumber(string): Customer number (Kundennummer), unique among the live addresses of the tenant (409customer_number_taken). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)customerSince(string (date), nullable): Customer since (YYYY-MM-DD)dataQualityScore(integer, read-only): Completeness score computed on save (max 100)deletionBlockedUntil(string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addressesdeliveryBlockReason(string, read-only): Reason of the delivery blockdeliveryBlocked(boolean, read-only): Delivery block (set withPOST /addresses/{id}/blocks; a PUT keeps it)deliveryBlockedAt(string (date-time), read-only): Time of the delivery blockdeliveryBlockedBy(string, read-only): Actor of the delivery blockdeliveryCondition(string): Delivery condition (free text) (max length 255)discountRate(number, nullable): Discount in percent (max 100)displayName(string, read-only): Company name, else first and last namedistributorIds(array of DistributorID, read-only): Maintained via /api/masterdata/distributor-idsaddressId(string (uuid), required): Supplier address the distributor ID maps toaddressName(string, required): Display name of that addressadrNr(string, required): Address number of that addressdistributorId(string, required): The distributor's own IDsource(string, required): Distributor (lower case, e.g. egis, ingram)updatedAt(string (date-time), required): Time of the last changedistributorName(string): Name of the distributor
dunningBlocked(boolean): Dunning block (also set withPOST /addresses/{id}/blocks, type DUNNING)dunningBlockedAt(string (date-time), read-only): Time of the dunning blockdunningBlockedBy(string, read-only): Actor of the dunning blockeInvoiceBuyerRef(string): Leitweg-ID (XRechnung buyer reference)eInvoiceFormat(string): Preferred e-invoice format (one ofXRECHNUNG,ZUGFERD,PEPPOL,PDF)email(string (email)): Main e-mail address (max length 255)employeeCount(integer, nullable): Number of employeesenrichedAt(string (date-time), read-only): Time of the last enrichmentenrichmentData(any): Free JSON of an enrichmentenrichmentStatus(string): State of the data enrichment (one ofNOT_ENRICHED,PENDING,ENRICHED,FAILED; default"NOT_ENRICHED")externalIds(object): Keys of other systems, at most 20; key^[a-z0-9_-]{1,64}$, value max. 255 charactersfax(string): E.164 (max length 64)firstName(string): First name (of a person) (max length 128)gdprConsent(string): GDPR consent state (one ofUNKNOWN,GRANTED,DENIED,REVOKED; default"UNKNOWN")gdprConsentDate(string (date), nullable): Required whengdprConsentis GRANTEDgdprDataOrigin(string): GDPR: where the data came from (max length 255)gdprPurpose(string): GDPR: purpose of the processing (max length 255)gln(string): Global Location Number with check digitid(string (uuid), read-only): Id of the addressindustryCode(string): Code ofindustriesinfo(string): Info textinvoiceEmail(string (email)): E-mail address for invoices (max length 255)isBlocked(boolean): General block of the addressisDiscountEligible(boolean): Discounts may be grantedisEuForeign(boolean, read-only): Derived likeisForeign(both countries in the EU)isForeign(boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on writeisOneTime(boolean): One-time account (Diverse)isTaxInclusive(boolean): Prices are gross (tax inclusive)languageCode(string): ISO 639-1, optionally with regionlastName(string): Last name (required forpartyTypePERSON) (max length 128)legalForm(string): Legal form (max length 64)marketingObjection(boolean): Objection to advertisingmarketingObjectionAt(string (date-time), nullable, read-only): Set by the server whenmarketingObjectionturns truememo(string): Internal memomergedIntoId(string (uuid), read-only): Set when the address was merged into another onemobile(string): E.164 (max length 64)netDays(integer, nullable): Payment term in days (net)ourCustomerNumber(string): Our customer number at this party (max length 64)parentAddressId(string (uuid)): Parent company (another address of the tenant; no cycles)parentName(string, read-only): Display name of the parent address (set on read)partyType(string): COMPANY needscompanyName, PERSON needslastName(one ofCOMPANY,PERSON; default"COMPANY")paymentBlockReason(string, read-only): Reason of the payment blockpaymentBlocked(boolean, read-only): Payment block (set withPOST /addresses/{id}/blocks; a PUT keeps it)paymentBlockedAt(string (date-time), read-only): Time of the payment blockpaymentBlockedBy(string, read-only): Actor of the payment blockpaymentMethodCode(string): Code ofpayment-methodspaymentTermCode(string): Code ofpayment-termspeppolId(string): Peppol participant IDscheme:idphone(string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)postalAddresses(array of PostalAddress): Postal addresses (Anschriften)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
postingAccountNo(string): Debtor account (Debitorenkonto). With the tenant'sglAccountLengthg it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)purchaseOrderEmail(string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back toemail(max length 254)purchaseOrderRequired(boolean, nullable): Invoices of this supplier need a purchase order. Omitted:trueon create, unchanged on updateregisterCourt(string): Register court (max length 128)reverseCharge(boolean): Reverse charge (§13b UStG)roles(array of string, read-only): Derived from the flags of the status (isCustomerCUSTOMER,isVendorSUPPLIER,isLeadPROSPECT,isPartnerPARTNER); a value in the request is ignoredsalesRepCommissionRate(number, nullable): Commission of the sales representative in percent (max 100)salesRepNo(string): Number of the sales representative (max length 32)salutationCode(string): Code ofsalutationssearchTerm(string): Search term (Suchbegriff); derived from the name when empty (max length 255)sepaMandates(array of SepaMandate): SEPA direct debit mandatesbankAccountIban(string, required): IBAN of a bank account of this addresssignedAt(string (date), required): Date of signature (YYYY-MM-DD)bankAccountId(string (uuid), read-only): Id of the linked bank accountcreditorId(string): Creditor identifier (max length 35)id(string (uuid)): Id of the mandatelastUsedAt(string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED insteadmandateReference(string): Assigned from the MANDATE range when emptymandateType(string): CORE or B2B direct debit (one ofCORE,B2B; default"CORE")revokedAt(string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)sequenceType(string): Sequence type of the next collection (one ofFRST,RCUR,OOFF,FNAL; default"FRST")status(string): State of the mandate (one ofACTIVE,REVOKED,EXPIRED; default"ACTIVE")validFrom(string (date), nullable): Valid from (YYYY-MM-DD)
shippingTypeCode(string): Code ofshipping-typesskontoDays1(integer, nullable): Days for the first cash discountskontoDays2(integer, nullable): Days for the second cash discountskontoRate1(number, nullable): First cash discount in percent (max 100)skontoRate2(number, nullable): Second cash discount in percent (max 100)smallBusiness(boolean): Small business (§19 UStG)source(string): Where the address came from (lead source) (max length 64)supplierNumber(string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (409supplier_number_taken). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)syncStatus(string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one ofSTANDALONE,PENDING_CREATION,PENDING_UPDATE,SYNCED,CONFLICT,ERROR)tags(array of string): Duplicates (case-insensitive) are removedtaxNumber(string): Tax number (Steuernummer) (max length 64)taxZone(string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU withvatId), EU_PRIVATE (EU withoutvatId), THIRD_COUNTRY; empty without a postal address. Ignored on write.vatCategorystays for compatibility (one ofDOMESTIC,EU_VATID,EU_PRIVATE,THIRD_COUNTRY)tenantName(string, read-only): Tenant name (from the token)title(string): Title of the party (e.g. Dr.) (max length 64)updatedAt(string (date-time), read-only): Time of the last changeupdatedBy(string, read-only): Who changed the address last (subject of the token)valutaDays(integer, nullable): Value date daysvatCategory(integer): VAT category (microtech) (max 9)vatCheckStatus(VatCheckStatus, read-only): Result of the latest official VAT check (one ofOFFICIALLY_CONFIRMED,PARTIALLY_CONFIRMED,OFFICIALLY_NOT_CONFIRMED,FORMALLY_VALID_NO_OFFICIAL_CHECK,FORMALLY_INVALID,CHECK_NOT_POSSIBLE,TECHNICAL_ERROR,NOT_CHECKED)vatCheckedAt(string (date-time), read-only): Time of the latest official VAT checkvatId(string): VAT ID (USt-IdNr.)website(string (uri)): Website (max length 255)
Example:
{
"bankAccounts": [
{
"bankName": "Deutsche Kreditbank",
"bic": "BYLADEM1001",
"iban": "DE02120300000000202051",
"isDefault": true
}
],
"companyName": "Muster GmbH",
"contactPersons": [
{
"email1": "erika.musterfrau@muster.de",
"firstName": "Erika",
"isDefault": true,
"lastName": "Musterfrau",
"position": "Leitung Einkauf",
"roles": [
"PURCHASING"
],
"salutationCode": "FRAU"
}
],
"customerNumber": "10023",
"email": "info@muster.de",
"legalForm": "GmbH",
"partyType": "COMPANY",
"paymentTermCode": "NETTO30",
"phone": "+49 30 1234567",
"postalAddresses": [
{
"city": "Berlin",
"countryCode": "DE",
"isDefaultBilling": true,
"isDefaultShipping": true,
"postalCode": "10115",
"street": "Hauptstraße 1"
}
],
"statusCode": "KUNDE",
"tags": [
"Stammkunde"
],
"vatId": "DE123456789",
"website": "https://www.muster.de"
}
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) - 409 Stale version or conflict with existing data (
application/json) - 413 The body is over the limit (2 MiB; AI drafts 4 MiB) (
application/json)
Fields of the 201 answer:
statusCode(string, required): Code ofaddress-statuses(required). Its flags decide therolesversion(integer, required): Optimistic locking version; send the version you read (ignored on create)accountOwner(string): Account owner (responsible person) in CRM (max length 255)accountType(string): Individual or collective account (one ofINDIVIDUAL,COLLECTIVE; default"INDIVIDUAL")additionalName(string): Name addition (second name line) (max length 255)adrNr(string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)annualRevenue(number, nullable): Annual revenuebankAccounts(array of BankAccount): Bank accountsiban(string, required): Unique per addressaccountHolder(string): Account holder (max length 255)bankName(string): Name of the bank (max length 128)bic(string): BICid(string (uuid)): Id of the bank accountisDefault(boolean): At most one; the first account is the default when none is set
blockReason(string): Cleared whenisBlockedis false (max length 255)blockedAt(string (date-time), read-only): Time of the general blockblockedBy(string, read-only): Actor of the general blockcommercialRegister(string): Commercial register number (Handelsregister) (max length 128)companyName(string): Company name (required forpartyTypeCOMPANY) (max length 255)contactPersons(array of ContactPerson): Contact persons (Ansprechpartner)aspNr(integer): Number within the address; assignedavailableFrom1(string, nullable): Reachable from (HH:MM)availableFrom2(string, nullable): Second time window: reachable from (HH:MM)availableTo1(string, nullable): AfteravailableFrom1availableTo2(string, nullable): AfteravailableFrom2birthday(string (date), nullable): Birthday (YYYY-MM-DD)blockReason(string, read-only): Reason of the blockblockedAt(string (date-time), read-only): Time of the blockblockedBy(string, read-only): Actor of the blockcustomFields(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.department(string): DepartmentdoNotCall(boolean): Do not callemail1(string (email)): First e-mail addressemail2(string (email)): Second e-mail addressemailOptOut(boolean): No marketing e-mailsfax(string): E.164firstName(string): First name (max length 128)gdprConsent(string): GDPR consent state (one ofUNKNOWN,GRANTED,DENIED,REVOKED; default"UNKNOWN")gdprConsentDate(string (date), nullable): Required whengdprConsentis GRANTEDid(string (uuid)): Id of the contact personinfo(string): Info textisActive(boolean): False whenleftAtis set (defaulttrue)isBlocked(boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set withPOST /addresses/{id}/contacts/{cid}/blockisDefault(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; setsisActivefalseletterSalutation(string): Salutation line of letterslinkedinUrl(string (uri)): LinkedIn profile (max length 255)mobile(string): E.164namePrefix(string): Name prefixnameSuffix(string): Name suffixphone1(string): E.164phone2(string): E.164portalUserId(string): Linked desk portal user (max length 255)position(string): PositionpostalAddressAnsNr(integer, nullable):ansNrof a postal address of the same addresspreferredChannel(string): Preferred contact channel (one ofEMAIL,PHONE,MOBILE,LETTER,PORTAL)reportsToAspNr(integer, nullable):aspNrof the manager within the same address (no cycles)roles(array of string): Roles in the buying centre or for ticket routingsalutationCode(string): Code ofsalutationstimezone(string): IANA time zonetitle(string): Titleversion(integer): Version of this contact (child updates)
createdAt(string (date-time), read-only): Creation timecreatedBy(string, read-only): Who created the address (subject of the token)creditLimit(number, nullable): Credit limitcreditorAccountNo(string): Creditor account. WithglAccountLengthg it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)currencyCode(string): ISO 4217customFields(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.customerNo(string, read-only): Tenant customer number (from the token)customerNumber(string): Customer number (Kundennummer), unique among the live addresses of the tenant (409customer_number_taken). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)customerSince(string (date), nullable): Customer since (YYYY-MM-DD)dataQualityScore(integer, read-only): Completeness score computed on save (max 100)deletionBlockedUntil(string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addressesdeliveryBlockReason(string, read-only): Reason of the delivery blockdeliveryBlocked(boolean, read-only): Delivery block (set withPOST /addresses/{id}/blocks; a PUT keeps it)deliveryBlockedAt(string (date-time), read-only): Time of the delivery blockdeliveryBlockedBy(string, read-only): Actor of the delivery blockdeliveryCondition(string): Delivery condition (free text) (max length 255)discountRate(number, nullable): Discount in percent (max 100)displayName(string, read-only): Company name, else first and last namedistributorIds(array of DistributorID, read-only): Maintained via /api/masterdata/distributor-idsaddressId(string (uuid), required): Supplier address the distributor ID maps toaddressName(string, required): Display name of that addressadrNr(string, required): Address number of that addressdistributorId(string, required): The distributor's own IDsource(string, required): Distributor (lower case, e.g. egis, ingram)updatedAt(string (date-time), required): Time of the last changedistributorName(string): Name of the distributor
dunningBlocked(boolean): Dunning block (also set withPOST /addresses/{id}/blocks, type DUNNING)dunningBlockedAt(string (date-time), read-only): Time of the dunning blockdunningBlockedBy(string, read-only): Actor of the dunning blockeInvoiceBuyerRef(string): Leitweg-ID (XRechnung buyer reference)eInvoiceFormat(string): Preferred e-invoice format (one ofXRECHNUNG,ZUGFERD,PEPPOL,PDF)email(string (email)): Main e-mail address (max length 255)employeeCount(integer, nullable): Number of employeesenrichedAt(string (date-time), read-only): Time of the last enrichmentenrichmentData(any): Free JSON of an enrichmentenrichmentStatus(string): State of the data enrichment (one ofNOT_ENRICHED,PENDING,ENRICHED,FAILED; default"NOT_ENRICHED")externalIds(object): Keys of other systems, at most 20; key^[a-z0-9_-]{1,64}$, value max. 255 charactersfax(string): E.164 (max length 64)firstName(string): First name (of a person) (max length 128)gdprConsent(string): GDPR consent state (one ofUNKNOWN,GRANTED,DENIED,REVOKED; default"UNKNOWN")gdprConsentDate(string (date), nullable): Required whengdprConsentis GRANTEDgdprDataOrigin(string): GDPR: where the data came from (max length 255)gdprPurpose(string): GDPR: purpose of the processing (max length 255)gln(string): Global Location Number with check digitid(string (uuid), read-only): Id of the addressindustryCode(string): Code ofindustriesinfo(string): Info textinvoiceEmail(string (email)): E-mail address for invoices (max length 255)isBlocked(boolean): General block of the addressisDiscountEligible(boolean): Discounts may be grantedisEuForeign(boolean, read-only): Derived likeisForeign(both countries in the EU)isForeign(boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on writeisOneTime(boolean): One-time account (Diverse)isTaxInclusive(boolean): Prices are gross (tax inclusive)languageCode(string): ISO 639-1, optionally with regionlastName(string): Last name (required forpartyTypePERSON) (max length 128)legalForm(string): Legal form (max length 64)marketingObjection(boolean): Objection to advertisingmarketingObjectionAt(string (date-time), nullable, read-only): Set by the server whenmarketingObjectionturns truememo(string): Internal memomergedIntoId(string (uuid), read-only): Set when the address was merged into another onemobile(string): E.164 (max length 64)netDays(integer, nullable): Payment term in days (net)ourCustomerNumber(string): Our customer number at this party (max length 64)parentAddressId(string (uuid)): Parent company (another address of the tenant; no cycles)parentName(string, read-only): Display name of the parent address (set on read)partyType(string): COMPANY needscompanyName, PERSON needslastName(one ofCOMPANY,PERSON; default"COMPANY")paymentBlockReason(string, read-only): Reason of the payment blockpaymentBlocked(boolean, read-only): Payment block (set withPOST /addresses/{id}/blocks; a PUT keeps it)paymentBlockedAt(string (date-time), read-only): Time of the payment blockpaymentBlockedBy(string, read-only): Actor of the payment blockpaymentMethodCode(string): Code ofpayment-methodspaymentTermCode(string): Code ofpayment-termspeppolId(string): Peppol participant IDscheme:idphone(string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)postalAddresses(array of PostalAddress): Postal addresses (Anschriften)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
postingAccountNo(string): Debtor account (Debitorenkonto). With the tenant'sglAccountLengthg it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)purchaseOrderEmail(string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back toemail(max length 254)purchaseOrderRequired(boolean, nullable): Invoices of this supplier need a purchase order. Omitted:trueon create, unchanged on updateregisterCourt(string): Register court (max length 128)reverseCharge(boolean): Reverse charge (§13b UStG)roles(array of string, read-only): Derived from the flags of the status (isCustomerCUSTOMER,isVendorSUPPLIER,isLeadPROSPECT,isPartnerPARTNER); a value in the request is ignoredsalesRepCommissionRate(number, nullable): Commission of the sales representative in percent (max 100)salesRepNo(string): Number of the sales representative (max length 32)salutationCode(string): Code ofsalutationssearchTerm(string): Search term (Suchbegriff); derived from the name when empty (max length 255)sepaMandates(array of SepaMandate): SEPA direct debit mandatesbankAccountIban(string, required): IBAN of a bank account of this addresssignedAt(string (date), required): Date of signature (YYYY-MM-DD)bankAccountId(string (uuid), read-only): Id of the linked bank accountcreditorId(string): Creditor identifier (max length 35)id(string (uuid)): Id of the mandatelastUsedAt(string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED insteadmandateReference(string): Assigned from the MANDATE range when emptymandateType(string): CORE or B2B direct debit (one ofCORE,B2B; default"CORE")revokedAt(string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)sequenceType(string): Sequence type of the next collection (one ofFRST,RCUR,OOFF,FNAL; default"FRST")status(string): State of the mandate (one ofACTIVE,REVOKED,EXPIRED; default"ACTIVE")validFrom(string (date), nullable): Valid from (YYYY-MM-DD)
shippingTypeCode(string): Code ofshipping-typesskontoDays1(integer, nullable): Days for the first cash discountskontoDays2(integer, nullable): Days for the second cash discountskontoRate1(number, nullable): First cash discount in percent (max 100)skontoRate2(number, nullable): Second cash discount in percent (max 100)smallBusiness(boolean): Small business (§19 UStG)source(string): Where the address came from (lead source) (max length 64)supplierNumber(string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (409supplier_number_taken). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)syncStatus(string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one ofSTANDALONE,PENDING_CREATION,PENDING_UPDATE,SYNCED,CONFLICT,ERROR)tags(array of string): Duplicates (case-insensitive) are removedtaxNumber(string): Tax number (Steuernummer) (max length 64)taxZone(string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU withvatId), EU_PRIVATE (EU withoutvatId), THIRD_COUNTRY; empty without a postal address. Ignored on write.vatCategorystays for compatibility (one ofDOMESTIC,EU_VATID,EU_PRIVATE,THIRD_COUNTRY)tenantName(string, read-only): Tenant name (from the token)title(string): Title of the party (e.g. Dr.) (max length 64)updatedAt(string (date-time), read-only): Time of the last changeupdatedBy(string, read-only): Who changed the address last (subject of the token)valutaDays(integer, nullable): Value date daysvatCategory(integer): VAT category (microtech) (max 9)vatCheckStatus(VatCheckStatus, read-only): Result of the latest official VAT check (one ofOFFICIALLY_CONFIRMED,PARTIALLY_CONFIRMED,OFFICIALLY_NOT_CONFIRMED,FORMALLY_VALID_NO_OFFICIAL_CHECK,FORMALLY_INVALID,CHECK_NOT_POSSIBLE,TECHNICAL_ERROR,NOT_CHECKED)vatCheckedAt(string (date-time), read-only): Time of the latest official VAT checkvatId(string): VAT ID (USt-IdNr.)website(string (uri)): Website (max length 255)
Example 201 answer:
{
"accountOwner": "Lena Vogel",
"accountType": "INDIVIDUAL",
"adrNr": "10001",
"bankAccounts": [
{
"accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"bankName": "Commerzbank",
"bic": "COBADEFFXXX",
"iban": "DE89370400440532013000",
"id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
"isDefault": true
}
],
"commercialRegister": "HRA 4711",
"companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"contactPersons": [
{
"aspNr": 1,
"email1": "georg.moser@alpenhotel-seeblick.example",
"firstName": "Georg",
"gdprConsent": "UNKNOWN",
"id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
"isActive": true,
"isDefault": true,
"lastName": "Moser",
"letterSalutation": "Sehr geehrter Herr Moser",
"phone1": "+49865298760",
"position": "Geschäftsführer",
"postalAddressAnsNr": 1,
"roles": [
"DECISION_MAKER"
],
"salutationCode": "HERR",
"version": 1
},
{
"aspNr": 2,
"availableFrom1": "08:00",
"availableTo1": "16:00",
"customFields": {},
"doNotCall": false,
"email1": "katrin.stadler@alpenhotel-seeblick.example",
"emailOptOut": false,
"firstName": "Katrin",
"gdprConsent": "UNKNOWN",
"id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
"isActive": true,
"isBlocked": false,
"isDefault": false,
"languageCode": "de",
"lastName": "Stadler",
"letterSalutation": "Sehr geehrte Frau Stadler",
"phone1": "+498652987612",
"position": "Empfangsleitung und IT",
"postalAddressAnsNr": 1,
"preferredChannel": "PHONE",
"roles": [
"TECHNICAL",
"SUPPORT"
],
"salutationCode": "FRAU",
"timezone": "Europe/Berlin",
"version": 3
}
],
"createdAt": "2026-01-02T08:00:00Z",
"createdBy": "laura.kaestner@muster-it.example",
"currencyCode": "EUR",
"customFields": {
"branche": "hotel"
},
"customerNo": "99999",
"customerNumber": "10001",
"customerSince": "2019-04-01",
"dataQualityScore": 90,
"deliveryBlocked": false,
"displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"distributorIds": [
{
"addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
"addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"adrNr": "10001",
"distributorId": "700123",
"distributorName": "EGIS Computer Service-Center GmbH",
"source": "egis",
"updatedAt": "2026-05-20T11:40:00Z"
}
],
"dunningBlocked": false,
"eInvoiceFormat": "ZUGFERD",
"email": "rezeption@alpenhotel-seeblick.example",
"employeeCount": 38,
"enrichmentStatus": "NOT_ENRICHED",
"gdprConsent": "UNKNOWN",
"id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
"invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
"isBlocked": false,
"isDiscountEligible": true,
"isEuForeign": false,
"isForeign": false,
"isOneTime": false,
"isTaxInclusive": false,
"languageCode": "de",
"legalForm": "GmbH \u0026 Co. KG",
"marketingObjection": false,
"netDays": 30,
"partyType": "COMPANY",
"paymentBlocked": false,
"paymentMethodCode": "UEBERWEISUNG",
"paymentTermCode": "NETTO30",
"phone": "+49865298760",
"postalAddresses": [
{
"ansNr": 1,
"city": "Schönau am Königssee",
"countryCode": "DE",
"county": "Berchtesgadener Land",
"customFields": {},
"distanceKm": 142.7,
"driveMinutes": 109,
"email1": "rezeption@alpenhotel-seeblick.example",
"geocodePrecision": "HOUSE",
"geocodeStatus": "DONE",
"geocodedAt": "2026-03-14T10:02:31Z",
"id": "2c4e6a8c-0d2f-4b4c-9e6a-8c0e2a4c6e8a",
"isBlocked": false,
"isDefaultBilling": true,
"isDefaultDunning": true,
"isDefaultInfo": true,
"isDefaultService": false,
"isDefaultShipping": true,
"latitude": 47.5986,
"longitude": 12.9894,
"municipality": "Schönau a.Königssee",
"name1": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"phone": "+49865298760",
"postalCode": "83471",
"region": "DE-BY",
"routeApproximate": false,
"routeStatus": "DONE",
"routedAt": "2026-03-14T10:03:05Z",
"street": "Seestraße 4",
"validationStatus": "VERIFIED",
"version": 2
}
],
"postingAccountNo": "10001",
"registerCourt": "Amtsgericht Traunstein",
"reverseCharge": false,
"roles": [
"CUSTOMER"
],
"searchTerm": "ALPENHOTEL SEEBLICK",
"sepaMandates": [],
"smallBusiness": false,
"statusCode": "KUNDE",
"syncStatus": "STANDALONE",
"tags": [
"Wartungsvertrag"
],
"taxZone": "DOMESTIC",
"tenantName": "DEMO",
"updatedAt": "2026-11-03T09:14:22Z",
"updatedBy": "christina.adler@muster-it.example",
"vatCheckStatus": "OFFICIALLY_CONFIRMED",
"vatCheckedAt": "2026-11-03T09:14:22Z",
"vatId": "DE811234567",
"version": 7,
"website": "https://www.alpenhotel-seeblick.example"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"bankAccounts":[{"bankName":"Deutsche Kreditbank","bic":"BYLADEM1001","iban":"DE02120300000000202051","isDefault":true}],"companyName":"Muster GmbH","contactPersons":[{"email1":"erika.musterfrau@muster.de","firstName":"Erika","isDefault":true,"lastName":"Musterfrau","position":"Leitung Einkauf","roles":["PURCHASING"],"salutationCode":"FRAU"}],"customerNumber":"10023","email":"info@muster.de","legalForm":"GmbH","partyType":"COMPANY","paymentTermCode":"NETTO30","phone":"+49 30 1234567","postalAddresses":[{"city":"Berlin","countryCode":"DE","isDefaultBilling":true,"isDefaultShipping":true,"postalCode":"10115","street":"Hauptstraße 1"}],"statusCode":"KUNDE","tags":["Stammkunde"],"vatId":"DE123456789","website":"https://www.muster.de"}'