NAV Navbar
shell

Gini Accounting API documentation (v1.0)

Introduction

Gini provides an information extraction system for analyzing documents (e. g. invoices or contracts), specifically information such as the document sender or the amount to pay in an invoice.

The API supports documents in the formats PDF, GIF, JPEG, PNG, and TIFF.

Furthermore there is the distinction between native PDF files (i. e. files digitally created from Microsoft Word documents and containing textual information) and scanned PDF files, created by scanning paper documents.

After a file has been submitted and validated, Gini first extracts the textual contents of the document. Native PDF files already contain this information and are analyzed accordingly. Scanned documents (like the aforementioned) image files do not provide easily processable information directly, so Gini has to preprocess these files using Optical Character Recognition (OCR) and other methods to obtain their content.

Once the layout and textual information is available for the uploaded document, Gini starts extracting semantic and meta information about the document, such as the document sender (e. g. name, address) or the document type (e. g. invoice, contract).

In the unlikely case that Gini was unable to infer the information correctly, it is possible to correct the extractions manually (e. g. by selecting the correct amount to pay on the document) and submit it back to the API. This also helps to improve the learning extraction system over time.

If you have any questions about the Gini Accounting API and the functionality it provides, please contact us via api@gini.net.

Getting started

Welcome! To process your first document with the Gini Accounting API, follow these easy steps:

  1. Register your application
  2. create user
  3. upload
  4. document retrieval
  5. extractions
  6. feedback

For general information about the Gini Accounting API, see overview.

Prerequisites

Before you can use the Gini Accounting API within your application, you need a valid client ID and client secret. If you don't have a client ID and client secret already, please contact your sales representative.

Create a user and obtain an access token

Create a user and obtain an access token

curl -v -X POST --data-urlencode 'username=random@example.org' 
        --data-urlencode 'password=geheim'  
        -H 'Content-Type: application/x-www-form-urlencoded' 
        -H 'Accept: application/json' 
        -u 'client-id:client-secret' 
        'https://user.gini.net/oauth/token?grant_type=password'

The response will look similar to this:

{
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

6c470ffa-abf1-41aa-b866-cd3be0ee84f4 is the access token which can be used for API requests.

All requests to the Gini Accounting API are made on behalf of a user, authorized by an access token. For now, it's assumed that you already created an anonymous user and obtained an access token for it. For details on how to do so, please read guide-anonymous-accounts.

To get an access token for a Gini account, use the following command (replace client-id with your client ID and client-secret with your client secret as well as random@example.org with your username and geheim with your password):

Upload a document

Upload a document

curl -v -X POST --data-binary '@/path/to/your/document.pdf' 
     -H 'Accept: application/vnd.gini.v1+json' 
     -H 'Authorization: BEARER b6c470ffa-abf1-41aa-b866-cd3be0ee84f' 
     'https://accounting-api.gini.net/documents'

Now that you have an access token, you can upload your first document. The Gini API is versionized via a custom media type, hence all requests to the API must state against which version of the API they are made.

For our first document, we will use Gini Accounting API V1. The following command uploads the document.

Accepted

HTTP/1.1 201 Created
X-Request-Id: 7b5a7f79-ae7c-4040-b6cf-25cde58ad937
Location: https://accounting-api.gini.net/documents/b4bd3e80-7bd1-11e4-95ab-000000000000
Content-Type: application/vnd.gini.v1+json

If the file was accepted by the Gini Accounting API (i.e. it is in one of the supported file formats), Gini automatically starts to process the document. The response will have HTTP status code 201 and the response's Location header points to the created document:

Wait for the document processing to complete

Getting document processing information

curl -v -H 'Accept: application/vnd.gini.v1+json' 
        -H 'Authorization: BEARER b6c470ffa-abf1-41aa-b866-cd3be0ee84f' 
  'https://accounting-api.gini.net/documents/b4bd3e80-7bd1-11e4-95ab-000000000000'

The response body will look similar to this:

{
  "_links": {
    "processed": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000\/processed",
    "layout": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000\/layout",
    "extractions": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000\/extractions",
    "document": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000"
  },
  "sourceClassification": "NATIVE",
  "origin": "UPLOAD",
  "progress": "PENDING",
  "creationDate": 1417710133864,
  "pages": [
    {
      "images": {
        "1280x1810": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000\/pages\/1\/1280x1810",
        "750x900": "https:\/\/accounting-api.gini.net\/documents\/b4bd3e80-7bd1-11e4-95ab-000000000000\/pages\/1\/750x900"
      },
      "pageNumber": 1
    }
  ],
  "pageCount": 1,
  "name": "Document",
  "id": "b4bd3e80-7bd1lll-11e4-95ab-000000000000"
}

The next step is now to wait until the processing of the document has been completed. To check the current status of the document, you can issue a GET request on the URL which you received in the API response when the document was submitted:

When the value of progress changes to COMPLETED, processing of the document is completed and you can proceed with the next step. To notice the transition from PENDING to COMPLETED, your application needs to periodically poll the document status.

Retrieve the extractions

To retrieve the extractions

curl -v -H 'Accept: application/vnd.gini.v1+json' 
    -H 'Authorization: BEARER b6c470ffa-abf1-41aa-b866-cd3be0ee84f' 
    'https://accounting-api.gini.net/documents/b4bd3e80-7bd1-11e4-95ab-000000000000/extractions'

The Gini Accounting API returns the information it has extracted from the document in so-called extractions. To receive all extractions, execute the following request:

Example

{
  "extractions": {
    "docType": {
      "value": "Invoice",
      "entity": "doctype"
    },
    "amountToPay": {
      "candidates": "amounts",
      "box": {
        "page": 1,
        "height": 9.0,
        "width": 30.870000000000005,
        "left": 524.13,
        "top": 357.89
      },
      "value": "12.00:EUR",
      "entity": "amount"
    },
    "customerId": {
      "candidates": "customerIds",
      "box": {
        "page": 1,
        "height": 7.0,
        "width": 31.139999999999986,
        "left": 470.0,
        "top": 152.89
      },
      "value": "20980000",
      "entity": "customerid"
    },
    "invoiceId": {
      "candidates": "invoiceIds",
      "box": {
        "page": 1,
        "height": 7.0,
        "width": 38.920000000000016,
        "left": 470.0,
        "top": 143.89
      },
      "value": "3113805926",
      "entity": "invoiceid"
    },
    "senderName": {
      "candidates": "senderNames",
      "box": {
        "page": 1,
        "height": 7.0,
        "width": 52.56000000000001,
        "left": 41.87,
        "top": 88.84
      },
      "value": "Deutsche Post AG",
      "entity": "companyname"
    }
  },
  "candidates": {
    "amounts": [
      {
        "box": {
          "page": 1,
          "height": 9.0,
          "width": 30.870000000000005,
          "left": 524.13,
          "top": 357.89
        },
        "value": "12.00:EUR",
        "entity": "amount"
      },
      {
        "box": {
          "page": 1,
          "height": 12.0,
          "width": 40.89999999999998,
          "left": 138.02,
          "top": 413.09
        },
        "value": "12.00:EUR",
        "entity": "amount"
      }
   ],
    "senderNames": [
      {
        "box": {
          "page": 1,
          "height": 7.0,
          "width": 52.56000000000001,
          "left": 41.87,
          "top": 88.84
        },
        "value": "Deutsche Post AG",
        "entity": "companyname"
      }
    ],
    "customerIds": [
      {
        "box": {
          "page": 1,
          "height": 7.0,
          "width": 31.139999999999986,
          "left": 470.0,
          "top": 152.89
        },
        "value": "20980000",
        "entity": "customerid"
      }
    ],
    "invoiceIds": [
      {
        "box": {
          "page": 1,
          "height": 7.0,
          "width": 38.920000000000016,
          "left": 470.0,
          "top": 143.89
        },
        "value": "3113805926",
        "entity": "invoiceid"
      }
    ]
  }
}

The returned object contains specific extractions (a value with some specific semantic property) as well as candidates (a list of values for some semantic property).

In this (shortened) example, the processed document was an invoice (see docType) issued by Deutsche Post AG with invoice number 3113805926 (see invoiceId). The receiver of the invoice has to pay 12€ (see amountToPay.

Send feedback and get even better extractions next time

To improve the result of future extractions, your application should always give some feedback about the correctness of a document's extractions. To tell Gini that an extraction was correct, send back the same value in the feedback request. In the unlikely case that the Gini Accounting API returned a wrong extraction value, you can send back a corrected value. Gini will then learn from that mistake.

Overview of the Gini Accounting API

This section provides general information about the Gini Accounting API. If you want a step-by-step guide how to upload your first document and retrieve its semantic content, have a look at the getting started guide <guide-getting-started>.

IPv6 compatibility

    $ host accounting-api.gini.net
    accounting-api.gini.net has address 46.245.182.123
    accounting-api.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::7

    $ host user.gini.net
    user.gini.net has address 46.245.182.124
    user.gini.net has IPv6 address 2a00:14e0:600:1500:d0c5::2

Gini Accounting API and User Center are accessible from legacy IPv4 and IPv6 networks. The protocol precedence depends on your operating system and configuration if both protocols are enabled.

Media Types

The media types consumed and produced by the Gini Accounting API look like this

    application/vnd.gini.<version>+json

Custom media types are used in the API to let consumers choose the version of the data format they wish to receive. This is done by adding one or more of the following media types to the Accept header when a request is made. Media types are specific to resources, allowing them to change independently and supporting formats that other resources don't.

Versions

Currently there is one stable version of the Gini Accounting API. Future versions can be requested using a specific Accept header. Additionally, we provide a unstable incubator version of the Gini Accounting API. This is primarily for testing new extractions but may affect other parts of the Gini Accounting API as well.

v1

v1 media type

    Accept: application/vnd.gini.v1+json 

Gini Accounting API v1 is stable and will not be changed in an incompatible way. Please contact us via api@gini.net if you have any problems.

By default all requests receive data in version 1 of the API. Developers are strongly encouraged to explicitly specify the required version of the Gini Accounting API using the HTTP/1.1 Accept header:

incubator

incubator media type

    Accept: application/vnd.gini.incubator+json

Gini Accounting API incubator is unstable and can change at any time. We will provide new and immature features (e.g. extractions) exclusively under this Gini Accounting API version. We encourage developers to test these features and to give us feedback under api@gini.net. The incubating features are accessible by using the HTTP/1.1 Accept header:

See incubator for further information.

Authentication

Only authenticated users are allowed to make API requests. The Gini API uses the OAuth 2.0 protocol with bearer tokens for authentication. To use the Gini Accounting API within your application, you first have to register your application with Gini. Then your application requests an access token from the Gini Authorization Server and uses that token to access the Gini Accounting API.

Security

The Gini Accounting API is only accessible over HTTPS. Please make sure that your application validates the relevant X.509 certificates (e.g. common name matches hostname, issuing CA is trusted, etc.).

Client Errors

HTTP response codes

The API uses idiomatic HTTP status codes to indicate if a request was successful, and if not, whether it should be retried.

Code Description
2xx The request was successful.
4xx The request was not successful. See the response body for details. Retrying with the same arguments will not work.
5xx Some error occurred while processing the request. Please try again.

Error entity

Error entity response

{
  "message": "Validation of the request entity failed",
  "requestId": "8896f9dc-260d-4133-9848-c54e5715270f"
}

The Gini Accounting API always returns a JSON object further describing the error which occurred. The JSON object consists of the following properties:

Name Type Description
message string Human consumable error description (not intended for application end-users)
requestId string Unique ID identifying the request. Please provide this when contacting the support.

Managing anonymous Gini accounts

For best results, the Gini Accounting API must be able to track requests down to individual users for various reasons:

Gini offers various ways to perform requests on behalf of individual users, without requiring physical user interaction. Depending on your use case and the architecture of your product, the following ways to authenticate to the Gini Accounting API are possible:

Communication to the Gini Accounting API via a backend/gateway

Communication example: to get the list of user1's documents, use the following request:

curl -v -H 'Accept: application/vnd.gini.v1+json' 
    -u 'client-id:client-secret' 
    -H 'X-User-Identifier: user1' 
    https://accounting-api.gini.net/documents

This authentication scheme is based on HTTP Basic Authentication. Your application uses HTTP Basic Authentication to authenticate itself against the Gini Accounting API. In addition to the Authorization header, another header called X-User-Identifier is sent per request. This header is used by the Gini Accounting API to distinguish individual users. Your application is free to choose whatever value it wants for the header, as long as the following constraints are met:

Direct communication from client devices to the Gini Accounting API

Gini offers the user_center_api to work with Gini users. This step-by-step guide outlines how to create and use a new (anonymous) Gini account. See the links to the corresponding sections of the user_center_api for details about each step.

1. Obtain a client token <client_authentication>

To obtain a client token <client_authentication&gt

curl -v -H 'Accept: application/json' 
    -u 'client-id:client-secret' 
    'https://user.gini.net/oauth/token?grant_type=client_credentials'

In case of success, the response will have HTTP status 200 and 1eb7ca49-d99f-40cb-b86d-8dd689ca2345 is returned as client access token:

{
  "access_token":"1eb7ca49-d99f-40cb-b86d-8dd689ca2345",
  "token_type":"bearer","expires_in":43199,"scope":"read"
}

Before you are able to use the user_center_api, you need to obtain a client access token. This client access tokes authorizes your client (i.e. your application) against the user_center_api.

It is assumed that you have a client ID client-id and a client secret client-secret. Authorized by those (with HTTP Basic Authentication), your client can obtain a client access token using the following request:

2. Create a new user <creating_a_new_user>

Create a new user <creating_a_new_user>

This will create a new user random@example.org with password geheim. If the creation is successful, the response will have HTTP status 201 and the response contains a Location header that points to the new user.

curl -v -X POST --data '{"email":"random@example.org", "password":"geheim"}' 
    -H 'Content-Type: application/json' 
    -H 'Accept: application/json' 
    -H 'Authorization: BEARER 1eb7ca49-d99f-40cb-b86d-8dd689ca2345' 
    'https://user.gini.net/api/users'

Your client is now allowed to create a new user, authorized by the client access token.

Two values are required for a new user: A username and a password. The username must be a syntactically correct email address whose domain part is easily linkable to your application. For example, if your company is called Example Inc., then app.example.org would be a good domain to use for your app's user accounts.

3. Log in as that user <authenticating_on_behalf_of_a_user>

Login as that user

curl -v -X POST --data-urlencode 'username=random@example.org' 
    --data-urlencode 'password=geheim'  
    -H 'Content-Type: application/x-www-form-urlencoded' 
    -H 'Accept: application/json' -u 'client-id:client-secret' 
    'https://user.gini.net/oauth/token?grant_type=password'

Note that this request requires HTTP Basic Authentication again, with the client ID as username and the client secret as password. It does not require a client access token.

The result is an access token that can be used to make API requests on behalf of the user.

4. Making API requests with the access token

Use the access token you obtained to make requests to the API

GET /documents HTTP/1.1
Host: accounting-api.gini.net
Authorization: BEARER 760822cb-2dec-4275-8da8-fa8f5680e8d4
Accept: application/vnd.gini.v1+json
Connection: close

Use the access token you obtained to make requests to the API, by sending the access token as a bearer token in the Authorization request header:

Documents

As the key aspect of the Gini Accounting API is to provide information extraction for analyzing documents, the API is mainly built around the concept of documents. A document can be any written representation of information such as invoices, reminders, contracts and so on.

The main idea is that you submit a document in form of an electronic file to Gini. After the document has been analyzed by Gini you can get the information that is extracted from the document by querying the API.

The following documentation explains those actions in detail.

Submitting files

Documents can be submitted by doing a POST request on the /documents resource.

    POST /documents

In order to analyze a document, the document source file must be first submitted to Gini.

You can submit documents by using the file of the document and calling a POST request on the /documents path. After successful creation of a document, the location of the new document is returned in the Location header.

The Gini Accounting API currently supports two different variants of uploads, one optimized for web applications running in a web browser and one for all other types of clients.

The variant optimized for web browsers expects the documents to be uploaded using a multipart/form-data request as constructed by typical web browsers.

The variant aimed at all other clients simply uses the request body (independent of the Content-Type of the request) as document.

Supported file formats

Gini currently supports input files in the formats PDF, GIF (non-animated), PNG, JPEG, TIFF and plain text files. You can use native documents (PDF only) as well as scanned document (all formats). Note that there are certain limitations on a document that the Gini Accounting API accepts:

Document Type Hints

The type of a document is in many cases known to the client application. If you provide the doctype parameter with a valid value from the extraction-entity-doctype entity , Gini can optimize the processing of the document in many ways. Furthermore, some incubating extractions may only available if the document type is provided.

Request

Example

Variant for web applications running in a web browser:

curl -H 'Authorization: BEARER <token>' 
    --form 'file=@file.pdf' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents

Variant for other types of applications:

curl -H 'Authorization: BEARER <token>' 
    --data-binary '@file.pdf' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents?filename=file.pdf
Headers
Header Value
Content-Type multipart/form-data; boundary=...
*/*
Accept application/vnd.gini.v1+json
Request query parameters

If the upload is performed not using multipart/form-data you can optionally provide a file name for the submitted document with a query parameter:

Name Type Description
filename string (Optional) File name of the submitted document
doctype string (Optional) Type of the submitted document See extraction-entity-doctype for possible values
Body

Only in case of Content-Type: multipart/form-data (applications running in a web browser):

Key Description
Content-Disposition form-data
file File contents of document

Response

Headers
Status Code Description
201 (Created) Success
Header Value
Content-Type application/vnd.gini.v1+json
Location Absolute URI of created document (document URI)
Errors
Status Code Description
400 (Bad Request) Returned when a file in an invalid format is sent

Checking processing status and getting document information

Document information can be retrieved by doing a GET request on the document URI.

    GET /documents/{id}

After submission the document is processed. You can check the processing status of a single document by examining the document information. It can be retrieved by a GET request to the document URI. When the document has been processed you can retrieve the extractions from it and additional information such as the document layout.

Request

Get document processing status

curl -H 'Authorization: BEARER <token>' 
    -X GET -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000
Headers
Header Value
Accept application/vnd.gini.v1+json

Response

response

{
  "id": "626626a0-749f-11e2-bfd6-000000000000",
  "creationDate": 1360623867402,
  "name": "scanned.jpg",
  "progress": "COMPLETED",
  "origin": "UPLOAD",
  "sourceClassification": "SCANNED",
  "pageCount": 1,
  "pages" : [
    {
      "images" : {
        "750x900" : "http://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000/pages/1/750x900",
        "1280x1810" : "http://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000/pages/1/1280x1810"
      },
      "pageNumber" : 1
    }
  ],
  "_links": {
    "extractions": "https://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000/extractions",
    "layout": "https://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000/layout",
    "document": "https://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000",
    "processed": "https://accounting-api.gini.net/documents/626626a0-749f-11e2-bfd6-000000000000/processed"
  }
}
Headers
Status Code Description
200 (OK) Success
Header Value
Content-Type application/vnd.gini.v1+.json
Body (application/vnd.gini.v1+json)
Key Child Key Type Description
id string Unique identifier of document as UUID Version 1
name string Document name (as stated on upload)
pageCount number Number of pages
creationDate number Unix timestamp of document creation date in milliseconds
origin string Source channel of the document, either UPLOAD (when uploaded through Gini Accounting API) or UNKNOWN
progress string Processing status of the document, either PENDING, COMPLETED, or ERROR
sourceClassification string Classification of the source file, either SCANNED, SANDWICH, NATIVE or TEXT.
pages array List of page objects
pageNumber number Page number in the document
images object URIs to pre-rendered page images
_links array List of related resources, e. g. the found extractions or the document layout
extractions string URI to extractions of the document (extractions URI)
layout string URI to the layout of the document (layout URI)
processed string URI to the processed document
document string URI to the document, meaning the current resource (document URI)

Errors

Status Code Description
404 (Not Found) Returned when no document can be found under the specific URI

Retrieving extractions

Extractions can be retrieved by doing a GET request on the extractions URI:

    GET /documents/{id}/extractions

After a document has been processed, the extractions from the document analysis can be retrieved. See document_extractions for details about extractions.

Request

Get extractions

curl -H 'Authorization: BEARER <token>' 
    -X GET -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/extractions
Headers
Header Value
Accept application/vnd.gini.v1+json

Response

Response

{
   "extractions": {
       "amountToPay": {
           "box": {
               "height": 9.0,
               "left": 516.0,
               "page": 1,
               "top": 588.0,
               "width": 42.0
           },
           "entity": "amount",
           "value": "24.99:EUR",
           "candidates": "amounts"
       }
     },
     "candidates": {
       "amounts": [
         {
             "box": {
                 "height": 9.0,
                 "left": 516.0,
                 "page": 1,
                 "top": 588.0,
                 "width": 42.0
             },
             "entity": "amount",
             "value": "24.99:EUR"
         },
         {
             "box": {
                 "height": 9.0,
                 "left": 241.0,
                 "page": 1,
                 "top": 588.0,
                 "width": 42.0
             },
             "entity": "amount",
             "value": "21.0:EUR"
         }
       ]
       ...
   }
}
Headers
Status Code Description
200 (OK) Success
Header Value
Content-Type application/vnd.gini.v1+json
Body (application/vnd.gini.v1+json)

A detailed explanation of the response format can be found in document_extractions.

Name Type Description
extractions object A mapping of labels to extractions (i.e. specific-extractions)
candidates object A mapping of labels to a list of extraction-candidates

Errors

Status Code Description
404 (Not Found) Response status if the requested entity couldn't be found

Submitting feedback on extractions

Depending on your use case, you should always submit feedback on extractions in order to help to improve the recognition rate of the Gini Accounting API.

Feedback should only be sent if your use case fulfills these constraints. Gini uses several techniques to learn from feedback on extractions automatically. Thereby it is equally important for Gini to receive both feedback on correct and on incorrect extractions. There are currently two ways to submit feedback. The first and most common one is to submit the complete feedback in one request. This is the most obvious way if your frontend (app) shows the extractions on one screen in an editable form. The user can edit the extractions before she confirms that the approvement/correction is complete with a click on a button. The second way covers quite rare use cases where the final approvement signal - e.g. the click on a button - is not possible. Therefore you can send the feedback for one label per request.

There are three different types of feedback:

Please see the full example for further details.

Submitting feedback on multiple extractions

Submitting feedback on multiple extractions


    PUT /documents/{id}/extractions

    POST /documents/{id}/extractions

The Gini Accounting API allows to submit feedback on multiple extractions for a single document with a single request. It is strongly recommended for two reasons that you submit your feedback in this way. On the one hand, the total number of round trips is reduced to one and the feedback is handled internally as a batch. Thus, the update is more efficient for multiple extractions compared to submitting each feedback with a separate request (See singlefeedback). On the other hand, Gini's training techniques can benefit from the feedback on multiple extractions, as Gini can be aware of the fact that the single parts of the submitted feedback belong together.

Request

Example

We show a more elaborated example here in order to explain the different types of feedback. The example scenario is as follows: The user uploads a document where the labels amountToPay, paymentReference, iban were extracted. Unfortunately the label paymentRecipient could not be extracted. The response for the extractions request is as follows:

{
    "candidates": {
    },
    "extractions": {
        "amountToPay": {
            "box": {
                "height": 8.0,
                "left": 545.0,
                "page": 1,
                "top": 586.0,
                "width": 17.0
            },
            "candidates": "amounts",
            "entity": "amount",
            "value": "5.60:EUR"
        },
        "iban": {
            "box": {
                "height": 7.0,
                "left": 447.0,
                "page": 1,
                "top": 746.0,
                "width": 100.0
            },
            "candidates": "ibans",
            "entity": "iban",
            "value": "DE68130300000017850360"
        },
        "paymentReference": {
            "entity": "reference",
            "value": "ReNr 123, KdNr 32"
        }
    }
}

The user adds the missed paymentRecipient value (complementary feedback) and corrects the paymentReference to "ReNr 1735, KdNr 37" (negative feedback). The iban and amountToPay were correct (positive feedback) The document is not shown, so we can leave out the boxes. The resulting feedback request is then as follows:

{
   "feedback": {
       "amountToPay": {
           "value": "5.60:EUR"
       },
       "iban": {
           "value": "DE68130300000017850360",
       },
       "paymentReference": {
           "value": "ReNr 1735, KdNr 37"
       },
       "paymentRecipient": {
           "value": "Zalando SE"
       }
   }
}

Give feedback and correct or verify multiple specific labeled extraction patterns with a single PUT or POST request to the documents extractions URI.

The labels must correspond to the names of the extraction types (e. g. amountToPay. See available-specific-extractions for a list of names).

Headers
Header Value
Content-Type application/vnd.gini.v1+json
Body
Key Type Description
feedback object A mapping of labels to extractions (i.e. specific-extractions)

Response

Status Code Description
204 (No Content) The feedback was successfully processed
404 (Not Found) The document or label could not be found
422 (Unprocessable Entity) At least one value was not valid regarding to the labels entity validation rules

Submitting feedback on single extractions

Request

Submitting feedback to single extraction


    PUT /documents/{id}/extractions/{label}

Example

{
    "box": {
        "height": 14,
        "left": 405,
        "page": 1,
        "top": 421,
        "width": 36
    },
    "value": "new value"
}

Give feedback and correct, verify or add a specific labeled extraction pattern with a PUT request to the documents extractions URI. Please be aware that single extraction feedback should be avoided - its only suitable for very rare use cases.

The label must correspond to the name of the extraction type (e. g. amountToPay. See available-specific-extractions for a list of names).

Headers
Header Value
Content-Type application/vnd.gini.v1+json
Body
Key Type Description
value string New value of extraction
box object (Optional) Bounding box where the extraction can be found

Response

Status Code Description
204 (No Content) The feedback was successfully processed
404 (Not Found) The document or label could not be found
422 (Unprocessable Entity) At least one value was not valid regarding to the labels entity validation rules

Submitting feedback for invalid extractions

Submitting feedback for invalid extractions

    DELETE /documents/{id}/extractions/{label}

Request

In case an extraction was found erroneously (i.e. is not present in the source document), you can delete it by issuing a DELETE request to the extraction URI:

Response

Status Code Description
204 (No Content) Removal of the label was successful
404 (Not Found) Returned when the document or label can not be found

Retrieving a document's pages

Retrieving a document's pages

    GET /documents/{id}/pages

The Gini Accounting API renders preview images of a document's pages. To retrieve the list of pages for a document, issue a GET request to the pages sub-resource of a document.

Request

Path parameters

Retrieve a document's pages

curl -H 'Authorization: BEARER <token>' 
    -X GET -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/pages
Name Value
id Document ID
Headers
Header Value
Accept application/vnd.gini.v1+json

Response

The response is a list of pages.

[
  {
    "images" : {
      "1280x1810" : "https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/pages/1/1280x1810",
      "750x900" : "https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/pages/1/750x900"
    },
    "pageNumber" : 1
  },
  {
    "pageNumber" : 2,
    "images" : {
      "1280x1810" : "https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/pages/2/1280x1810",
      "750x900" : "https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/pages/2/750x900"
    }
  }
]
Headers
Status Code Description
200 (OK) The request was successful.
404 (Not Found) The requested document does not exist.
Body
Name Type Description
pages array All pages<entity-page> in the current result page

A page is an entity with the following fields:

Key Child key Type Description
documentId string UUID of the document to which page belongs
pagenum number Page number
_links object Links to related resources
document string Link to the document to which the page belongs
pages string Link to the pages of the document
_images object Links to pre-rendered page images in different resolutions
image resolution in pixels string Link to a pre-rendered image of the page

Retrieving the layout of a document

The layout of the document describes the textual content of a document with positional information, based on the processed document <retrieving-the-processed-document>.

Coordinate system

The origin of the coordinate system is adjusted to the upper left corner of the page. The coordinate system uses the DTP point as unit: 1 pt = 1 inch / 72 = 25.4 mm / 72 = 0.3528 mm

Request

Retrieving the layout of a document


    GET /documents/{id}/layout

Example

curl -H 'Authorization: BEARER <token>' 
    -X GET -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000/layout

The layout of a document can be retrieved by a GET request to the layout URI:

Headers
Header Value
Accept application/vnd.gini.v1+json

Response

Layout Example

{
  "pages": [
    {
      "number": 1,
      "sizeX": 595.3,
      "sizeY": 841.9,
      "textZones": [
        {
          "paragraphs": [
            {
              "l": 54.0,
              "t": 158.76,
              "w": 190.1,
              "h": 36.55000000000001,
              "lines": [
                {
                  "l": 54.0,
                  "t": 158.76,
                  "w": 190.1,
                  "h": 10.810000000000002,
                  "wds": [
                    {
                      "l": 54.0,
                      "t": 158.76,
                      "w": 18.129999999999995,
                      "h": 9.900000000000006,
                      "fontSize": 9.9,
                      "fontFamily": "Arial-BoldMT",
                      "bold":false,
                      "text": "Ihre"
                    },
                    {
                      "l": 74.86,
                      "t": 158.76,
                      "w": 83.91000000000001,
                      "h": 9.900000000000006,
                      "fontSize": 9.9,
                      "fontFamily": "Arial-BoldMT",
                      "bold":false,
                      "text": "Vorgangsnummer"
                    },
                    {
                      "l": 158.76,
                      "t": 158.76,
                      "w": 3.3000000000000114,
                      "h": 9.900000000000006,
                      "fontSize": 9.9,
                      "fontFamily": "Arial-BoldMT",
                      "bold":false,
                      "text": ":"
                    },
                    [...]
                  ]
                },
                [...]
              ]
            }
          ]
        }
      ],
      "regions": [
        {
          "l": 20.0,
          "t": 240.1,
          "w": 190.0,
          "h": 150.3,
          "type": "RemittanceSlip"
        },
        [...]
      ]
    },
    [...]
  ]
}
Headers
Status Code Description
200 (OK) Success
Header Value
Content-Type application/vnd.gini.v1+json
Body (application/vnd.gini.v1+json)
Key Type Description
pages array Array of page objects
Page Object
Key Type Description
number number Number of the page starting with 1
sizeX number Width of the page
sizeY number Height of the page
textZones array Array of textzone objects
regions array Array of region objects
TextZone Object
Key Type Description
paragraphs array Array of paragraph objects
Paragraph Object
Key Type Description
w number Width of the paragraph
h number Height of the paragraph
t number Distance of the paragraph from the upper edge of the page
l number Distance of the paragraph from the left edge of the page
lines array Array of line objects
Line Object
Key Type Description
w number Width of the line
h number Height of the line
t number Distance of the line from the upper edge of the page
l number Distance of the line from the left edge of the page
wds array Array of word objects
Word Object
Key Type Description
h number Height of the word
w number Width of the word
l number Distance of the word from the left edge of the page
t number Distance of the word from the upper edge of the page
fontSize number Font size of the word in points
fontFamily string Name of the font family of the word
bold boolean Indicates bold font style
text string Text of word
Region Object
Key Type Description
h number Height of the region of interest
w number Width of the region of interest
l number Distance of the region from the left edge of the page
t number Distance of the region from the upper edge of the page
type string Type of the region of interest, e.g. RemittanceSlip

Errors

Status Code Description

404 (Not Found) Returned when the requested layout is invalid

Retrieving the processed document

Request

Retrieve the processed document

    GET /documents/{id}/processed

Before Gini tries to extract information, it preprocesses the document, e.g. to deskew pages. The processed document can be retrieved by a GET request:

Path parameters

Name Value
id Document ID

Response

Headers

Status Code Description
200 (OK) Success

Body

The version of the uploaded document file after preprocessing (i.e. color corrected, deskewed) which has been used for all layout and semantic extractions. In case of native PDF documents identical to the original document file.

Errors

Status Code Description
404 (Not Found) The requested document does not exist.

Deleting documents

Delete documents


    DELETE /documents/{id} 

If you want to delete a document you can do this by doing a DELETE request on the document URI. When the document is deleted all associated resources (extractions, layout) will also be deleted.

Request

Delete request

curl -H 'Authorization: BEARER <token>' 
    -X DELETE -i https://accounting-api.gini.net/documents/c292af40-d06a-11e2-9a2f-000000000000

Documents can be deleted by doing a DELETE request on the document URI.

Response

Headers

Status Code Description
204 (No Content) Success

Errors

Status Code Description
404 (Not Found) Returned when no document can be found under the specific URI

Getting a list of all documents

Get a list of all documents

    GET /documents

To get a list of all documents, issue a GET request on the /documents resource. The response will be a paginated list of all documents.

Request query parameters

Example request

curl -H 'Authorization: BEARER <token>' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -X GET -i https://accounting-api.gini.net/documents?limit=50
Name Type Description
limit number (Optional) Maximum number of documents to return. Defaults to 20.
offset number (Optional) Start offset. Defaults to 0.

Response

Example response

{
  "totalCount": 118,
  "documents": [
    {...},
    {...},
    ...
  ]
}

The response is a paginated list of documents.

Headers
Status Code Description
200 (OK) Success
Body

The response entity has the following fields:

Name Type Description
totalCount number Total number of documents
documents array All documents of the current result page

Document Extractions

Documents are full of information. For instance, invoices contain an amount to pay and additional information such as a bank account and a due date. The Gini Accounting API is able to extract this information and provide it in a structured way. In the following, that extracted information will be referred to as extractions. Examples for extractions are, as already mentioned, amounts and bank accounts, but also addresses, tax numbers, links to websites etc.

Additionally, Gini also maps a semantic property to an extraction. In other words, Gini not only extracts a date from a given document, but also infers that the date is the due date of an invoice. In the following, that will be referred to as a specific extraction.

Extractions

Extraction

{
  "entity": "date",
  "value": "2012-06-20",
  "box": { ... }
}

An extraction contains an entity describing the general semantic type of the extraction (e.g. a date), which also determines the format of the value containing the information as text. Optionally there may be a box describing the position of the extraction value on the document. In most instances, extractions without a bounding box are meta information (e.g. doctype).

Name Type Description
entity string Key (primary identification) of an entity type (e. g. banknumber). See available-extraction-entities for a full list.
value string A normalized textual representation of the Text/Information provided by the extraction value (e. g. bank number without spaces between the digits)
box bounding-box (Optional) bounding box containing the position of the extraction value on the document

Specific extractions

Specific extractions

{ 
  "paymentDueDate": {
      "entity": "date",
      "value": "2012-06-20",
      "box": { ... },
      "candidates": "dates"
  }
}

A specific extraction assigns a semantic property to an extraction. It also has an additional field candidates:

Name Type Description
candidates string (Optional) A reference to a extraction candidates. See available-extraction-candidates for a list.

Available Specific Extractions

Name Description Entity Candidates
amountToPay The amount which has to be paid. amount amounts
bankAccountNumber The account number of a payment recipient. (Deprecated) bankaccount bankAccountNumbers
bankNumber The bank number of a payment recipient. (Deprecated) banknumber bankNumbers
bic The bic of a payment recipient. bic bics
branchId The branch id of a receipt. Note: This extraction is only available if the document is a Receipt. See Document Type Hints for details. text n/a
companyRegisterId The Commercial Registry number of a document sender. companyregisterid companyRegisterIds
customerId The customer Id of a document recipient. customerid customerIds
docType The document type of a given document. doctype n/a
documentDate The document date. date dates
documentTime The document time. Note: This extraction is only available if the document is a Receipt. See Document Type Hints for details. time times
documentDomain The domain of a current document. documentdomain n/a
email The most probable email address of a sender email emails
iban The IBAN of a document sender. iban ibans
invoiceId The invoice Id of a given document. invoiceid invoiceIds
netAmount The net amount of an invoice. amount n/a
paymentDueDate The calculated payment due date (e.g. of an invoice). date dates
paymentMethod The payment method of a receipt. Note: This extraction is only available if the document is a Receipt. See Document Type Hints for details. text n/a
paymentPurpose The extra payment purpose text when the payment reference is not available Note: Currently only available for clients in Austria. text n/a
paymentRecipient The payment recipient, beneficiary of a money transfer activity companyname senderNames
paymentReference The payment reference. reference n/a
paymentState If a document has yet to be paid or is paid already. paymentstate n/a
phoneNumber The first found phoneNumber in a given document. phonenumber phoneNumbers
receiptNumber The number of the receipt. Note that this extraction is only available if the document was uploaded with doctype hint Receipt. See Document Type Hints for details. invoiceid receiptNumbers
recipient The document’s recipient. (Deprecated: use individual recipient subfields) recipient n/a
recipientName The document’s recipient name. text n/a
recipientNameAddition The document’s recipient name addition. text n/a
recipientStreet The document’s recipient street address. street n/a
recipientCity The document’s recipient city. city n/a
recipientPostalCode The document’s recipient postal code. zipcode n/a
recipientPoBox The document’s recipient postal box. poboxnumber n/a
referenceId The first found reference id in a given document. text referenceIds
senderCity The sender city. city n/a
senderName The sender name. companyname senderNames
senderNameAddition The sender name addition. companynameaddition n/a
senderPoBox The sender post-office box. poboxnumber n/a
senderPostalCode The sender’s postal code. zipcode n/a
senderStreet The sender’s street with house number. street n/a
tax0 The amount with tax rate of 0% amount n/a
tax7 The amount with tax rate of 7% amount n/a
tax16 The amount with tax rate of 16% (Deprecated) amount n/a
tax19 The amount with tax rate of 19% amount n/a
taxNumber The tax number of a document sender. taxnumber taxnumbers
templateId (Optional) The template id when the layout of document meets a certain template (available to clients who choose the template option) text n/a
transactionId The transaction id of a receipt when it is paid per card. Note: This extraction is only available if the document is a Receipt. See Document Type Hints for details. text n/a
vatRegNumber The VAT number of a document sender. vat vatRegNumbers
website The most probable web address of a sender. url websites

Extraction Candidates

Extraction Candidates

{ 
    "dates": [
      {"entity": "date","value": "2012-06-20","box": { ... } },
      {"entity": "date","value": "2012-05-10","box": { ... } },
      ...
    ]
}

Extraction candidates are a list of suggestions for an appropriate extraction <extractions>.

Available Extraction Candidates

Name Description Entity
amounts All amounts of a given document. amount
bankAccountNumbers All account numbers of a given document. bankaccount
bankNumbers All bank numbers of a given document. banknumber
bics All bics of a given document. bic
companyRegisterIds All alphanumeric strings (of a similar structure as a German company register id) of a given document. companyregisterid
customerIds All alphanumeric strings (of a similar structure as an identifier) of a given document. customerid
dates All dates of a given document. date
emails All emails of a given document. email
ibans All IBANs of a given document. iban
invoiceIds All alphanumeric strings (of similar structure as an identifier) of a given document. invoiceid
phoneNumbers All phone numbers of a given document. phonenumber
receiptNumbers All potential receipt numbers of a given document. invoiceid
referenceIds All potential reference id numbers of a given document. text
senderNames All possible sender names of a given document. companyname
taxNumbers All strings of digits (of a similar structure as a German tax number) of a given document. taxnumber
times All times of a given document. time
vatRegNumbers All alphanumeric strings (of a similar structure as an identifier) of a given document. vat
websites All links found in a given document. url

Extraction Entities

The available extraction entities are (follow each link for a detailed description):

Bounding Box

Bounding Box

{ 
    "box": {
      "page": 2,
      "left": 483.0,
      "top": 450.0,
      "width": 51.0,
      "height": 9.0
    }
}

A bounding box creates a direct relation between an extraction and a document. The box describes the page and the position where the extraction originates.

Name Type Description
left number The distance from the left edge of the page
top number The distance from the top edge of the page
width number The horizontal dimension of a box
height number The vertical dimension of a box
page number The page on which the box can be found, starting with 1

Coordinate system

The origin of the coordinate system is adjusted to the upper left corner of the page. The coordinate system uses the DTP point as unit: 1 pt = 1 inch / 72 = 25.4 mm / 72 = 0.3528 mm

Entity reference

amount

amount

{
    "entity": "amount",
    "value": "33.78:EUR",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes an amount of money with a specific currency in the format <Amount>:<Currency Code>, where <Amount> is a decimal number with "." as decimal separator and ":" as delimiter between <Amount> and <Currency Code>.

The currency code must be given according to the list specified in ISO 4217.

Format
Name Type Description
entity string Must be amount
value string Amount in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
<Number>:<Currency Code/Symbol> 12.3:EUR; 12,4:USD; 12.98:USD

<Number> <Currency Code/Symbol> (1-space-separation) 12,3 EUR; 12,4 USD; 12 € <Currency Code/Symbol> <Number> (1-space-separation) EUR 12.3; \$ 12.4

bankaccount

bankaccount

{
    "entity": "bankaccount",
    "value": "1597880",
    "box": {
        "page": 1,
        "left": 506.0,
        "top": 777.0,
        "width": 53.0,
        "height": 6.0
    }
}

Describes a bank account number.

Format
Name Type Description
entity string Must be bankaccount
value string Bank account number in the normalized form (without spaces between digits)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
Digits > 1597880

If the string has less than 3 digits, it will be rejected.

banknumber

banknumber

{
    "entity": "banknumber",
    "value": "70250150",
    "box": {
        "page": 1,
        "left": 147.0,
        "top": 427.0,
        "width": 52.0,
        "height": 8.0
    }
}

Describes a bank number.

Format
Name Type Description
entity string Must be banknumber
value string Bank number in the normalized form (without spaces between digits)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
8 digits > 70250150

bic

Describes a BIC number.

bic

{
    "entity": "bic",
    "value": "GENODEF1HH2",
    "box": {
        "page": 1,
        "left": 506.0,
        "top": 777.0,
        "width": 53.0,
        "height": 6.0
    }
}
Format
Name Type Description
entity string Must be bic
value string BIC number in the normalized form (without spaces between digits and letters)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
String matching BIC format GENODEF1HH2

city

city

{
    "entity": "city",
    "value": "München",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes a city.

Format
Name Type Description
entity string Must be city
value string The city name
box bounding-box Bounding box of the occurrence including the page number

companyname

companyname

{
    "entity": "companyname",
    "value": "Weinquelle Lühmann",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes a (sender) company name.

Format
Name Type Description
entity string Must be companyname
value string The company name
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
Random string with at least 2 letter/digit characters O2, BMW, ABC GmbH

A string with single letter/digit character will be rejected.

companynameaddition

companynameaddition

{
    "entity": "companynameaddition",
    "value": "Kundenservice",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes a (sender) company name addition (e.g. Kundenservice).

Format
Name Type Description
entity string Must be companynameaddition
value string The company name addition
box bounding-box Bounding box of the occurrence including the page number

companyregisterid

companyregisterid

{
    "entity": "companyregisterid",
    "value": "HRB:108514:München",
    "box": {
        "page": 1,
        "left": 525.0,
        "top": 805.0,
        "width": 34.0,
        "height": 6.0
    }
}

Describes a German Register number in the format <Area of the Commercial Registry>:<Number>:<Office of the Registry> with ":" as delimiter between components.

Format
Name Type Description
entity string Must be companyregisterid
value string Register number in the defined format
box bounding-box Bounding box of the occurrence including the page number

currency

currency

{
    "entity": "currency",
    "value": "EUR",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes the currency of the document.

The currency code must be given according to the list specified in ISO 4217.

Format
Name Type Description
entity string Must be currency
value string Currency in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example

Euro currency symbol € Euro Currency name/code | EUR, EURO

Since only German documents are supported at the moment, the following string are allowed: €, EUR, EURO

customerid

customerid

{
    "entity": "customerid",
    "value": "M500721563",
    "box": {
        "page": 1,
        "left": 317.0,
        "top": 123.0,
        "width": 158.0,
        "height": 8.0
    }
}

Describes a customer ID.

Format
Name Type Description
entity string Must be customerid
value string Customer ID in the normalized form (without spaces between digits and letters)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
A string with length >= 1 and at least 1 digit 12345, KD678

date

date

{
    "entity": "date",
    "value": "2012-11-16",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 143.0,
        "width": 40.0,
        "height": 8.0
    }
}

Describes a date in the format <Year>-<Month>-<Day> with "-" as delimiter between date components.

Format
Name Type Description
entity string Must be date
value string Date in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
yyyy-mm-dd 2015-10-05
German style date 05.10.2015, 05-10-2015, 05 Okt 2015, 05 Oktober 2015

doctype

doctype

{
    "entity": "doctype",
    "value": "Invoice"
}

Describes a document type as one of the following values:

There are also some other document types that are part of the incubator API. See the documentation about the incubator API for more details. <incubator>

Format
Name Type Description
entity string Must be doctype
value string The document type
Valid Feedback
Form Example
One of the above listed values Invoice, Reminder

documentdomain

documentdomain

{
    "entity": "documentdomain",
    "value": "TeleCommunication"
}

Describes a document domain as one of the following values:

Format
Name Type Description
entity string Must be documentdomain
value string The document domain
Valid Feedback
Form Example
One of the above listed values Travel, HealthInsurance

email

email

{
    "entity": "email",
    "value": "info@t-online.de",
    "box": {
        "page": 1,
        "left": 189.0,
        "top": 820.0,
        "width": 73.0,
        "height": 7.0
    }
}

Describes an email in the format <Name>@<Domain> with "@" as a delimiter between email components.

Format
Name Type Description
entity string Must be email
value string Email in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
Valid email address hello@gini.net

iban

iban

{
    "entity": "iban",
    "value": "DE74700500000000028273",
    "box": {
        "page": 1,
        "left": 425.0,
        "top": 770.0,
        "width": 83.0,
        "height": 6.0
    }
}

Describes an IBAN.

Format
Name Type Description
entity string Must be iban
value string IBAN in the normalized form (without spaces between digits and letters)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
Valid IBAN DE68700202700667302269

Invalid IBAN will be rejected.

invoiceid

invoiceid

{
    "entity": "invoiceid",
    "value": "201210124056",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 133.0,
        "width": 53.0,
        "height": 8.0
    }
}

Describes an invoice ID as identifier.

Format
Name Type Description
entity string Must be invoiceId
value string Invoice ID in the normalized form (without spaces between digits and letters)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
A string with length >= 1 and at least 1 digit 12345, RE 67890

paymentstate

paymentstate

{
    "entity": "paymentState",
    "value": "Paid"
}

Describes a payment state as one of the following values:

Format
Name Type Description
entity string Must be paymentState
value string The payment state
Valid Feedback
Form Example
One of the above listed values Paid, ToBePaid

phonenumber

phonenumber

{
    "entity": "phonenumber",
    "value": "08923508270",
    "box": {
        "page": 1,
        "left": 425.0,
        "top": 770.0,
        "width": 83.0,
        "height": 6.0
    }
}

Describes a phone number in one of two formats <CountryCode> <Number> with " " as a delimiter and <Number> without a country code. All punctuation marks (e.g. "/", "-"), spaces and "(0)" (e.g. +49(0)61957746361) are deleted.

Format
Name Type Description
entity string Must be phonenumber
value string The phone number in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
Phonenumber-like string +49 89 1234 567

Brackets, spaces, leading '+', and '-' are allowed.

poboxnumber

poboxnumber

{
    "entity": "poboxnumber",
    "value": "22087",
    "box": {
        "page": 1,
        "left": 223.0,
        "top": 125.0,
        "width": 16.0,
        "height": 6.0
    }
}

Describes a post-office box.

Format
Name Type Description
entity string Must be poboxnumber
value string The post-office box number
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
4-6 digits 123456
<Keyword> <4-6 digits> Postfach 123456, PF 123456, Brieffach 123456

The keyword can be one of the following: Postfach, PF, Brieffach

recipient

recipient

{
    "entity": "recipient",
    "value": "Max Mustermann Musterstrasse 1 Musterstadt",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the recipient of a letter.

Format
Name Type Description
entity string Must be recipient
value string The recipient
box bounding-box Bounding box of the occurrence including the page number

reference

reference

{
    "entity": "reference",
    "value": "K19218331",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes a payment reference.

Format
Name Type Description
entity string Must be reference
value string The payment reference with ", " as delimiter between reference parts
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
A string with length >= 5 This a reference

A string with less than 5 non-space-letters will be rejected.

street

street

{
    "entity": "street",
    "value": "Emmy-Noether-Straße:2a",
    "box": {
        "page": 1,
        "left": 162.0,
        "top": 125.0,
        "width": 55.0,
        "height": 6.0
    }
}

Describes a street in the format <Street name>:<House number> with ":" as a delimiter between components. All abbreviations (e.g. "str.") are replaced with the German word "Straße".

Format
Name Type Description
entity string Must be street
value string Street in the defined format
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
<Streetname>:<Housenumber> ABC Str:1a
<Streetname> <Housenumber> ABC Straße 1a
<Streetname> (without house number) ABC Straße

taxnumber

taxnumber

{
    "entity": "taxnumber",
    "value": "143/163/4028/9",
    "box": {
        "page": 1,
        "left": 501.0,
        "top": 812.0,
        "width": 58.0,
        "height": 6.0
    }
}

Describes a German tax number in the format <3-5 digits>/<3 digits>/<4 digits>/<1 digit> (or <3-5 digits>/<4 digits>/<3 digits>/<1 digit> for Nordrhein-Westfalen) with "/" as delimiter between components.

Format
Name Type Description
entity string Must be taxnumber
value string Tax number in the defined format
box bounding box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
A string containing 11-13 digits 143/163/4028/9

All kinds of delimiters, that are common for tax numbers, are allowed (e.g. '/', '-'). A string without delimiters is also allowed.

text

text

{
    "entity": "text",
    "value": "Aktenzeichen: K19218331",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Describes a plain text entity.

Format
Name Type Description
entity string Must be text
value string Plain text
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback

Generally Text entity accepts all kinds of Text as feedback. Except for on some specific field, extra rules are applied

Label Form Example
branchId digit sequence 12345, 678901234
transactionId
paymentMethod one of the allowed valid payment methods Cash, Card, Contactless Card, Girocard, Contactless Girocard, Contactless Visa, Contactless Mastercard

time

time

{
    "entity": "time",
    "value": "12:13:14",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 143.0,
        "width": 40.0,
        "height": 8.0
    }
}

Describes a time in the format <hour>:<minute>:<second> with ":" as delimiter between time components.

Format
Name Type Description
entity string Must be time
value string Time in the defined format
box bounding-box Bounding box of the occurrence including the page number

url

url

{
    "entity": "url",
    "value": "www.m-net.de",
    "box": {
        "page": 1,
        "left": 444.0,
        "top": 553.0,
        "width": 50.0,
        "height": 8.0
    }
}

Describes the host part of an URI as defined in 3986. http:// is implicitly assumed as URI scheme.

Format
Name Type Description
entity string Must be url
value string The host part of a URI
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
A valid url string www.gini.net

vat

vat

{
    "entity": "vat",
    "value": "DE188796931",
    "box": {
        "page": 1,
        "left": 453.0,
        "top": 812.0,
        "width": 43.0,
        "height": 6.0
    }
}

Describes a EU VAT number.

Format
Name Type Description
entity string Must be vat
value string European Union VAT number in normalized form (without spaces between the digits and letters)
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
VAT string in valid form DE188796931

Currently only VAT for 'DE' 'GB' 'FR' 'AT' allowed.

zipcode

zipcode

{
    "entity": "zipCode",
    "value": "18337",
    "box": {
        "page": 1,
        "left": 62.0,
        "top": 25.0,
        "width": 55.0,
        "height": 6.0
    }
}

Describes a ZIP code.

Format
Name Type Description
entity string Must be zipCode
value string The ZIP code
box bounding-box Bounding box of the occurrence including the page number
Valid Feedback
Form Example
4-5 digits 80809

Incubator

The incubator Gini Accounting API is unstable and subject of change. It allows early access to immature features which are still in research or under development.

Incubating Extractions

This kind of features are not accessible via the v1 version of the Gini Accounting API. They are only accessible by submitting the incubator version header and/or special parameters.

Accessing Incubating Extractions

Accessing Incubating Extractions

curl -H 'Authorization: BEARER <token>' 
    -H 'Accept: application/vnd.gini.incubator+json' 
    -i https://accounting-api.gini.net/documents/<documentId>/extractions

The incubating extractions are accessible by submitting the incubator custom media type Access header. See the example below:

Receipt Extraction

Submit as receipt
The document type hint parameter must be set to Receipt when submitting-documents. See the example below:

curl -H 'Authorization: BEARER <token>' 
    --data-binary '@file.pdf' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents?filename=file.pdf&doctype=Receipt

Receipts are printed acknowledgements that a specified article or payment has been received. They are often printed in stores with cash registers and include information like price, tax, discount and the purchased items or services.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountToPay The amount which was paid. amount n/a n/a
docType The document type of a given document. doctype n/a Receipt
documentDate The document date. date dates n/a
documentTime The document time. time times n/a
email The email of the seller. email emails n/a
netAmount The net amount on the receipt. amount netAmounts n/a
phoneNumber The phone number of the seller. phonenumber phoneNumbers n/a
receiptNumber The number of the receipt. invoiceid receiptNumbers n/a
senderName The name of the seller. companyname senderNames n/a
senderNameAddition The name of the branch of the seller. companynameaddition n/a n/a
senderStreet The street and house number of the seller. street n/a n/a
senderPostalCode The zip code of the seller. zipcode n/a n/a
senderCity The city of the seller. city n/a n/a
taxNumber The tax number of the seller. taxnumber taxNumbers n/a
vatRegNumber The vat identification number of the seller. vat vatRegNumbers n/a
website The website of the seller. url websites n/a

Fuel Receipt Extraction

Submit as Fuel Receipt

The document type hint parameter must be set to FuelReceipt when submitting-documents. See the example below:

curl -H 'Authorization: BEARER <token>' 
    --data-binary '@file.pdf' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents?filename=file.pdf&doctype=FuelReceipt

Fuel receipts are a special kind of receipts for purchasing gasoline in a gas station.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountLiters The amount of gasoline purchased. volume n/a n/a
amountToPay The amount which was paid. amount n/a n/a
docType The document type of a given document. doctype n/a FuelReceipt
pricePerLiter The price per liter of gasoline. fuelprice pricePerLiters n/a

Access

Furthermore, the Accept header must be set to the incubator custom media type if you access the extractions. See accessing-incubating-extractions

These extractions are printed on invoices and are needed for proper accounting.

Supported Specific Extractions

Name Description Entity Candidates Special Values
netAmount The net amount of an invoice. amount n/a n/a
tax0 The amount with tax rate of 0% amount n/a n/a
tax7 The amount with tax rate of 7% amount n/a n/a
tax16 The amount with tax rate of 16% amount n/a n/a
tax19 The amount with tax rate of 19% amount n/a n/a

Access

The Accept header must be set to the incubator custom media type if you access the extractions. See accessing-incubating-extractions

Subject Extraction

This extraction captures the subject line of a letter.

Supported Specific Extractions

Name Description Entity Candidates Special Values
subject The subject line of a letter. subject n/a n/a

Access

The Accept header must be set to the incubator custom media type if you access the extractions. See accessing-incubating-extractions

Recipient Extraction

This extraction captures the recipient of a letter.

Supported Specific Extractions

Name Description Entity Candidates Special Values
recipient The recipient of a letter. recipient n/a n/a

Access

The Accept header must be set to the incubator custom media type if you access the extractions. See accessing-incubating-extractions

Energy Statement Extractions

Submit as Energy Bill

The document type hint parameter must be set to Energy when submitting-documents. See the example below:

curl -H 'Authorization: BEARER <token>' 
    --data-binary '@file.pdf' 
    -H 'Accept: application/vnd.gini.v1+json' 
    -i https://accounting-api.gini.net/documents?filename=file.pdf&doctype=Energy

An energy statement is a document sent by an energy provider to their client which lists the energy consumption over a certain time period together with the charges.

Supported Specific Extractions

Name Description Entity Candidates Special Values
amountToPay The amount which has to be paid amount n/a n/a
billingAmount The amount which was charged. amount n/a n/a
consumption The amount of energy which was consumed. energyconsumption consumptions n/a
consumptionDuration The time period of the charged consumption. timeperiod n/a n/a
counterNumber The number of the counter which measured the consumption. counternumber counterNumbers n/a
customerPostalCode The postal code of the client. postalcode n/a n/a
docType The document type of a given document. doctype n/a Energy
energyType The type of energy being charged. energytype n/a Electricity, Gas
paidAmount The amount which was already paid. amount n/a n/a
refundAmount The amount which will be refunded. amount n/a n/a

Access

Furthermore, the Accept header must be set to the incubator custom media type if you access the extractions. See accessing-incubating-extractions

Incubating Entities

volume

volume

{
    "entity": "volume",
    "value": "63.56:l",
    "box": {
        "top": 210.0,
        "left": 199.0,
        "width": 43.0,
        "height": 7.0,
        "page": 1
    }
}

Describes a volume (e.g. of gasoline) with a specific unit (e.g. liter) in the format <Volume>:<Unit>, where <Volume> is a decimal number with "." as decimal separator and ":" as delimiter between <Volume> and <Unit>.

Format
Name Type Description
entity string Must be volume
value string Volume in the defined format
box bounding-box Bounding box of the occurrence including the page number

fuelprice

fuelprice

{
    "entity": "fuelprice",
    "value": "1.439:EUR",
    "box": {
        "top": 210.0,
        "left": 257.0,
        "width": 53.0,
        "height": 8.0,
        "page": 1
    }
}

Describes a price per liter (e.g. of gasoline) with a specific currency (e.g. EUR) in the format <Fuelprice>:<Currency>, where <Fuelprice> is a decimal number with "." as decimal separator and ":" as delimiter between <Fuelprice> and <Currency>.

Format
Name Type Description
entity string Must be fuelprice
value string Fuelprice in the defined format
box bounding-box Bounding box of the occurrence including the page number

subject

subject

{
    "entity": "subject",
    "value": "Thema Unser Vorteilsangebot. Ihre Fahrfreude.",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the subject line of a letter.

Format
Name Type Description
entity string Must be subject
value string The subject
box bounding-box Bounding box of the occurrence including the page number

recipient

recipient

{
    "entity": "recipient",
    "value": "Max Mustermann Musterstrasse 1 Musterstadt",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the recipient of a letter.

Format
Name Type Description
entity string Must be recipient
value string The recipient
box bounding-box Bounding box of the occurrence including the page number

counternumber

counternumber

{
    "entity": "counternumber",
    "value": "220666",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the number of a counter which measures energy consumption.

Format
Name Type Description
entity string Must be counternumber
value string The counter number.
box bounding-box Bounding box of the occurrence including the page number

energyconsumption

energyconsumption

{
    "entity": "energyconsumption",
    "value": "176.00:kWh",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the amount of consumed energy. The format is <amount>:<unit> where <unit> is always kWh.

Format
Name Type Description
entity string Must be energyconsumption
value string The energy consumption in the defined format.
box bounding-box Bounding box of the occurrence including the page number

energytype

energytype

{
    "entity": "energytype",
    "value": "Gas",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents the type of energy beeing charged. The possible types are Electricity or Gas.

Format
Name Type Description
entity string Must be energytype
value string Electricity or Gas
box bounding-box Bounding box of the occurrence including the page number

postalcode

postalcode

{
    "entity": "postalcode",
    "value": "DE:81379:Munich",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents a postal code. The format is <countrycode>:<zipcode>:<city>.

Format
Name Type Description
entity string Must be postalcode
value string The postalcode in the defined format.
box bounding-box Bounding box of the occurrence including the page number

timeperiod

timeperiod

{
    "entity": "timeperiod",
    "value": "30:day",
    "box": {
        "top": 379.0,
        "left": 68.0,
        "width": 244.0,
        "height": 10.0,
        "page": 1
    }
}

Represents a time period. The format is <number of days>:day.

Format
Name Type Description
entity string Must be timeperiod
value string The timeperiod in the defined format.
box bounding-box Bounding box of the occurrence including the page number

time

time

{
    "entity": "time",
    "value": "12:13:14",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 143.0,
        "width": 40.0,
        "height": 8.0
    }
}

Describes a time in the format <hour>:<minute>:<second> with ":" as delimiter between time components.

Format
Name Type Description
entity string Must be time
value string Time in the defined format
box bounding-box Bounding box of the occurrence including the page number

User Center API

Gini's User Center offers an API, e.g. to programmatically create new Gini accounts and to make API requests on behalf of a created user.

Client Authentication

All access to the User Center API requires client authentication. A client can authenticate itself with the Client Credentials Grant described in 6749. In short, the client exchanges its client ID and client secret for an access token.

Request

To get a client access token

curl -v -H 'Accept: application/json' 
    -u 'client-id:secret' 
    'https://user.gini.net/oauth/token?grant_type=client_credentials'
GET /oauth/token?grant_type=client_credentials HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json

Example response

{ 
  "access_token":"74c1e7fe-e464-451f-a6eb-8f0998c46ff6","token_type":"bearer","expires_in":3599
}

To get a client access token, do a GET request to /oauth/token?grant_type=client_credentials. The request must contain a HTTP basic access authorization header, with the client ID as username and the client secret as password.

The client can now use the returned access token to make requests to the User Center API, by sending the token as a bearer token in the Authorization request header:

GET /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Authenticating on behalf of a user

Authenticating on behalf of a user

curl -v -X POST --data-urlencode 
    'username=some_user@example.com' 
    --data-urlencode 'password=supersecret' 
    -H 'Content-Type: application/x-www-form-urlencoded' 
    -H 'Accept: application/json' 
    -u 'client-id:secret' 'https://user.gini.net/oauth/token?grant_type=password'
POST /oauth/token?grant_type=password HTTP/1.1
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: user.gini.net
Accept: application/json
Content-Type: application/x-www-form-urlencoded

username=some_user@example.com&password=supersecret

Example response

{ 
  "access_token":"6c470ffa-abf1-41aa-b866-cd3be0ee84f4",
  "token_type":"bearer",
  "expires_in":3599
}

The returned access token can now be used to make requests to the Gini Accounting API on behalf of the user. To do so, send the access token as a bearer token in the Authorization request header:

GET /documents HTTP/1.1
Host: accounting-api.gini.net
Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4
Accept: application/vnd.gini.v1+json
Connection: close

The Resource Owner Password Credentials Grant can be used to exchange a user's email address and password with an access token. The access token can then be used to make requests to the Gini API on behalf of the user.

Request
Key Description
username The user's email address.
password The user's password.

Note that the client must authenticate itself using HTTP basic access authentication with its ID as username and its secret as password.

Creating a new user

Creating a new user

curl -v -X POST --data '{"email":"some_user@example.com", "password":"supersecret"}' 
    -H 'Content-Type: application/json' 
    -H 'Accept: application/json' 
    -H 'Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6' 
    'https://user.gini.net/api/users'
POST /api/users HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

{"email":"some_user@example.com","password:"supersecret"}

Example response

HTTP/1.1 201 Created
Location: https://user.gini.net/api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e
Content-Length: 0

To create a new user, submit a POST request to /api/users.

Request
Key Description
email The new user's email address (will be used as login username)
password The new user's password. Must be at least 6 characters long.

If the request entity was considered invalid (missing fields, password less than 6 chars etc.) or a user with that email address already exists, the API responds with 400 Bad Request.

Retrieving user information

Retrieving user information

GET /api/users/88a28076-18e8-4275-b39c-eaacc240d406 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Accept: application/json

Response

{
  "id":"88a28076-18e8-4275-b39c-eaacc240d406",
  "email":"some_user@example.com"
}

Information about a user can be retrieved with a GET request on /api/users/{userId}

Response
Key Description
id Unique User ID.
email The user's email address.

Changing a user's password and/or email

Changing a user's password and/or email

PUT /api/users/c1e60c6b-a0a4-4d80-81eb-c1c6de729a0e HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

with

{"oldPassword":"supersecret","password:"anothersecret"}

or

{"oldEmail":"old@email.com","email:"my.new@email.com"}

or

{
 "oldPassword":"supersecret", 
 "password":"anothersecret",
 "oldEmail":"old@email.com",
 "email":"my.new@email.com"}

A user's password and/or email can be changed with a PUT request to /api/users/{userId}. To update a user's password and/or email, the current password/email must be provided.

Request
Key Description

oldPassword The user's current password. password | The password to which the user's password should be changed to. oldEmail | The user's current email. email | The email to which the user's email should be changed to.

Deleting a user

Deleting a user

DELETE /api/users/16aecc72-8032-4df6-9686-eaf4ec9532b8 HTTP/1.1
Host: user.gini.net
Authorization: BEARER 74c1e7fe-e464-451f-a6eb-8f0998c46ff6
Content-Type: application/json

An existing user can be deleted with a DELETE request to /api/users/{userId}. This also deletes all data associated with that user (e.g. access tokens, documents and extractions).

Troubleshooting

If you have trouble using the Gini Accounting API and you need to contact the support, there are some information you should always provide in order to help you quickly and efficiently.

X-Request-Id

The request id is generated for every request against the Gini Accounting API and tracked through the whole system. It is included in every response you receive from the Gini Accounting API as the HTTP header X-Request-Id. Please refer to it when you contact our support.

Document Id

The document id is generated for every accepted upload. It is included in the Location HTTP header which is part of the response for a successful upload. Please refer to the document id if you have questions related to a specific document upload.