Skip to content

Hypatos REST API (2.68.0)

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
Languages
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

Cases

Endpoints for case management

Operations

Enrichment

Endpoints for data enrichment

Operations

Insert customer product

Request

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

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

Example: "DE01-1000004711-CUST-ABC-4711"
externalClientIdstring

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

Example: "EXTERNAL_CLIENT_ID"
externalCustomerIdstring

External unique id of the customer in the source system

Example: "1000004711"
externalProductIdstring

Unique id of the product in the source system that links the customer product to the internal product master

Example: "DE01-MAT-000123"
customerProductNumberstring

Product number used by the customer to identify the product

Example: "CUST-ABC-4711"
unspscstring

United Nations Standard Products and Services Code of the product

Example: "43211508"
eanstring

European Article Number (EAN-13)

Example: "4006381333931"
upcstring

Universal Product Code (UPC-A)

Example: "036000291452"
gtinstring

Global Trade Item Number (GTIN) according to GS1 standards. A globally unique identifier for trade items and products.

Example: "4006381333931"
customsTariffNumberstring

Customs tariff number (HS/TARIC code) used for cross-border trade and customs

Example: "8471300000"
customerProductDescriptionstring

Product description used by the customer

Example: "Laptop 14 inch business model"
salesOrganizationCodestring

Sales organization for which the customer product is valid

Example: "DE01"
distributionChannelstring

Distribution channel for sales

Example: "10"
divisionstring

Division under which the sales organization operates

Example: "00"
baseUnitOfMeasurestring

The base unit in which the product is managed in the system

Example: "kg"
statusstring

Current status of the customer product

Example: "ACTIVE"
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/customer-products \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "DE01-1000004711-CUST-ABC-4711",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "externalCustomerId": "1000004711",
    "externalProductId": "DE01-MAT-000123",
    "customerProductNumber": "CUST-ABC-4711",
    "unspsc": "43211508",
    "ean": "4006381333931",
    "upc": "036000291452",
    "gtin": "4006381333931",
    "customsTariffNumber": "8471300000",
    "customerProductDescription": "Laptop 14 inch business model",
    "salesOrganizationCode": "DE01",
    "distributionChannel": "10",
    "division": "00",
    "baseUnitOfMeasure": "kg",
    "status": "ACTIVE",
    "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 customer product

Request

Security
OAuth2(Required scopes:
enrichment.write
)
Path
externalIdstringrequired

Previously sent externalId

Bodyapplication/merge-patch+jsonrequired
externalIdstring^\S+$required

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

Example: "DE01-1000004711-CUST-ABC-4711"
externalClientIdstring

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

Example: "EXTERNAL_CLIENT_ID"
externalCustomerIdstring

External unique id of the customer in the source system

Example: "1000004711"
externalProductIdstring

Unique id of the product in the source system that links the customer product to the internal product master

Example: "DE01-MAT-000123"
customerProductNumberstring

Product number used by the customer to identify the product

Example: "CUST-ABC-4711"
unspscstring

United Nations Standard Products and Services Code of the product

Example: "43211508"
eanstring

European Article Number (EAN-13)

Example: "4006381333931"
upcstring

Universal Product Code (UPC-A)

Example: "036000291452"
gtinstring

Global Trade Item Number (GTIN) according to GS1 standards. A globally unique identifier for trade items and products.

Example: "4006381333931"
customsTariffNumberstring

Customs tariff number (HS/TARIC code) used for cross-border trade and customs

Example: "8471300000"
customerProductDescriptionstring

Product description used by the customer

Example: "Laptop 14 inch business model"
salesOrganizationCodestring

Sales organization for which the customer product is valid

Example: "DE01"
distributionChannelstring

Distribution channel for sales

Example: "10"
divisionstring

Division under which the sales organization operates

Example: "00"
baseUnitOfMeasurestring

The base unit in which the product is managed in the system

Example: "kg"
statusstring

Current status of the customer product

Example: "ACTIVE"
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/customer-products/{externalId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "externalId": "DE01-1000004711-CUST-ABC-4711",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "externalCustomerId": "1000004711",
    "externalProductId": "DE01-MAT-000123",
    "customerProductNumber": "CUST-ABC-4711",
    "unspsc": "43211508",
    "ean": "4006381333931",
    "upc": "036000291452",
    "gtin": "4006381333931",
    "customsTariffNumber": "8471300000",
    "customerProductDescription": "Laptop 14 inch business model",
    "salesOrganizationCode": "DE01",
    "distributionChannel": "10",
    "division": "00",
    "baseUnitOfMeasure": "kg",
    "status": "ACTIVE",
    "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 customer product that is globally unique across the provided customer product data

Example: "DE01-1000004711-CUST-ABC-4711"
externalClientIdstring

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

Example: "EXTERNAL_CLIENT_ID"
externalCustomerIdstring

External unique id of the customer in the source system

Example: "1000004711"
externalProductIdstring

Unique id of the product in the source system that links the customer product to the internal product master

Example: "DE01-MAT-000123"
customerProductNumberstring

Product number used by the customer to identify the product

Example: "CUST-ABC-4711"
unspscstring

United Nations Standard Products and Services Code of the product

Example: "43211508"
eanstring

European Article Number (EAN-13)

Example: "4006381333931"
upcstring

Universal Product Code (UPC-A)

Example: "036000291452"
gtinstring

Global Trade Item Number (GTIN) according to GS1 standards. A globally unique identifier for trade items and products.

Example: "4006381333931"
customsTariffNumberstring

Customs tariff number (HS/TARIC code) used for cross-border trade and customs

Example: "8471300000"
customerProductDescriptionstring

Product description used by the customer

Example: "Laptop 14 inch business model"
salesOrganizationCodestring

Sales organization for which the customer product is valid

Example: "DE01"
distributionChannelstring

Distribution channel for sales

Example: "10"
divisionstring

Division under which the sales organization operates

Example: "00"
baseUnitOfMeasurestring

The base unit in which the product is managed in the system

Example: "kg"
statusstring

Current status of the customer product

Example: "ACTIVE"
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": "DE01-1000004711-CUST-ABC-4711",
  "externalClientId": "EXTERNAL_CLIENT_ID",
  "externalCustomerId": "1000004711",
  "externalProductId": "DE01-MAT-000123",
  "customerProductNumber": "CUST-ABC-4711",
  "unspsc": "43211508",
  "ean": "4006381333931",
  "upc": "036000291452",
  "gtin": "4006381333931",
  "customsTariffNumber": "8471300000",
  "customerProductDescription": "Laptop 14 inch business model",
  "salesOrganizationCode": "DE01",
  "distributionChannel": "10",
  "division": "00",
  "baseUnitOfMeasure": "kg",
  "status": "ACTIVE",
  "customFields": {
    "property1": "string",
    "property2": "string"
  },
  "customMetadata": {
    "someTopLevelProperty": "value1",
    "someNestedProperty": { … },
    "someArrayProperty": [ … ]
  }
}

Delete customer product

Request

Security
OAuth2(Required scopes:
enrichment.delete
)
Path
externalIdstringrequired

Previously sent externalId

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

Responses

Successfully deleted

Response
No content

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

Agent Management

Endpoints for managing agents and agent workflows

Operations

Emails

Operations

Document Routing

Operations

Enrichment workflows

Operations

Users

Operations