Skip to content

Insert company

Request

Security
OAuth2(Required scopes: enrichment.write)
Bodyapplication/jsonrequired
externalIdstring^\S+$required

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

Example:"DE01"
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 company in the source system (not unique across clients)

Example:"CODE1"
namestring^[\S ]*\S[\S ]*$required

Name of the company

Example:"Acmne Corp."
nameAlternative1string

Alternative name of the company

Example:"Acmne Corp."
nameAlternative2string

Alternative name of the company

Example:"Acmne Corp."
nameAlternative3string

Alternative name of the company

Example:"Acmne Corp."
nameAlternative4string

Alternative name of the company

Example:"Acmne Corp."
streetstring

Street and street number where the company is located

Example:"Hauptstr. 1"
addressAdditionalstring

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

Example:"Eingang B"
postcodestring

Postcode where the company is located

Example:"10001"
citystring

City where the company is located

Example:"Berlin"
statestring

State where the company 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 company

Example:
[
  {
    "id": "DE123456789",
    "countryCode": "DE"
  }
]
taxIdsArray of objects(taxId)

List of Tax IDs assigned to the company

Example:
[
  {
    "id": "123-456-789",
    "type": "TIN"
  }
]
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"
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"
  ]
}
curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/companies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "DE01",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "code": "CODE1",
    "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",
    "state": "Berlin",
    "countryCode": "DE",
    "vatIds": [
      {
        "id": "DE123456789",
        "countryCode": "DE"
      }
    ],
    "taxIds": [
      {
        "id": "123-456-789",
        "type": "TIN"
      }
    ],
    "globalLocationNumber": "4000001000002",
    "duns": "123456789",
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    }
  }'

Responses

Successfully inserted

Bodyapplication/json
idstringrequired
Example:"3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
Response
{
  "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}