How to Process Documents

In order to process your first document with Gini Pay API, perform the following steps.

The usage examples are executed with cURL, a command-line tool to perform HTTP requests.

1 1. Register your application
2 2. Obtain an access token
3 3. Upload a document
4 4. Check the document status information
5 5. Retrieve the extractions
6 6. Prepare and submit payment summary

1. Register your application

Before you can use 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 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 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. 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.

//obtain an access token from an untrusted device (eg. smartphone)

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 JSON response will look similar to

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

//obtain an access token from a trusted device (eg. backend / gateway)

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

POST https://pay-api.gini.net/login
Authorization: Basic Y2xpZW50LWlkOnNlY3JldA==
Host: pay-api.gini.net
Accept: application/vnd.gini.v1+json

//example response
{
  "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 Gini Pay API are made on behalf of the user authorized by the access token. 
//For now, let's assume that you've already created an anonymous user. 
//If not, for the details on how to do so please read Direct Communication from Client Devices to Gini Pay API.

If your client is configured, you will also receive a refresh token in the token api response. By providing the received refresh token, you can get a new access token by calling token endpoint with refresh_token grant_type.

// Getting access token by providing refresh token

curl -v -X POST  --data-urlencode 'grant_type=refresh_token'\
    --data-urlencode 'refresh_token=<refresh_token_received_from_token_api>' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Accept: application/json' \
    -u "client-id:client-secret" \
    'https://user.gini.net/oauth/token'

3. Upload a document

Now that you have the access token, you can upload your first document by sending an API request. The request should contain the corresponding Gini API version number. For example, for our first document, we use Gini Pay API version v1. The command sends a request against the corresponding version of the API.

If the file is accepted by 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.

//upload a document

curl -v -X POST --data-binary '@/path/to/your/document.pdf'
     -H 'Accept: application/vnd.gini.v1+json'
     -H 'Content-Type: application/pdf'
     -H 'Authorization: BEARER 6c470ffa-abf1-41aa-b866-cd3be0ee84f4'
     'https://pay-api.gini.net/documents'
     
//the response (in case the document was Accepted)

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

4. Check the 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 the extractions

The document extractions represent various document contents that the extraction system is able to understand and retrieve. In order to get all the extractions, send a request.

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) 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. Prepare and submit payment summary

A payment summary is an API request containing the correct extractions that you 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 for us and important for you because there is no other way to know in real-time whether the extraction system is delivering the best possible quality for your application.

In order to inform the system whether the extraction is 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 in a self-learning mechanism of the Gini extraction system.