Insert customer

Request

Security

OAuth2(Required scopes: enrichment.write)

Bodyapplication/jsonrequired

externalIdstring^\S+$required

External id of the customer that is globally unique across the provided customer data

Example:"0000100000"

externalClientIdstring

Identifier of the client entity in the source system which can be used to separate data

Example:"EXTERNAL_CLIENT_ID"

codestring

Code of the customer in the source system (not unique across clients)

Example:"CODE1"

typestring

Type (role) of the customer as defined in the source system (e.g. SOLD_TO, SHIP_TO, BILL_TO, PAYER)

Example:"SOLD_TO"

namestring^[\S ]*\S[\S ]*$required

Name of the customer

Example:"Acmne Corp."

nameAlternative1string

Alternative name of the customer

Example:"Acmne Corp."

nameAlternative2string

Alternative name of the customer

Example:"Acmne Corp."

nameAlternative3string

Alternative name of the customer

Example:"Acmne Corp."

nameAlternative4string

Alternative name of the customer

Example:"Acmne Corp."

streetstring

Street and street number where the customer is located

Example:"Hauptstr. 1"

addressAdditionalstring

Additional address data (e.g. apartment or suite)

Example:"Eingang B"

postcodestring

Postcode where the customer is located

Example:"10001"

citystring

City where the customer is located

Example:"Berlin"

countryCodestring or null(CountryCode)

Two letter country code as defined in ISO 3166-1 alpha-2

Enum:"AF""AX""AL""DZ""AS""AD""AO""AI""AQ""AG"

Example:"DE"

vatIdsArray of objects(vatId)

List of VAT IDs assigned to the customer

Example:

[
  {
    "id": "DE123456789",
    "countryCode": "DE"
  }
]

taxIdsArray of objects(taxId)

List of Tax IDs assigned to the customer

Example:

[
  {
    "id": "123-456-789",
    "type": "TIN"
  }
]

blockedForPostingboolean

Indicator if the customer is blocked for posting

Example:false

blockedForPaymentboolean

Indicator if the customer is blocked for payment

Example:false

blockedForOrderingboolean

Indicator if the customer is blocked for ordering globally

Example:false

blockedForDeliveryboolean

Indicator if the customer is blocked for delivery globally

Example:false

globalLocationNumberstring

13-digit Global Location Number (GLN) used for unique location identification in B2B transactions

Example:"4000001000002"

dunsstring

D-U-N-S Number issued by Dun & Bradstreet. A globally used identifier for business entities.

Example:"123456789"

customerSubsidiariesArray of objects(subsidiary)

customerBankAccountsArray of objects(bankAccount)

customFieldsobject(customFields)

List of key value pairs containing custom fields from the source system

customMetadataobject(JsonObject)

Any nested structure with metadata that source system needs to send

Example:

{
  "someTopLevelProperty": "value1",
  "someNestedProperty": {
    "nestedProperty": "value2"
  },
  "someArrayProperty": [
    "value3",
    "value4"
  ]
}

salesOrganizationInfoArray of objects(customerSalesOrganizationInfo)

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/customers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "0000100000",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "code": "CODE1",
    "type": "SOLD_TO",
    "name": "Acmne Corp.",
    "nameAlternative1": "Acmne Corp.",
    "nameAlternative2": "Acmne Corp.",
    "nameAlternative3": "Acmne Corp.",
    "nameAlternative4": "Acmne Corp.",
    "street": "Hauptstr. 1",
    "addressAdditional": "Eingang B",
    "postcode": "10001",
    "city": "Berlin",
    "countryCode": "DE",
    "vatIds": [
      {
        "id": "DE123456789",
        "countryCode": "DE"
      }
    ],
    "taxIds": [
      {
        "id": "123-456-789",
        "type": "TIN"
      }
    ],
    "blockedForPosting": false,
    "blockedForPayment": false,
    "blockedForOrdering": false,
    "blockedForDelivery": false,
    "globalLocationNumber": "4000001000002",
    "duns": "123456789",
    "customerSubsidiaries": [
      {
        "defaultAccountAssignment": {
          "glAccountCode": "0000100GL1",
          "costCenterCode": "0000100CC1",
          "externalApproverId": "MMUSTERMANN",
          "externalProjectId": "PROJ1234",
          "externalOrderId": "ORDER1234"
        },
        "externalCompanyId": "DE01",
        "paymentTerms": {
          "paymentTermKey": "T10",
          "descriptions": [
            {
              "text": "Please pay us",
              "language": "en"
            }
          ]
        },
        "blockedForPosting": false,
        "blockedForPayment": false,
        "enabledForAutoPosting": true,
        "withholdingTaxInfo": [
          {
            "key": "WHT-432",
            "descriptions": [
              {
                "text": "Some very deep description of the type of withholding tax",
                "language": "en"
              }
            ]
          }
        ]
      }
    ],
    "customerBankAccounts": [
      {
        "externalId": "12341234",
        "countryCode": "DE",
        "bankAccountNumber": "78090",
        "bankAccountHolder": "Maximilian Mustermann",
        "iban": "DE91100000000123456789",
        "bic": "CHASUS33XXX",
        "bankName": "Deutsche Bank",
        "bankStreet": "Hauptstr. 1",
        "bankPostcode": "10001",
        "bankCity": "Berlin",
        "isActive": true,
        "type": "SAVINGS",
        "bankKey": "60-16-13"
      }
    ],
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "salesOrganizationInfo": [
      {
        "externalSalesOrganizationId": "1000",
        "distributionChannel": "2000",
        "division": "3000",
        "salesGroup": "4000",
        "salesOffice": "5000",
        "blockedForOrdering": true,
        "blockedForDelivery": false,
        "shippingAddresses": [
          "ADDR001",
          "ADDR002"
        ],
        "billingAddresses": [
          "ADDR003"
        ],
        "salesOrganizationCode": "SO001",
        "salesUnit": {
          "unitOfMeasure": "PK",
          "conversionFactorToBaseUnit": 1000,
          "description": "Package of 10 units"
        },
        "paymentTerms": {
          "paymentTermKey": "T10",
          "descriptions": [
            {
              "text": "Please pay us",
              "language": "en"
            }
          ]
        },
        "customerGroup1": "01",
        "customerGroup2": "02",
        "customerGroup3": "03",
        "customerGroup4": "04",
        "customerGroup5": "05"
      }
    ]
  }'

Responses

Successfully inserted

Bodyapplication/json

idstringrequired

Example:"3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"

Response

{
  "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Insert customer

Request

Responses

Was this helpful?