In order to process your first document with the Gini Pay API, you will have to perform the following easy steps:
Register your application
Obtain an access token
Upload a document
Check the document status information
Retrieve the extractions
Send feedback
The usage examples are executed with cURL, a command-line tool to perform HTTP requests.
Register Your Application
Before you can use the Gini Pay API in your application, you need a valid client ID and a client secret. If you don't have the client ID and the client secret already, please contact your sales representative.
Your client secret must be kept confidential. Do not share the client secret with anyone (e.g. keeping it in a public repository).
Obtain an Access Token
The access token is only needed if you want to create a token from a trusted device (backend) and use it from a untrusted device (smartphone). The anonymous user is created automatically for each user identified by the X-User-Identifier header.
In order to get an access token for the Gini account, run the example command on the right (don't forget to replace random@example.org with your username and geheim with your password as well as client-id with your client ID and client-secret with your client secret).
Upload a Document
Now that you have the access token, you can upload your first document by sending an API request. The request must contain the correspoinding Gini API version number. For example for our first document, we will use Gini Pay API version v1. The command on the right will send a request against the corresponding version of the API.
If the file was accepted by the Gini Pay API (i.e. its file format is supported), the extraction system automatically starts to process the document and responses with the HTTP status code 201 as well as the document location URL.
Check the Document Status Information
The document processing takes a bit of time and in order to get the extractions, you need to check the status of the processed document periodically. The status can have the value PENDING, which means that the document is being analyzed, and COMPLETED, which means that the document analysis is complete and the extractions are ready for retrieval. Check the current document status by sending a GET request to the URL that you received when the document was uploaded. Once the status changes to COMPLETED, the extractions are ready and you can retrieve them.
Retrieve the Extractions
The document extractions represent various document contents that the extraction system was able to understand and retrieve. In order to get all the extractions, send a request to the right (notice the API version v1).
The returned object contains specific extractions (a value with some specific semantic property), compound extractions (a group of values with some specific semantic property) as well as candidates (a list of values for some semantic property).
The example response (shortened, on the right) is an invoice (see docType) issued by Deutsche Post AG. The receiver of the invoice has to pay 12€ (see amountToPay). It contains one line item (see lineItem) with an article number 10101, a tax rate 19% and an amount 12€.
Send Feedback and Get Even Better Extractions Next Time
Feedback is an API request containing the correct extractions that you can send us in order to improve the future extraction accuracy of the system. In fact your application should always send at least some feedback. The more complete and qualitative the feedback is, the sooner the extraction system learns what is correct and what's not. Feedback is critical to us and important to you because there is no other way for us know in realtime whether the extraction system is delivering the best possible quality for your application.
In order to inform the system the extraction was correct or incorrect, send back the correct value in the feedback request. It is important that it should be the value exactly as it appears on the actual document (not calculated or inferred). Once the feedback is received it gets compared to the extracted value and the result is used futher in reports and is included into a self-learning mechanism of the Gini extraction system.