API Documentation

Hypatos provides access to it's pre-trained invoice extractor via API so you can use it straight in your own applications.
For pricing and signup please contact our sales department at +49 30 209970-902.


You must authenticate to use the API. After you have received your account credentials you have to call our login endpoint in order to receive an access token. With this token you can then use the extraction endpoint.

Call to retrieve a token:

curl -X POST \
  'https://api.hypatos.ai/iam/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "user@domain.com",
    "password": "your-api-password",
    "grant_type": "password"

Returns the following result on success:

  "access_token": "your-token-here"

Calling the extract endpoint


The extractor only takes PDF documents. For sending it in a json request body you have to first base64 encode our pdf file. Then call the extract endpoint with your token from above:

curl -X POST \
  'https://api.hypatos.ai/v1/invoice-extract' \
  -H 'Authorization: Bearer your-token-here' \
  -H 'Content-Type: application/pdf' \
  --data-binary @path/to/your-document.pdf

The extractor supports data in hOCR (HTML) format, if that’s your case you might call it similarly by:

curl -X POST \
  'https://api.hypatos.ai/v1/invoice-extract' \
  -H 'Authorization: Bearer your-token-here' \
  -H 'Content-Type: application/xml' \
  --data-binary @path/to/your-document.xml
Output object and extra parameters

That’s an example of the output object:

    "id": "f37b3ed3-0ea1-11e9-9aaf-2288b0932d4e",
    "status": "processed",
    "result": {
      "entities": {
        "type": "invoice",
        "issuedAt": "2017-06-16",
        "number": "1-5218",
        "currency": "EUR", 
      "infos": {
        "numPages": 1
      "probabilities": {
        "type": 0.9603405793507894,
        "issuedAt": 0.19987956310311952,
        "number": 0.919721802075704,
        "currency": 0.3527391602595647,
      "ocr": "OCR_OUTPUT_XML"

OCR and probabilities extra attributes can be turned on by setting the url parameters as:

curl -X POST \