| Page Properties | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||
|
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
.
| Info |
|---|
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 need have 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.
| Note |
|---|
Your Keep confidential your client secret must be kept confidential. Do not share the client secret with anyone (e.g. keeping . 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 a 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 (don't forget . Make sure 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).
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 correspoinding corresponding Gini API version number. For example, for our first document, we will use the Gini Pay API version v1. The command on the right will send sends a request against the corresponding version of the API.
If the file was is accepted by the Gini Pay API (i.e. 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, 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.
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) as well as , and 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€.
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 futher further in reports and is included into a self-learning mechanism of the Gini extraction system.