Powered by Redocly

Hypatos REST API (2.18.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": "document.create project.create"
}

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/pdf
{
  "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,
  • "message": "Upload failed due to ERP being down"
}
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) 
 
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": [
    ]
}
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


 
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.",
  • "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


 
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


 
defaultGlAccountCode
string
 Deprecated 
Default general ledger account that is assigned to the supplier. Deprecated, use defaultAccountAssignment.glAccountCode instead.


 
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.",
  • "street": "Hauptstr. 1",
  • "addressAdditional": "Eingang B",
  • "postcode": "10001",
  • "city": "Berlin",
  • "state": "Berlin",
  • "countryCode": "DE",
  • "vatIds": [
    ],
  • "taxIds": [
    ],
  • "blockedForPosting": false,
  • "blockedForPayment": false,
  • "defaultGlAccountCode": "0000100GL1",
  • "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


 
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.",
  • "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": { }
}
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}
Request samples 
Response samples 
application/json
{
  • "id": "6040dc9680b782b365ea77d5",
  • "senderAddresses": [
    ],
  • "subject": "Document from this month"
}