Skip to content

Hypatos REST API (2.51.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

Enrichment

Endpoints for data enrichment

Operations

Partially update invoice

Request

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

Previously sent externalId

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

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

Example: "SUPPLIER_INVOICE-3-1"
externalClientIdstring

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

Example: "EXTERNAL_CLIENT_ID"
documentIdstring^[0-9a-fA-F]{24}$

Document id that was assigned during upload to Hypatos

Example: "63cac12c37bb02accb396cae"
documentsArray of objects(document)
supplierInvoiceNumberstring

Invoice number provided by the issuing supplier

Example: "10000001"
invoiceNumberstring

Number of the invoice in the source system (not unique across clients)

Example: "12345"
externalCompanyIdstring

External unique id of the company in the source system

Example: "DE01"
externalSupplierIdstring

External unique id of the supplier in the source system

Example: "0000100000"
externalBankAccountIdstring

External unique id of the bank account that the invoice payment was transferred to

Example: "12341234"
fiscalYearLabelstring

Label used in the source system for the fiscal year that the invoice was posted in

Example: "2023"
issuedDatestring(date)

Date when the invoice was issued by the supplier (printed on invoice document)

Example: "2000-12-31"
receivedDatestring(date)

Date when the invoice was recieved by the company

Example: "2000-12-31"
postingDatestring(date)

Date when the invoice was posted in the source system

Example: "2000-12-31"
isCanceledboolean

Indicator if the invoice is canceled

Example: false
isCreditNoteboolean

Indicator if the document is a credit note

externalCustomerIdstring

External unique id of the customer in the source system

relatedInvoicestring

externalInvoiceId of related invoice

Example: "SUPPLIER_INVOICE-3-2"
currencystring or null(CurrencyCode)

Three letter currency code as defined in ISO 4217

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
Example: "EUR"
totalNetAmountnumber

Total net amount of invoice (sum of line item net amounts)

Example: 81
totalFreightChargesnumber

Sum of all freight charges

Example: 9
totalOtherChargesnumber

Sum of all charges other than freight charges

Example: 10
totalTaxAmountnumber

Total tax amount of invoice (sum of all taxes)

Example: 19
totalGrossAmountnumber

Total gross amount of invoice (total net amount + total freight charges + total other charges + total tax amount)

Example: 119
paymentTermsobject(paymentTerms)
externalApproverIdstring

External unique id of the first approver of an invoice in the source system

Example: "UserID#1234"
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"]}
headerTextstring

Header Text describing the invoice

Example: "doc header text"
typestring

type of the invoice as defined in th source system

Example: "FI"
invoiceLinesArray of objects(invoiceLine)non-emptyrequired
invoiceLines[].​externalIdstring^\S+$

External id of the invoice line that is globally unique across the provided invoice line data

Example: "00000001"
invoiceLines[].​externalCompanyIdstring

Company that the invoice line is assigned to

Example: "DE01"
invoiceLines[].​accountAssignmentsArray of objects(accountAssignment)
invoiceLines[].​typestring

type of the invoice line as defined in the source system

Example: "Service"
invoiceLines[].​quantitynumber

Quantity of the invoice line (sum of all quantity splits in case of several accountAssignments)

Example: 2
invoiceLines[].​netAmountnumber

Net amount of the invoice line

Example: 1.23
invoiceLines[].​totalTaxAmountnumber

Total tax amount of the invoice line

Example: 1.23
invoiceLines[].​grossAmountnumber

Gross amount of the invoice line

Example: 100.01
invoiceLines[].​unitOfMeasurestring

Unit of measure of the invoice line

Example: "kg"
invoiceLines[].​unitPricenumber

Price for one unit of the invoice line

Example: 19.0123
invoiceLines[].​taxCodeobject(taxCode)
invoiceLines[].​taxJurisdictionCodestring

tax jurisdiction code assigned to the invoice

Example: "PA0000000"
invoiceLines[].​itemTextstring

Text describing the invoice line item

Example: "Virtual Event ABC"
invoiceLines[].​externalPurchaseOrderIdstring

Purchase order related to the invoice line item

Example: "4500016221"
invoiceLines[].​purchaseOrderLineNumberstring

Reference to the purchase order line item assigned to the invoice line item

Example: "00010"
invoiceLines[].​centralBankIndicatorstring

State Central Bank Indicator for reporting foreign payment transactions according to the German Foreign Trade and Payments Ordinance (Außenwirtschaftsverordnung - AWV)

Example: "123"
invoiceLines[].​customFieldsobject(customFields)

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

invoiceLines[].​customMetadataobject(JsonObject)

Any nested structure with metadata that source system needs to send

Example: {"someTopLevelProperty":"value1","someNestedProperty":{"nestedProperty":"value2"},"someArrayProperty":["value3","value4"]}
withholdingTaxArray of objects(withholdingTax)
documentTypestring

document type as defined in the source system

Example: "supplier invoice"
curl -i -X PATCH \
  'https://api.cloud.hypatos.ai/v2/enrichment/invoices/{externalId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "externalId": "SUPPLIER_INVOICE-3-1",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "documentId": "63cac12c37bb02accb396cae",
    "documents": [
      {
        "id": "63cac12c37bb02accb396cae",
        "type": "invoice"
      }
    ],
    "supplierInvoiceNumber": "10000001",
    "invoiceNumber": "12345",
    "externalCompanyId": "DE01",
    "externalSupplierId": "0000100000",
    "externalBankAccountId": "12341234",
    "fiscalYearLabel": "2023",
    "issuedDate": "2000-12-31",
    "receivedDate": "2000-12-31",
    "postingDate": "2000-12-31",
    "isCanceled": false,
    "isCreditNote": true,
    "externalCustomerId": "string",
    "relatedInvoice": "SUPPLIER_INVOICE-3-2",
    "currency": "EUR",
    "totalNetAmount": 81,
    "totalFreightCharges": 9,
    "totalOtherCharges": 10,
    "totalTaxAmount": 19,
    "totalGrossAmount": 119,
    "paymentTerms": {
      "paymentTermKey": "T10",
      "descriptions": [
        {
          "text": "Please pay us",
          "language": "en"
        }
      ]
    },
    "externalApproverId": "UserID#1234",
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "headerText": "doc header text",
    "type": "FI",
    "invoiceLines": [
      {
        "externalId": "00000001",
        "externalCompanyId": "DE01",
        "accountAssignments": [
          {
            "externalGlAccountId": "0000100GL1",
            "externalCostCenterId": "0000100CO1",
            "glAccountCode": "GL1",
            "costCenterCode": "CO1",
            "quantity": 2,
            "externalProjectId": "EPI1",
            "externalOrderId": "EOI1",
            "costElementCode": "CE1",
            "externalProfitCenterId": "EPCI1",
            "profitCenterCode": "PCC1"
          }
        ],
        "type": "Service",
        "quantity": 2,
        "netAmount": 1.23,
        "totalTaxAmount": 1.23,
        "grossAmount": 100.01,
        "unitOfMeasure": "kg",
        "unitPrice": 19.0123,
        "taxCode": {
          "code": "DEU_Standard",
          "description": "DEU - Standard (19%)"
        },
        "taxJurisdictionCode": "PA0000000",
        "itemText": "Virtual Event ABC",
        "externalPurchaseOrderId": "4500016221",
        "purchaseOrderLineNumber": "00010",
        "centralBankIndicator": "123",
        "customFields": {
          "property1": "string",
          "property2": "string"
        },
        "customMetadata": {
          "someTopLevelProperty": "value1",
          "someNestedProperty": {
            "nestedProperty": "value2"
          },
          "someArrayProperty": [
            "value3",
            "value4"
          ]
        }
      }
    ],
    "withholdingTax": [
      {
        "key": "WHT-432",
        "baseAmount": 632.78,
        "amount": 21.39,
        "currency": "EUR"
      }
    ],
    "documentType": "supplier invoice"
  }'

Responses

Successfully updated

Bodyapplication/json
externalIdstring^\S+$required

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

Example: "SUPPLIER_INVOICE-3-1"
externalClientIdstring

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

Example: "EXTERNAL_CLIENT_ID"
documentIdstring^[0-9a-fA-F]{24}$

Document id that was assigned during upload to Hypatos

Example: "63cac12c37bb02accb396cae"
documentsArray of objects(document)
supplierInvoiceNumberstring

Invoice number provided by the issuing supplier

Example: "10000001"
invoiceNumberstring

Number of the invoice in the source system (not unique across clients)

Example: "12345"
externalCompanyIdstring

External unique id of the company in the source system

Example: "DE01"
externalSupplierIdstring

External unique id of the supplier in the source system

Example: "0000100000"
externalBankAccountIdstring

External unique id of the bank account that the invoice payment was transferred to

Example: "12341234"
fiscalYearLabelstring

Label used in the source system for the fiscal year that the invoice was posted in

Example: "2023"
issuedDatestring(date)

Date when the invoice was issued by the supplier (printed on invoice document)

Example: "2000-12-31"
receivedDatestring(date)

Date when the invoice was recieved by the company

Example: "2000-12-31"
postingDatestring(date)

Date when the invoice was posted in the source system

Example: "2000-12-31"
isCanceledboolean

Indicator if the invoice is canceled

Example: false
isCreditNoteboolean

Indicator if the document is a credit note

externalCustomerIdstring

External unique id of the customer in the source system

relatedInvoicestring

externalInvoiceId of related invoice

Example: "SUPPLIER_INVOICE-3-2"
currencystring or null(CurrencyCode)

Three letter currency code as defined in ISO 4217

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
Example: "EUR"
totalNetAmountnumber

Total net amount of invoice (sum of line item net amounts)

Example: 81
totalFreightChargesnumber

Sum of all freight charges

Example: 9
totalOtherChargesnumber

Sum of all charges other than freight charges

Example: 10
totalTaxAmountnumber

Total tax amount of invoice (sum of all taxes)

Example: 19
totalGrossAmountnumber

Total gross amount of invoice (total net amount + total freight charges + total other charges + total tax amount)

Example: 119
paymentTermsobject(paymentTerms)
externalApproverIdstring

External unique id of the first approver of an invoice in the source system

Example: "UserID#1234"
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"]}
headerTextstring

Header Text describing the invoice

Example: "doc header text"
typestring

type of the invoice as defined in th source system

Example: "FI"
invoiceLinesArray of objects(invoiceLine)non-emptyrequired
invoiceLines[].​externalIdstring^\S+$

External id of the invoice line that is globally unique across the provided invoice line data

Example: "00000001"
invoiceLines[].​externalCompanyIdstring

Company that the invoice line is assigned to

Example: "DE01"
invoiceLines[].​accountAssignmentsArray of objects(accountAssignment)
invoiceLines[].​typestring

type of the invoice line as defined in the source system

Example: "Service"
invoiceLines[].​quantitynumber

Quantity of the invoice line (sum of all quantity splits in case of several accountAssignments)

Example: 2
invoiceLines[].​netAmountnumber

Net amount of the invoice line

Example: 1.23
invoiceLines[].​totalTaxAmountnumber

Total tax amount of the invoice line

Example: 1.23
invoiceLines[].​grossAmountnumber

Gross amount of the invoice line

Example: 100.01
invoiceLines[].​unitOfMeasurestring

Unit of measure of the invoice line

Example: "kg"
invoiceLines[].​unitPricenumber

Price for one unit of the invoice line

Example: 19.0123
invoiceLines[].​taxCodeobject(taxCode)
invoiceLines[].​taxJurisdictionCodestring

tax jurisdiction code assigned to the invoice

Example: "PA0000000"
invoiceLines[].​itemTextstring

Text describing the invoice line item

Example: "Virtual Event ABC"
invoiceLines[].​externalPurchaseOrderIdstring

Purchase order related to the invoice line item

Example: "4500016221"
invoiceLines[].​purchaseOrderLineNumberstring

Reference to the purchase order line item assigned to the invoice line item

Example: "00010"
invoiceLines[].​centralBankIndicatorstring

State Central Bank Indicator for reporting foreign payment transactions according to the German Foreign Trade and Payments Ordinance (Außenwirtschaftsverordnung - AWV)

Example: "123"
invoiceLines[].​customFieldsobject(customFields)

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

invoiceLines[].​customMetadataobject(JsonObject)

Any nested structure with metadata that source system needs to send

Example: {"someTopLevelProperty":"value1","someNestedProperty":{"nestedProperty":"value2"},"someArrayProperty":["value3","value4"]}
withholdingTaxArray of objects(withholdingTax)
documentTypestring

document type as defined in the source system

Example: "supplier invoice"
Response
application/json
{
  "externalId": "SUPPLIER_INVOICE-3-1",
  "externalClientId": "EXTERNAL_CLIENT_ID",
  "documentId": "63cac12c37bb02accb396cae",
  "documents": [
    { … }
  ],
  "supplierInvoiceNumber": "10000001",
  "invoiceNumber": "12345",
  "externalCompanyId": "DE01",
  "externalSupplierId": "0000100000",
  "externalBankAccountId": "12341234",
  "fiscalYearLabel": "2023",
  "issuedDate": "2000-12-31",
  "receivedDate": "2000-12-31",
  "postingDate": "2000-12-31",
  "isCanceled": false,
  "isCreditNote": true,
  "externalCustomerId": "string",
  "relatedInvoice": "SUPPLIER_INVOICE-3-2",
  "currency": "EUR",
  "totalNetAmount": 81,
  "totalFreightCharges": 9,
  "totalOtherCharges": 10,
  "totalTaxAmount": 19,
  "totalGrossAmount": 119,
  "paymentTerms": {
    "paymentTermKey": "T10",
    "descriptions": [ … ]
  },
  "externalApproverId": "UserID#1234",
  "customFields": {
    "property1": "string",
    "property2": "string"
  },
  "customMetadata": {
    "someTopLevelProperty": "value1",
    "someNestedProperty": { … },
    "someArrayProperty": [ … ]
  },
  "headerText": "doc header text",
  "type": "FI",
  "invoiceLines": [
    { … }
  ],
  "withholdingTax": [
    { … }
  ],
  "documentType": "supplier invoice"
}

Delete invoice

Request

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

Previously sent externalId

Query
lineNumberstring

Line number of one of the line numbers inside the Invoice. Optional, omitting means the whole Invoice is deleted.

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

Responses

Successfully deleted

Response
No 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"}]
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"
      }
    ],
    "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"
}

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