In order to process your first document with the Gini Pay API, perform the following steps.
The usage examples on the right are executed with cURL, a command-line tool to perform HTTP requests.
1. Register your application
Before you can use the Gini Pay API in your application, make sure you have a valid client ID and a client secret. If you don't have the client ID and the client secret already, contact your sales representative.
Keep confidential your client secret. Don't share it with anyone and don’t keep it in a public repository.
2. Obtain access token
The access token is only needed if you want to create a token from a trusted device (backend) and use it from an 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. Make sure to replace:
random@example.org with your username,
geheim with your password,
client-id with your client ID,
client-secret with your client secret.
3. Upload document
Now that you have the access token, you can upload your first document by sending an API request. The request must contain the corresponding Gini API version number. For example, for our first document, we use the Gini Pay API version v1. The command on the right sends a request against the corresponding version of the API.
If the file is accepted by the Gini Pay API (that is 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.
4. Check document status information
The document processing takes a bit of time and, in order to get the extractions, 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.
5. Retrieve 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), and candidates (a list of values for some semantic property).
The example response (shortened, on the right) is an invoice issued by Deutsche Post AG. The receiver of the invoice has to pay 12€ (see amountToPay). It contains one line item with article number 10101, a tax rate 19%, and an amount 12€.
6. 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 to know in realtime whether the extraction system is delivering the best possible quality for your application.
In order to inform the system whether 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 further in reports and is included into a self-learning mechanism of the Gini extraction system.