Hypatos REST API (2.24.0)

Download OpenAPI specification:Download

License: Apache 2.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.

Authorization

Endpoints for handling the OAuth 2.0 Client Credentials Grant flow.

Request an access token

Request an access token using your client credentials

SecurityBasic
Request
Request Body schema: application/x-www-form-urlencoded

Access token request

grant_type
required
string
Value: "client_credentials"
Responses
200

Access token provided

401

Invalid Client Credentials

429

Rate limit exceeded

post/auth/token
Request samples
application/x-www-form-urlencoded
grant_type=client_credentials
Response samples
application/json
{
  • "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  • "expires_in": 3600,
  • "token_type": "Bearer",
  • "scope": "documents.write projects.write"
}

Files

Endpoints for management of files

Upload a file

This endpoint allows a client to upload a binary file. The id returned in the reponse is representing the file in Hypatos systems. It can be used in other endpoints, for example to initiate a processing of the file to create document holding captured data.

SecurityOAuth2
Request
header Parameters
X-Hy-Filename
string <= 256 characters

Optional name of the file to be stored along with the content. If not provided, a filename will be generated

Request Body schema:
required

Payload of the file

string <binary> (BinaryFile)
Responses
201

Document uploaded

400

Content type is not supported

429

Rate limit exceeded

post/files
Request samples
Response samples
application/json
{
  • "id": "6040dc9680b782b365ea77d5"
}

Download a file by id

Download the content of a file with the given identifier.

SecurityOAuth2
Request
path Parameters
id
required
string

File id to download

Responses
200

Binary content of a file

404

No file with given identifier exist

429

Rate limit exceeded

get/files/{id}
Request samples
Response samples
application/json
{
  • "detail": "File with given identifier does not exist",
  • "status": 404,
  • "title": "File not found"
}

Documents

Endpoints for document management

Retrieve a list of documents

Retrieve a list of documents.

SecurityOAuth2
Request
query Parameters
projectId
Array of strings

Project ids to to find items by. If ommitted, items from all existing projects are returned.

offset
integer >= 0

A zero-based offset of the first item in the data collection to return.

limit
integer [ 0 .. 50 ]
Default: 20

Limit the amount of items returned in the response. If the value exceeds the maximum, then the maximum value will be used.

sort
string
Default: "-createdAt"

The field to sort reponse items by.

Enum: "createdAt" "-createdAt" "+createdAt" "updatedAt" "-updatedAt" "+updatedAt"
state
Array of strings (DocumentState)

Used to retrieve documents that are in specific states only. Multiple states can be used for this filtering. By default, documents in all states are returned.

Items Enum: "done" "doneAutomatically" "extracted" "failed" "inCompletion" "junk" "new" "processing" "rejected" "reviewRequired" "split" "transferFailed" "transferred"
fileId
string

File identifier to retrieve documents that were created from that file

Responses
200

List of documents

400

Bad request

429

Rate limit exceeded

get/documents
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "totalCount": 1000
}

Request processing of a file

Request a processing of a file that was previously uploaded. The fileId in the request body is representing the identifier of the file that was returned by the upload endpoint. As a result of this request a document will be created and its identifier will be returned in the response. The projectId in the request body is an identifier of the project to create the document in.

SecurityOAuth2
Request
Request Body schema: application/json
required

Payload for processing the given file

fileId
required
string
projectId
required
string
externalId
string

External id of the file. Can be used if you want to link the file with an identifier in your system.

object (DocumentsUpdateExternalDataRequest)

External data to be associated with the document. The data are provided as a flat JSON object. The properties of that object are case-insensitive. The maximum amount of properties is limited to 20.

Responses
202

Processing accepted

400

Error occured while processing request

404

Error occured while processing request

429

Rate limit exceeded

post/documents/process-file
Request samples
application/json
{
  • "fileId": "5349b4ddd2781d08c09890f4",
  • "projectId": "00000020f51bb4362eee2a4d",
  • "externalId": "doc-0001",
  • "externalData": {
    }
}
Response samples
application/json
{
  • "documentId": "6040dc9680b782b365ea77d5",
  • "fileId": "5349b4ddd2781d08c09890f4",
  • "projectId": "00000020f51bb4362eee2a4d"
}

Retrieve a document by id

Retrieve a document by id

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document to get.

Responses
200

Document retrieved.

404

Error occured while processing request

429

Rate limit exceeded

get/documents/{id}
Request samples
Response samples
application/json
{
  • "id": "6040dc9680b782b365ea77d5",
  • "completedAt": "1990-12-31T15:59:60-08:00",
  • "completedBy": "string",
  • "createdAt": "1990-12-31T15:59:60-08:00",
  • "createdBy": "string",
  • "fileId": "5349b4ddd2781d08c09890f4",
  • "entities": {
    },
  • "externalId": "doc-0001",
  • "externalData": {
    },
  • "projectId": "6040dc9680b782b365ea77d5",
  • "state": "done",
  • "title": "scan-doc-1.jpg",
  • "updatedAt": "1990-12-31T15:59:60-08:00",
  • "updatedBy": "string"
}

Provide information about a transfer of a document to the target system

Update information about the transfer for the given document

SecurityOAuth2
Request
path Parameters
id
required
string

Id of of the document to update.

Request Body schema: application/json
required

Payload about the transfer

successful
required
boolean

Indicates if the transfer was successful or not

message
string

May be used to provide additional details about the transfer. Especially in the erroneous case this field is valueable.

Responses
202

Document transfer infor accepted

400

Error occured while processing request

404

Error occured while processing request

429

Rate limit exceeded

post/documents/{id}/transfer
Request samples
application/json
{
  • "successful": true
}
Response samples
application/json
{
  • "detail": "The document with given identifier does not exist",
  • "status": 404,
  • "title": "Document does not exist"
}

Provide external data for a document with given id

Update the external data for a document with given identifier. The external data are provided as a flat JSON object. The payload of this requests completley overrides the existing external data of a document. To remove the data, justsend empty JSON object {} in the payload.

Please note that the maximum lenght of an key is 50 characters. Any value with a longer key will be omitted. The maximum amount of key-value pairs is limited to 20.

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document to update.

Request Body schema: application/json
required

Payload containing the external data.

key1
string
key2
string
Responses
202

External data provided for the document accepted.

400

Error occured while processing request

404

Error occured while processing request

429

Rate limit exceeded

post/documents/{id}/external-data
Request samples
application/json
{
  • "key1": "value1",
  • "key2": "value2"
}
Response samples
application/json
{
  • "detail": "The document with given identifier does not exist",
  • "status": 404,
  • "title": "Document does not exist"
}

Provide an external identifier for a document with given id

Provide an external identifier for a document with given id

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document to update.

Request Body schema: text/plain
required

Update external id for a given document.

string (DocumentsUpdateExternalIdRequest)

External ID

Responses
202

External ID provided for the document accepted.

400

Error occured while processing request

404

Error occured while processing request

429

Rate limit exceeded

post/documents/{id}/external-id
Request samples
Response samples
application/json
{
  • "detail": "The document with given identifier does not exist",
  • "status": 404,
  • "title": "Document does not exist"
}

Provide a title for a document with given id

Provide a title for a document with given id.

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document to update.

Request Body schema: text/plain
required

Title for a given document.

string (DocumentsUpdateTitleRequest) <= 256 characters

New Title

Responses
202

Document title provided for the document accepted.

400

Error occured while processing request

404

Error occured while processing request

429

Rate limit exceeded

post/documents/{id}/title
Request samples
Response samples
application/json
{
  • "detail": "The document with given identifier does not exist",
  • "status": 404,
  • "title": "Document does not exist"
}

Retrieve a document states

Provides a list of states the given document passed through. If the document is still in processing, the number of states returend must not be considered as final. Subsequent calls to this endpoint might get more states as the document is progressing the processing pipeline.

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document to get states of.

Responses
200

Document states.

404

Error occured while processing request

429

Rate limit exceeded

get/documents/{id}/states
Request samples
Response samples
application/json
[
  • {
    }
]

Enrichment

Endpoints for data enrichment

Insert invoice including invoice lines

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S+$

External unique id of the invoice in the source system

documentId
string^[0-9a-fA-F]{24}$

Document id that was assigned during upload to Hypatos

Array of objects (document) non-empty
supplierInvoiceNumber
string

Invoice number provided by the issuing supplier

invoiceNumber
string

Invoice number defined by the recipient company (not globally unique)

externalCompanyId
string

External unique id of the company in the source system

externalSupplierId
string

External unique id of the supplier in the source system

externalBankAccountId
string

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

fiscalYearLabel
string

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

issuedDate
string <date>

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

receivedDate
string <date>

Date when the invoice was recieved by the company

postingDate
string <date>

Date when the invoice was posted in the source system

isCanceled
boolean

Indicator if the invoice is canceled

relatedInvoice
string

externalInvoiceId of related invoice

currency
string or null (CurrencyCode)

Three letter currency code as defined in ISO 4217

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" null
totalNetAmount
number

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

totalFreightCharges
number

Sum of all freight charges

totalOtherCharges
number

Sum of all charges other than freight charges

totalTaxAmount
number

Total tax amount of invoice (sum of all taxes)

totalGrossAmount
number

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

object (paymentTerms)
externalApproverId
string

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

object (customFields)

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

headerText
string

Header Text describing the invoice

type
string

type of the invoice as defined in th source system

required
Array of objects (invoiceLine) non-empty
Array of objects (withholdingTax)
documentType
string

document type as defined in the source system

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/invoices
Request samples
application/json
{
  • "externalId": "SUPPLIER_INVOICE-3-1",
  • "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,
  • "relatedInvoice": "SUPPLIER_INVOICE-3-2",
  • "currency": "EUR",
  • "totalNetAmount": 81,
  • "totalFreightCharges": 9,
  • "totalOtherCharges": 10,
  • "totalTaxAmount": 19,
  • "totalGrossAmount": 119,
  • "paymentTerms": {
    },
  • "externalApproverId": "UserID#1234",
  • "customFields": {
    },
  • "headerText": "doc header text",
  • "type": "FI",
  • "invoiceLines": [
    ],
  • "withholdingTax": [
    ],
  • "documentType": "supplier invoice"
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark invoice as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

query Parameters
lineNumber
string

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

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/invoices/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert company

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S+$

External unique id of the company in the source system

name
required
string^[\S ]*\S[\S ]*$

Name of the company

nameAlternative1
string^[\S ]*\S[\S ]*$

Alternative name of the company

nameAlternative2
string^[\S ]*\S[\S ]*$

Alternative name of the company

nameAlternative3
string^[\S ]*\S[\S ]*$

Alternative name of the company

nameAlternative4
string^[\S ]*\S[\S ]*$

Alternative name of the company

street
string

Street and street number where the company is located

addressAdditional
string

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

postcode
string

Postcode where the company is located

city
string

City where the company is located

state
string

State where the company is located

countryCode
string 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" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
Array of objects (vatId)

List of VAT IDs assigned to the company

Array of objects (taxId)

List of Tax IDs assigned to the company

object (customFields)

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

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/companies
Request samples
application/json
{
  • "externalId": "DE01",
  • "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": [
    ],
  • "taxIds": [
    ],
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark company as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/companies/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert supplier including related subsidiaries

SecurityOAuth2
Request
Request Body schema: application/json
required
object
externalId
required
string^\S+$

External unique id of the supplier in the source system

name
required
string^[\S ]*\S[\S ]*$

Name of the supplier

nameAlternative1
string^[\S ]*\S[\S ]*$

Alternative name of the supplier

nameAlternative2
string^[\S ]*\S[\S ]*$

Alternative name of the supplier

nameAlternative3
string^[\S ]*\S[\S ]*$

Alternative name of the supplier

nameAlternative4
string^[\S ]*\S[\S ]*$

Alternative name of the supplier

street
string

Street and street number where the supplier is located

addressAdditional
string

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

postcode
string

Postcode where the supplier is located

city
string

City where the supplier is located

state
string

State where the company is located

countryCode
string 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" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
Array of objects (vatId)

List of VAT IDs assigned to the supplier

Array of objects (taxId)

List of Tax IDs assigned to the supplier

blockedForPosting
boolean

Indicator if the supplier is blocked for posting

blockedForPayment
boolean

Indicator if the supplier is blocked for payment

Array of objects (subsidiary)
Array of objects (bankAccount)
object (customFields)

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

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/suppliers
Request samples
application/json
{
  • "defaultAccountAssignment": {
    },
  • "externalId": "0000100000",
  • "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": [
    ],
  • "taxIds": [
    ],
  • "blockedForPosting": false,
  • "blockedForPayment": false,
  • "supplierSubsidiaries": [
    ],
  • "supplierBankAccounts": [
    ],
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark supplier as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/suppliers/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert purchase order including purchase order lines

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S+$

External unique id of the purchase order in the source system

createdDate
string <date>

Date when the purchase order was created in the external system

fiscalYearLabel
string

Label used in the source system for the fiscal year that the purchase order was created in

language
string or null

Two letter language code as defined in ISO 639-1

Enum: "aa" "ab" "ae" "af" "ak" "am" "an" "ar" "as" "av" "ay" "az" "ba" "be" "bg" "bh" "bi" "bm" "bn" "bo" "br" "bs" "ca" "ce" "ch" "co" "cr" "cs" "cu" "cv" "cy" "da" "de" "dv" "dz" "ee" "el" "en" "eo" "es" "et" "eu" "fa" "ff" "fi" "fj" "fo" "fr" "fy" "ga" "gd" "gl" "gn" "gu" "gv" "ha" "he" "hi" "ho" "hr" "ht" "hu" "hy" "hz" "ia" "id" "ie" "ig" "ii" "ik" "io" "is" "it" "iu" "ja" "jv" "ka" "kg" "ki" "kj" "kk" "kl" "km" "kn" "ko" "kr" "ks" "ku" "kv" "kw" "ky" "la" "lb" "lg" "li" "ln" "lo" "lt" "lu" "lv" "mg" "mh" "mi" "mk" "ml" "mn" "mr" "ms" "mt" "my" "na" "nb" "nd" "ne" "ng" "nl" "nn" "no" "nr" "nv" "ny" "oc" "oj" "om" "or" "os" "pa" "pi" "pl" "ps" "pt" "qu" "rm" "rn" "ro" "ru" "rw" "sa" "sc" "sd" "se" "sg" "si" "sk" "sl" "sm" "sn" "so" "sq" "sr" "ss" "st" "su" "sv" "sw" "ta" "te" "tg" "th" "ti" "tk" "tl" "tn" "to" "tr" "ts" "tt" "tw" "ty" "ug" "uk" "ur" "uz" "ve" "vi" "vo" "wa" "wo" "xh" "yi" "yo" "za" "zh" "zu" null
externalCompanyId
string

Company that the purchase order is assigned to

type
string

type of the purchase order as defined in the source system

externalSupplierId
string

External unique id of the supplier in the source system

status
string

Status of purchase order as defined in source system

currency
string or null (CurrencyCode)

Three letter currency code as defined in ISO 4217

Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "QAR" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL" null
totalNetAmount
number

Total net amount of purchase order (sum of line item net amounts)

totalFreightCharges
number

Sum of all freight charges as defined on the purchase order

totalOtherCharges
number

Sum of all charges other than freight charges as defined on the purchase order

totalTaxAmount
number

Total tax amount of purchase order (sum of all taxes)

totalGrossAmount
number

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

object (paymentTerms)
object (customFields)

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

Array of objects (purchaseOrderLine)
Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/purchase-orders
Request samples
application/json
{
  • "externalId": "4500016221",
  • "createdDate": "2000-12-31",
  • "fiscalYearLabel": "2023",
  • "language": "string",
  • "externalCompanyId": "DE01",
  • "type": "Service",
  • "externalSupplierId": "0000100000",
  • "status": "OPEN",
  • "currency": "EUR",
  • "totalNetAmount": 81,
  • "totalFreightCharges": 9,
  • "totalOtherCharges": 10,
  • "totalTaxAmount": 19,
  • "totalGrossAmount": 119,
  • "paymentTerms": {
    },
  • "customFields": {
    },
  • "purchaseOrderLines": [
    ]
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark purchase Order as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

query Parameters
lineNumber
string

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

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/purchase-orders/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert general ledger account

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S([\S ]*\S)?$

External unique id of the general ledger account in the source system

code
required
string^\S([\S ]*\S)?$

Code of the general ledger account in the source system

companyAssignment
Array of strings

List of externalCompanyIds that the approver is assigned to

object (languagedTextWithValue)
object (languagedTextWithValue)
Array of objects (languagedText)

Label describing the general ledger account

Array of objects (languagedText)

Short label describing the general ledger account

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/gl-accounts
Request samples
application/json
{
  • "externalId": "0000100GL1",
  • "code": "GL1",
  • "companyAssignment": [
    ],
  • "type": {
    },
  • "category": {
    },
  • "label": [
    ],
  • "shortLabel": [
    ]
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark general ledger account as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/gl-accounts/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert cost center

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S([\S ]*\S)?$

External unique id of the cost center in the source system

code
required
string^\S([\S ]*\S)?$

Code of the cost center in the source system

companyAssignment
Array of strings

List of externalCompanyIds that the approver is assigned to

object (languagedTextWithValue)
object (languagedTextWithValue)
Array of objects (languagedText)

Label describing the cost center

Array of objects (languagedText)

Short label describing the cost center

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/cost-centers
Request samples
application/json
{
  • "externalId": "0000100CO1",
  • "code": "CO1",
  • "companyAssignment": [
    ],
  • "type": {
    },
  • "category": {
    },
  • "label": [
    ],
  • "shortLabel": [
    ]
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark cost Center as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/cost-centers/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert approver

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S+$

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

companyAssignment
Array of strings

List of externalCompanyIds that the approver is assigned to

isActive
boolean
firstName
string

First name of the approving person

lastName
string

Last name of the approving person

email
string <email>

Email address of the approving person

phoneNumber
string

Phone number of the approving person

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/approvers
Request samples
application/json
{
  • "externalId": "UserID#1234",
  • "companyAssignment": [
    ],
  • "isActive": true,
  • "firstName": "Koala",
  • "lastName": "Hinze",
  • "email": "accountant@sap.com",
  • "phoneNumber": 491001234567891
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark approver as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/approvers/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Insert customer

SecurityOAuth2
Request
Request Body schema: application/json
required
externalId
required
string^\S+$

External unique id of the customer in the source system

name
required
string^[\S ]*\S[\S ]*$

Name of the customer

nameAlternative1
string^[\S ]*\S[\S ]*$

Alternative name of the customer

nameAlternative2
string^[\S ]*\S[\S ]*$

Alternative name of the customer

nameAlternative3
string^[\S ]*\S[\S ]*$

Alternative name of the customer

nameAlternative4
string^[\S ]*\S[\S ]*$

Alternative name of the customer

street
string

Street and street number where the customer is located

addressAdditional
string

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

postcode
string

Postcode where the customer is located

city
string

City where the customer is located

countryCode
string 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" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW" null
Array of objects (vatId)

List of VAT IDs assigned to the customer

Array of objects (taxId)

List of Tax IDs assigned to the customer

blockedForPosting
boolean

Indicator if the customer is blocked for posting

blockedForPayment
boolean

Indicator if the customer is blocked for payment

Array of objects (subsidiary)
Array of objects (bankAccount)
object (customFields)

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

Responses
200

Successfully inserted

422

Validation error

429

Rate limit exceeded

post/enrichment/customers
Request samples
application/json
{
  • "externalId": "0000100000",
  • "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": [
    ],
  • "taxIds": [
    ],
  • "blockedForPosting": false,
  • "blockedForPayment": false,
  • "customerSubsidiaries": [
    ],
  • "customerBankAccounts": [
    ],
  • "customFields": {
    }
}
Response samples
application/json
{
  • "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}

Mark customer as deleted

SecurityOAuth2
Request
path Parameters
externalId
required
string

Previously sent externalId

Responses
204

Successfully marked as deleted

404

Not Found error

429

Rate limit exceeded

delete/enrichment/customers/{externalId}
Request samples
Response samples
application/json
{
  • "status": 404,
  • "title": "Not found"
}

Companies

Endpoints for company management

Retrieve a company by id

SecurityOAuth2
Request
path Parameters
id
required
string (CompaniesId)

Id of the company to retrieve

Example: 63e6663823b4c1f5287398bb
Responses
200

Successful Response

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

422

Validation Error

429

Rate limit exceeded

500

Internal Server Error

get/companies/{id}
Request samples
Response samples
application/json
{
  • "name": "Companies Name Inc.",
  • "id": "63e6663823b4c1f5287398bb",
  • "active": true,
  • "createdAt": "1990-12-31T15:46:19.384990Z"
}

Retrieve a list of companies

Note: For now pagination is not implemented

SecurityOAuth2
Responses
200

Successful Response

422

Validation Error

429

Rate limit exceeded

get/companies
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "totalCount": 1000
}

Projects

Endpoints for project management

Create a project

Creates a project based on the request

SecurityOAuth2
Request
Request Body schema: application/json
required

Project data

name
required
string (ProjectName) [ 1 .. 60 ] characters

Project name

note
string (ProjectNote) [ 1 .. 1000 ] characters

Project note

required
any
extractionModelId
required
string (ProjectExtractionModelId)

Extraction Model id

completion
string (ProjectCompletion)
Default: "manual"

ProjectCompletion type

  • automatic - Mark documents as completed after succesfull validation
  • manual - Mark documents to review after succesfull validation
Enum: "automatic" "manual"
duplicates
string (ProjectDuplicates)
Default: "fail"

How duplicates documents show be handle

  • allow - Allow documents duplicates to be processed
  • fail - Mark documents duplicates as failed
Enum: "allow" "fail"
required
any
object (Schema)
retentionDays
integer >= 1
Default: 180

Project document retention in days

Responses
201

Project created

400

Response when client request is wrong

401

Unauthorized

403

Forbidden

404

Response when resource was not found

422

Validation error

post/projects
Request samples
application/json
{
  • "name": "My Project",
  • "note": "My project description note",
  • "ocr": {
    },
  • "extractionModelId": "63e6663823b4c1f5287398bb",
  • "completion": "manual",
  • "duplicates": "allow",
  • "members": {
    },
  • "schema": {
    },
  • "retentionDays": 180
}
Response samples
application/json
{
  • "id": "63e6663823b4c1f5287398bb",
  • "createdAt": "1990-12-31T15:46:19.384990Z",
  • "createdBy": "63e6663823b4c1f5287398bb",
  • "updatedAt": "1990-12-31T15:46:19.384990Z",
  • "updatedBy": "63e6663823b4c1f5287398bb",
  • "name": "My Project",
  • "note": "My project description note",
  • "extractionModelId": "63e6663823b4c1f5287398bb",
  • "ocr": {
    },
  • "completion": "manual",
  • "duplicates": "allow",
  • "members": {
    },
  • "retentionDays": 180
}

Retrieve a projects list for given search criteria

SecurityOAuth2
Request
query Parameters
offset
integer >= 0

A zero-based offset of the first item in the data collection to return.

limit
integer [ 0 .. 50 ]
Default: 20

Limit the amount of items returned in the response. If the value exceeds the maximum, then the maximum value will be used.

sort
string
Default: "-createdAt"

The field to sort reponse items by.

Enum: "-createdAt" "+createdAt"
search
string (Search text used to find projects.)

Search text is used against projects name and id

Responses
200

Projects list retrieved

401

Unauthorized

403

Forbidden

422

Validation error

500

Internal Server Error

get/projects
Request samples
Response samples
application/json
{
  • "data": [
    ],
  • "limit": 20,
  • "offset": 0,
  • "totalCount": 1
}

Retrieve a project by id

Retrieve a project by id

SecurityOAuth2
Request
path Parameters
id
required
string (ProjectId)

Project id

Example: 63e6663823b4c1f5287398bb
Responses
200

Project by id

401

Unauthorized

403

Forbidden

404

Response when resource was not found

get/projects/{id}
Request samples
Response samples
application/json
{
  • "id": "63e6663823b4c1f5287398bb",
  • "createdAt": "1990-12-31T15:46:19.384990Z",
  • "createdBy": "63e6663823b4c1f5287398bb",
  • "updatedAt": "1990-12-31T15:46:19.384990Z",
  • "updatedBy": "63e6663823b4c1f5287398bb",
  • "name": "My Project",
  • "note": "My project description note",
  • "extractionModelId": "63e6663823b4c1f5287398bb",
  • "ocr": {
    },
  • "completion": "manual",
  • "duplicates": "allow",
  • "members": {
    },
  • "retentionDays": 180
}

Retrieve a schema by project id

Retrieve a schema by project id

SecurityOAuth2
Request
path Parameters
id
required
string (ProjectId)

Project id

Example: 63e6663823b4c1f5287398bb
Responses
200

Schema retrieved

400

Response when client request is wrong

401

Unauthorized

403

Forbidden

404

Response when resource was not found

get/projects/{id}/schema
Request samples
Response samples
application/json
{
  • "version": 1,
  • "dataPoints": [
    ],
  • "features": {
    },
  • "enrichment": { },
  • "normalization": { },
  • "validation": { }
}

E-Invoices

Endpoints for e-invoices

Retrieve a document PDF preview for e-invoices

Provides a binary file of a document PDF preview for e-invoices

SecurityOAuth2
Request
path Parameters
id
required
string

Id of the document.

Responses
200

Binary content of a file

404

Not Found

429

Rate limit exceeded

get/e-invoices/{id}/preview
Request samples
Response samples
application/json
{
  • "detail": "The document with given identifier does not exist",
  • "status": 404,
  • "title": "Document does not exist"
}

Emails

Retrieve an email merged content for given document ID

SecurityOAuth2
Request
path Parameters
id
required
string (Document identifier)
Example: 6295dcd39db1ab740c3e296c
Responses
200

Successful Response

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/emails/{id}/content
Request samples
Response samples
application/json
{
  • "status": 401,
  • "title": "Invalid token",
  • "detail": "Error details"
}

Retrieve an email metadata for given document ID

SecurityOAuth2
Request
path Parameters
id
required
string (Document identifier)
Example: 6295dcd39db1ab740c3e296c
Responses
200

Successful Response

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

get/emails/{id}