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.

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:

Managing anonymous Gini accounts

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

• Users might have individual opinions on the type of documents or the correctness of certain values
• To evaluate the correctness of feedback: the more users that submit the same value, the more correct it likely is.

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:

• trusted

  Your application communicates with the Gini Accounting API via a common backend that runs on a trusted device. Each request states for which user a request is made using a user identifier devised by your application. No account management is required.

• untrusted

  On first usage of the Gini Accounting API, your application creates an anomyous Gini user in the background and uses those account credentials for subsequent requests. This works best for (mobile) applications where the app communicates directly with the Gini Accounting API on an untrusted device.

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:

• Each user's identifier has to be unique
• Once determined for a user, the identifier must remain the same

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 file size must be less than 10 MiB.
• PDF files must not have any security restrictions such as password protection.
• Scanned documents should have a resolution of at least 300dpi in order for the OCR to return optimal results.
• Plain text documents have to be encoded in UTF-8. The source size must be smaller than 512 KiB.
• Only the first 10 pages of a document are processed.
• Only contents of documents in German language are sufficiently well recognized.

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

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:

Body

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

Response

Headers

Errors

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

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

Body (application/vnd.gini.v1+json)

Errors

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

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

Body (application/vnd.gini.v1+json)

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

Errors

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:

• positive feedback: The happy path - the extraction was correct and confirmed by the user
• complementary feedback: The Gini Accounting API extracted nothing, the given label is not in the response and the user entered the correct value
• negative feedback: The extraction was incomplete / erroneous and corrected by the user

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

Body

Response

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

Body

Response

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

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

Headers

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

Body

A page is an entity with the following fields:

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

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

Body (application/vnd.gini.v1+json)

Page Object

TextZone Object

Paragraph Object

Line Object

Word Object

Region Object

Errors

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

Response

Headers

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

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

Errors

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

Response

Example response

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

The response is a paginated list of documents.

Headers

Body

The response entity has the following fields:

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).

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:

Available Specific Extractions

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

Extraction Entities

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

• amount
• bankaccount
• banknumber
• bic
• city
• companyname
• companynameaddition
• companyregisterid
• currency
• customerid
• date
• doctype
• documentdomain
• email
• iban
• invoiceid
• paymentstate
• phonenumber
• poboxnumber
• recipient
• reference
• street
• taxnumber
• text
• time
• url
• vat
• zipcode

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.

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

Valid Feedback

<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

• If there is no <Number> in the string, it will be rejected.
• If there is no <Currency Code/Symbol>, it will be treated as default 'EUR' (default currency code).

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

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

Valid Feedback

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

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

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

doctype

doctype

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

Describes a document type as one of the following values:

• BankStatement
• Contract
• Invoice
• Receipt
• Reminder
• RemittanceSlip
• TravelExpenseReport
• Other

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

Valid Feedback

documentdomain

documentdomain

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

Describes a document domain as one of the following values:

• TeleCommunication
• Other
• HealthInsurance
• Energy
• Travel

Format

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

paymentstate

paymentstate

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

Describes a payment state as one of the following values:

• Paid
• ToBePaid

Format

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

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

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

Valid Feedback

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

Valid Feedback

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

Valid Feedback

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

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

Access

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

Accounting Related Extractions

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

Supported Specific Extractions

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

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

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

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

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

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

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

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

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

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

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

timeperiod

timeperiod

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