Hypatos REST API (2.51.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Introduction

The Hypatos API is organized around REST. The majority of the endpoints provide CRUD functionality for resources. The API is also exposing Intent Resources which mimic user intents or actions.

The Hypatos API uses OAuth 2.0 Client Credential Grant to authenticate requests. Before making any requests to any endpoint a client must authenticate with the authorization server and requests an access token from the token endpoint.

  POST /auth/token HTTP/1.1
  Host: api.cloud.hypatos.ai
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

  grant_type=client_credentials

Authorization header contains client_id:client_secret encoded as explained in RFC Client Password section.

If the authorization server authenticated the client successfully, an access token is issued. Here is an example successful response:

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache

  {
    "access_token": "mF_9.B5f-4.1JqM",
    "expires_in": 86400,
    "scope": "enrichment.write files.read",
    "token_type": "Bearer",
  }

This token can be used to authenticate the requests to API endpoints by sending a Bearer token in the Authorization HTTP header. The following example demonstrates how to use the access token to retrieve a list of documents.

  GET /v2/documents HTTP/1.1
  Host: api.cloud.hypatos.ai
  Authorization: Bearer mF_9.B5f-4.1JqM

Versioning

Changes to this API are released regularly. We use Semantic Versioning 2.0.0 scheme for versioning so that the clients can identify any backward-incompatible changes easily. Briefly summarized one can say, if the MAJOR version of the new API version didn't change you can expect the new version to be backward-compatible.

Rate limits

In order to maximise the stability of our API, we institue rate limits for all of API endpoints. Clients who send too many requests over a given period of time will see error responses that show up as status code 429 Too Many Requests.

When you see error responses with status code 429, it means you exhausted your current quota and need to withhold from sending further requests until the quota is reset. We encourage you not to wait until you get a 429 error but to monitor your quota in each request. In each response you receive from the API, you will find HTTP headers providing the details about your current quota. Here is the list of the HTTP headers:

x-ratelimit-limit: Indicates the quota associated to the client in the current time-window followed by the description of the quota policy.
x-ratelimit-remaining: Indicates the number of remaining requests in the current time-window
x-ratelimit-reset: Indicates the number of seconds until quota reset of the current time-window

Please note that IETF is currently in the process of publishing a standard for these headers. Please explore the draft for more details.

A basic technique to gracefully handle rate limits is watch for your quota permanently and increase the time between your request as the quota is decreasing. To recover from a 429 error you need a retry mechanism following an exponential backoff schedule.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License

Apache 2.0

Servers

API EU

https://api.cloud.hypatos.ai/v2

API US

https://api.cloud.hypatos.com/v2

Mock server

https://hypatos.redocly.app/_mock/openapi

Authorization

Endpoints for handling the OAuth 2.0 Client Credentials Grant flow.

Operations

Files

Endpoints for management of files

Operations

Documents

Endpoints for document management

Operations

Enrichment

Endpoints for data enrichment

Operations

Delete product

Request

Security

OAuth2(Required scopes:

enrichment.delete

)

Path

externalIdstringrequired

Previously sent externalId

curl -i -X DELETE \
  'https://api.cloud.hypatos.ai/v2/enrichment/products/{externalId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successfully deleted

Response

No content

Insert address

Request

Security

OAuth2(Required scopes:

enrichment.write

)

Bodyapplication/jsonrequired

externalIdstring^\S+$required

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

Example: "ADDR12345"

businessPartnerNumberstring

Number of the business partner related to this address (e.g. customer number)

Example: "BP12345"

parentBusinessPartnerNumberstring

Number of the parent business partner of this address (e.g. customer number)

Example: "PBP12345"

typestring

Type of the address

Enum"shippingAddress""billingAddress"

Example: "shippingAddress"

addressOrdernumber

Order of the address (in case there’s several addresses of the same type)

Example: 1

externalClientIdstring

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

Example: "CLIENT123"

globalLocationNumberstring

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

Example: "1234567890123"

companyNamestring^[\S ]*\S[\S ]*$

Name of the company associated with the address

Example: "Acme Corporation"

nameAlternative1string

Alternative name of the company (e.g. trade name or local language)

Example: "Acme Corp."

nameAlternative2string

Alternative name of the company

Example: "Acme Inc."

nameAlternative3string

Alternative name of the company

Example: "Acme Ltd."

nameAlternative4string

Alternative name of the company

Example: "Acme GmbH"

streetstring

Street and street number where the address is located

Example: "123 Main St"

addressAdditionalstring

Additional address data (e.g. building, entrance, apartment, or suite)

Example: "Building A, Suite 101"

postcodestring

Postcode where the address is located

Example: "12345"

citystring

City where the address is located

Example: "Berlin"

postOfficeBoxstring

Post office box number, if used instead of street address

Example: "PO Box 123"

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"

regionstring

Region, state, or province of the address (e.g. "CA" for California or "BE" for Berlin)

Example: "BE"

transportationZonestring

Code identifying the transportation or logistics zone relevant for shipping or route planning

Example: "TZ123"

phoneNumberstring

Phone number of the location or contact point

Example: "+491234567890"

faxNumberstring

Fax number of the location or contact point

Example: "+491234567891"

emailstring

Email address associated with the location or contact point

Example: "contact@acme.com"

validFromstring(date)

Start date from which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-01-01"

validTostring(date)

End date until which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-12-31"

isDefaultboolean

Indicator whether this address is the default for the given type (e.g., default ship-to address)

Example: true

latitudenumber

Geographical latitude coordinate of the address (in decimal degrees)

Example: 52.520008

longitudenumber

Geographical longitude coordinate of the address (in decimal degrees)

Example: 13.404954

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/addresses \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "ADDR12345",
    "businessPartnerNumber": "BP12345",
    "parentBusinessPartnerNumber": "PBP12345",
    "type": "shippingAddress",
    "addressOrder": 1,
    "externalClientId": "CLIENT123",
    "globalLocationNumber": "1234567890123",
    "companyName": "Acme Corporation",
    "nameAlternative1": "Acme Corp.",
    "nameAlternative2": "Acme Inc.",
    "nameAlternative3": "Acme Ltd.",
    "nameAlternative4": "Acme GmbH",
    "street": "123 Main St",
    "addressAdditional": "Building A, Suite 101",
    "postcode": "12345",
    "city": "Berlin",
    "postOfficeBox": "PO Box 123",
    "countryCode": "DE",
    "region": "BE",
    "transportationZone": "TZ123",
    "phoneNumber": "+491234567890",
    "faxNumber": "+491234567891",
    "email": "contact@acme.com",
    "validFrom": "2023-01-01",
    "validTo": "2023-12-31",
    "isDefault": true,
    "latitude": 52.520008,
    "longitude": 13.404954,
    "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

application/json

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

Partially update address

Request

Security

OAuth2(Required scopes:

enrichment.write

)

Path

externalIdstringrequired

Previously sent externalId

Bodyapplication/merge-patch+jsonrequired

externalIdstring^\S+$required

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

Example: "ADDR12345"

businessPartnerNumberstring

Number of the business partner related to this address (e.g. customer number)

Example: "BP12345"

parentBusinessPartnerNumberstring

Number of the parent business partner of this address (e.g. customer number)

Example: "PBP12345"

typestring

Type of the address

Enum"shippingAddress""billingAddress"

Example: "shippingAddress"

addressOrdernumber

Order of the address (in case there’s several addresses of the same type)

Example: 1

externalClientIdstring

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

Example: "CLIENT123"

globalLocationNumberstring

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

Example: "1234567890123"

companyNamestring^[\S ]*\S[\S ]*$

Name of the company associated with the address

Example: "Acme Corporation"

nameAlternative1string

Alternative name of the company (e.g. trade name or local language)

Example: "Acme Corp."

nameAlternative2string

Alternative name of the company

Example: "Acme Inc."

nameAlternative3string

Alternative name of the company

Example: "Acme Ltd."

nameAlternative4string

Alternative name of the company

Example: "Acme GmbH"

streetstring

Street and street number where the address is located

Example: "123 Main St"

addressAdditionalstring

Additional address data (e.g. building, entrance, apartment, or suite)

Example: "Building A, Suite 101"

postcodestring

Postcode where the address is located

Example: "12345"

citystring

City where the address is located

Example: "Berlin"

postOfficeBoxstring

Post office box number, if used instead of street address

Example: "PO Box 123"

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"

regionstring

Region, state, or province of the address (e.g. "CA" for California or "BE" for Berlin)

Example: "BE"

transportationZonestring

Code identifying the transportation or logistics zone relevant for shipping or route planning

Example: "TZ123"

phoneNumberstring

Phone number of the location or contact point

Example: "+491234567890"

faxNumberstring

Fax number of the location or contact point

Example: "+491234567891"

emailstring

Email address associated with the location or contact point

Example: "contact@acme.com"

validFromstring(date)

Start date from which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-01-01"

validTostring(date)

End date until which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-12-31"

isDefaultboolean

Indicator whether this address is the default for the given type (e.g., default ship-to address)

Example: true

latitudenumber

Geographical latitude coordinate of the address (in decimal degrees)

Example: 52.520008

longitudenumber

Geographical longitude coordinate of the address (in decimal degrees)

Example: 13.404954

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 PATCH \
  'https://api.cloud.hypatos.ai/v2/enrichment/addresses/{externalId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "externalId": "ADDR12345",
    "businessPartnerNumber": "BP12345",
    "parentBusinessPartnerNumber": "PBP12345",
    "type": "shippingAddress",
    "addressOrder": 1,
    "externalClientId": "CLIENT123",
    "globalLocationNumber": "1234567890123",
    "companyName": "Acme Corporation",
    "nameAlternative1": "Acme Corp.",
    "nameAlternative2": "Acme Inc.",
    "nameAlternative3": "Acme Ltd.",
    "nameAlternative4": "Acme GmbH",
    "street": "123 Main St",
    "addressAdditional": "Building A, Suite 101",
    "postcode": "12345",
    "city": "Berlin",
    "postOfficeBox": "PO Box 123",
    "countryCode": "DE",
    "region": "BE",
    "transportationZone": "TZ123",
    "phoneNumber": "+491234567890",
    "faxNumber": "+491234567891",
    "email": "contact@acme.com",
    "validFrom": "2023-01-01",
    "validTo": "2023-12-31",
    "isDefault": true,
    "latitude": 52.520008,
    "longitude": 13.404954,
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    }
  }'

Responses

Successfully updated

Bodyapplication/json

externalIdstring^\S+$required

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

Example: "ADDR12345"

businessPartnerNumberstring

Number of the business partner related to this address (e.g. customer number)

Example: "BP12345"

parentBusinessPartnerNumberstring

Number of the parent business partner of this address (e.g. customer number)

Example: "PBP12345"

typestring

Type of the address

Enum"shippingAddress""billingAddress"

Example: "shippingAddress"

addressOrdernumber

Order of the address (in case there’s several addresses of the same type)

Example: 1

externalClientIdstring

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

Example: "CLIENT123"

globalLocationNumberstring

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

Example: "1234567890123"

companyNamestring^[\S ]*\S[\S ]*$

Name of the company associated with the address

Example: "Acme Corporation"

nameAlternative1string

Alternative name of the company (e.g. trade name or local language)

Example: "Acme Corp."

nameAlternative2string

Alternative name of the company

Example: "Acme Inc."

nameAlternative3string

Alternative name of the company

Example: "Acme Ltd."

nameAlternative4string

Alternative name of the company

Example: "Acme GmbH"

streetstring

Street and street number where the address is located

Example: "123 Main St"

addressAdditionalstring

Additional address data (e.g. building, entrance, apartment, or suite)

Example: "Building A, Suite 101"

postcodestring

Postcode where the address is located

Example: "12345"

citystring

City where the address is located

Example: "Berlin"

postOfficeBoxstring

Post office box number, if used instead of street address

Example: "PO Box 123"

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"

regionstring

Region, state, or province of the address (e.g. "CA" for California or "BE" for Berlin)

Example: "BE"

transportationZonestring

Code identifying the transportation or logistics zone relevant for shipping or route planning

Example: "TZ123"

phoneNumberstring

Phone number of the location or contact point

Example: "+491234567890"

faxNumberstring

Fax number of the location or contact point

Example: "+491234567891"

emailstring

Email address associated with the location or contact point

Example: "contact@acme.com"

validFromstring(date)

Start date from which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-01-01"

validTostring(date)

End date until which the address is considered valid (format: YYYY-MM-DD)

Example: "2023-12-31"

isDefaultboolean

Indicator whether this address is the default for the given type (e.g., default ship-to address)

Example: true

latitudenumber

Geographical latitude coordinate of the address (in decimal degrees)

Example: 52.520008

longitudenumber

Geographical longitude coordinate of the address (in decimal degrees)

Example: 13.404954

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"]}

Response

application/json

{
  "externalId": "ADDR12345",
  "businessPartnerNumber": "BP12345",
  "parentBusinessPartnerNumber": "PBP12345",
  "type": "shippingAddress",
  "addressOrder": 1,
  "externalClientId": "CLIENT123",
  "globalLocationNumber": "1234567890123",
  "companyName": "Acme Corporation",
  "nameAlternative1": "Acme Corp.",
  "nameAlternative2": "Acme Inc.",
  "nameAlternative3": "Acme Ltd.",
  "nameAlternative4": "Acme GmbH",
  "street": "123 Main St",
  "addressAdditional": "Building A, Suite 101",
  "postcode": "12345",
  "city": "Berlin",
  "postOfficeBox": "PO Box 123",
  "countryCode": "DE",
  "region": "BE",
  "transportationZone": "TZ123",
  "phoneNumber": "+491234567890",
  "faxNumber": "+491234567891",
  "email": "contact@acme.com",
  "validFrom": "2023-01-01",
  "validTo": "2023-12-31",
  "isDefault": true,
  "latitude": 52.520008,
  "longitude": 13.404954,
  "customFields": {
    "property1": "string",
    "property2": "string"
  },
  "customMetadata": {
    "someTopLevelProperty": "value1",
    "someNestedProperty": { … },
    "someArrayProperty": [ … ]
  }
}

Companies

Endpoints for company management

Operations

Projects

Endpoints for project management

Operations

E-Invoices

Endpoints for e-invoices

Operations

Documents XML

Endpoints serving project-scoped documents as XML

Operations

Emails

Operations

Document Routing

Operations

Users

Operations

Hypatos REST API (2.51.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Introduction

Versioning

Rate limits

Authorization

Files

Documents

Enrichment

Delete product

Request

Responses

Was this helpful?

Insert address

Request

Responses

Was this helpful?

Partially update address

Request

Responses

Was this helpful?

Companies

Projects

E-Invoices

Documents XML

Emails

Document Routing

Users

Hypatos REST API (2.51.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Introduction

Versioning

Rate limits

Authorization

Files

Documents

Enrichment

Delete product

Request

Responses

Was this helpful?

Insert address

RequestExpand all

Responses

Was this helpful?

Partially update address

RequestExpand all

Responses

Was this helpful?

Companies

Projects

E-Invoices

Documents XML

Emails

Document Routing

Users

Hypatos REST API (2.51.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Request