ConnectCloud Developers

Find possible duplicates of an address (tenant:masterdata:read)

POST /api/masterdata/addresses:duplicates

Module: Master data · operationId: findAddressDuplicates · Tag: Addresses · Auth: access token (Authorization: Bearer <accessToken>)

Checks an address (body as for POST /api/masterdata/addresses; nothing is stored) against the tenant's addresses and returns up to 10 candidates with a score of at least 40 (0–100), best first. Strong identifiers (VAT ID, IBAN, customer and supplier number, email) count most; a similar name counts more with the same postal code.

Parameters

Name In Type Required Description
excludeId query string (uuid) Skip this address (the one being edited)

Request body

application/json (required)

  • statusCode (string, required): Code of address-statuses (required). Its flags decide the roles
  • version (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 of INDIVIDUAL, 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 revenue
  • bankAccounts (array of BankAccount): Bank accounts
    • iban (string, required): Unique per address
    • accountHolder (string): Account holder (max length 255)
    • bankName (string): Name of the bank (max length 128)
    • bic (string): BIC
    • id (string (uuid)): Id of the bank account
    • isDefault (boolean): At most one; the first account is the default when none is set
  • blockReason (string): Cleared when isBlocked is false (max length 255)
  • blockedAt (string (date-time), read-only): Time of the general block
  • blockedBy (string, read-only): Actor of the general block
  • commercialRegister (string): Commercial register number (Handelsregister) (max length 128)
  • companyName (string): Company name (required for partyType COMPANY) (max length 255)
  • contactPersons (array of ContactPerson): Contact persons (Ansprechpartner)
    • 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)
  • createdAt (string (date-time), read-only): Creation time
  • createdBy (string, read-only): Who created the address (subject of the token)
  • creditLimit (number, nullable): Credit limit
  • creditorAccountNo (string): Creditor account. With glAccountLength g 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 4217
  • 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.
  • customerNo (string, read-only): Tenant customer number (from the token)
  • customerNumber (string): Customer number (Kundennummer), unique among the live addresses of the tenant (409 customer_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 addresses
  • deliveryBlockReason (string, read-only): Reason of the delivery block
  • deliveryBlocked (boolean, read-only): Delivery block (set with POST /addresses/{id}/blocks; a PUT keeps it)
  • deliveryBlockedAt (string (date-time), read-only): Time of the delivery block
  • deliveryBlockedBy (string, read-only): Actor of the delivery block
  • deliveryCondition (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 name
  • distributorIds (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
    • addressId (string (uuid), required): Supplier address the distributor ID maps to
    • addressName (string, required): Display name of that address
    • adrNr (string, required): Address number of that address
    • distributorId (string, required): The distributor's own ID
    • source (string, required): Distributor (lower case, e.g. egis, ingram)
    • updatedAt (string (date-time), required): Time of the last change
    • distributorName (string): Name of the distributor
  • dunningBlocked (boolean): Dunning block (also set with POST /addresses/{id}/blocks, type DUNNING)
  • dunningBlockedAt (string (date-time), read-only): Time of the dunning block
  • dunningBlockedBy (string, read-only): Actor of the dunning block
  • eInvoiceBuyerRef (string): Leitweg-ID (XRechnung buyer reference)
  • eInvoiceFormat (string): Preferred e-invoice format (one of XRECHNUNG, ZUGFERD, PEPPOL, PDF)
  • email (string (email)): Main e-mail address (max length 255)
  • employeeCount (integer, nullable): Number of employees
  • enrichedAt (string (date-time), read-only): Time of the last enrichment
  • enrichmentData (any): Free JSON of an enrichment
  • enrichmentStatus (string): State of the data enrichment (one of NOT_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 characters
  • fax (string): E.164 (max length 64)
  • firstName (string): First name (of a person) (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
  • gdprDataOrigin (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 digit
  • id (string (uuid), read-only): Id of the address
  • industryCode (string): Code of industries
  • info (string): Info text
  • invoiceEmail (string (email)): E-mail address for invoices (max length 255)
  • isBlocked (boolean): General block of the address
  • isDiscountEligible (boolean): Discounts may be granted
  • isEuForeign (boolean, read-only): Derived like isForeign (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 write
  • isOneTime (boolean): One-time account (Diverse)
  • isTaxInclusive (boolean): Prices are gross (tax inclusive)
  • languageCode (string): ISO 639-1, optionally with region
  • lastName (string): Last name (required for partyType PERSON) (max length 128)
  • legalForm (string): Legal form (max length 64)
  • marketingObjection (boolean): Objection to advertising
  • marketingObjectionAt (string (date-time), nullable, read-only): Set by the server when marketingObjection turns true
  • memo (string): Internal memo
  • mergedIntoId (string (uuid), read-only): Set when the address was merged into another one
  • mobile (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 needs companyName, PERSON needs lastName (one of COMPANY, PERSON; default "COMPANY")
  • paymentBlockReason (string, read-only): Reason of the payment block
  • paymentBlocked (boolean, read-only): Payment block (set with POST /addresses/{id}/blocks; a PUT keeps it)
  • paymentBlockedAt (string (date-time), read-only): Time of the payment block
  • paymentBlockedBy (string, read-only): Actor of the payment block
  • paymentMethodCode (string): Code of payment-methods
  • paymentTermCode (string): Code of payment-terms
  • peppolId (string): Peppol participant ID scheme:id
  • phone (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 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
  • postingAccountNo (string): Debtor account (Debitorenkonto). With the tenant's glAccountLength g 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 to email (max length 254)
  • purchaseOrderRequired (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: true on create, unchanged on update
  • registerCourt (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 (isCustomer CUSTOMER, isVendor SUPPLIER, isLead PROSPECT, isPartner PARTNER); a value in the request is ignored
  • salesRepCommissionRate (number, nullable): Commission of the sales representative in percent (max 100)
  • salesRepNo (string): Number of the sales representative (max length 32)
  • salutationCode (string): Code of salutations
  • searchTerm (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
  • sepaMandates (array of SepaMandate): SEPA direct debit mandates
    • bankAccountIban (string, required): IBAN of a bank account of this address
    • signedAt (string (date), required): Date of signature (YYYY-MM-DD)
    • bankAccountId (string (uuid), read-only): Id of the linked bank account
    • creditorId (string): Creditor identifier (max length 35)
    • id (string (uuid)): Id of the mandate
    • lastUsedAt (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 instead
    • mandateReference (string): Assigned from the MANDATE range when empty
    • mandateType (string): CORE or B2B direct debit (one of CORE, 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 of FRST, RCUR, OOFF, FNAL; default "FRST")
    • status (string): State of the mandate (one of ACTIVE, REVOKED, EXPIRED; default "ACTIVE")
    • validFrom (string (date), nullable): Valid from (YYYY-MM-DD)
  • shippingTypeCode (string): Code of shipping-types
  • skontoDays1 (integer, nullable): Days for the first cash discount
  • skontoDays2 (integer, nullable): Days for the second cash discount
  • skontoRate1 (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 (409 supplier_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 of STANDALONE, PENDING_CREATION, PENDING_UPDATE, SYNCED, CONFLICT, ERROR)
  • tags (array of string): Duplicates (case-insensitive) are removed
  • taxNumber (string): Tax number (Steuernummer) (max length 64)
  • taxZone (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with vatId), EU_PRIVATE (EU without vatId), THIRD_COUNTRY; empty without a postal address. Ignored on write. vatCategory stays for compatibility (one of DOMESTIC, 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 change
  • updatedBy (string, read-only): Who changed the address last (subject of the token)
  • valutaDays (integer, nullable): Value date days
  • vatCategory (integer): VAT category (microtech) (max 9)
  • vatCheckStatus (VatCheckStatus, read-only): Result of the latest official VAT check (one of OFFICIALLY_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 check
  • vatId (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

  • 200 Candidates (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)

Fields of the 200 answer:

  • candidates (array of DuplicateCandidate, required): Up to 10 candidates, best first
    • adrNr (string, required): Address number
    • displayName (string, required): Display name
    • id (string (uuid), required): Id of the existing address
    • reasons (array of string, required): Why it may be the same
    • score (integer, required): Similarity score (at least 40) (max 100)
    • city (string): City of the default billing postal address (else the lowest ansNr)

Example 200 answer:

{
  "candidates": [
    {
      "adrNr": "10001",
      "city": "Schönau am Königssee",
      "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "reasons": [
        "VAT_ID",
        "EMAIL_DOMAIN",
        "NAME"
      ],
      "score": 95
    }
  ]
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses:duplicates' \
  -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"}'

View as Markdown · Interactive reference · OpenAPI