Submit Files

In order to extract document information, the document source file should be first submitted to Gini.

Submit documents by sending a POST request to the /documents resource path. After successful submission, the location of the new document is returned in the Location header.

The Gini Pay API currently supports two different variants of uploads, one optimized for web applications running in a web browser and the other for all other types of clients. The first variant optimized for web applications expects the documents to be uploaded using a multipart/form-data encoding method. The second variant for all other clients simply uses the request body (independent of the request Content-Type) as the document.

//documents can be submitted by doing a POST request to the /documents resource.

    POST /documents

Supported file formats

Gini supports PDF files, GIF files (non-animated), PNG files, JPEG files, TIFF files as well as plain text formats (including parsed QR codes). You can use native documents (PDF only) and scanned documents (all other supported formats).

Note that there are certain limitations:

• 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 300 dpi in order for the OCR to return optimal results

• plain text documents have to be encoded in UTF-8 and the source size must be smaller than 512 KiB

• only the first 10 pages of a document are processed

• only document contents in German are recognized sufficiently well

The above applies both to single-page documents and to each page in multipage documents.

Document uploading schemes

The Gini API enables you to upload a document as a single file or page by page, in parts.

Upload a single file document

This is the standard way of uploading a document to the Gini extraction system. A PDF document can contain single or multiple pages. JPEG and PNG documents are also accepted. When uploaded, the document is processed by the system normally and without any adjustments regarding its structure.

Request

Headers

The x-document-metadata-* headers are used to add some meta information to the upload. This information is used in analytics and reporting.

• branchid is used to group uploads from a specific client, for example, branches for banks

• deviceclass specifies from which kind of device the upload comes, for example, if it was uploaded from a desktop computer or a smartphone

Requesting query parameters

If the upload is performed without 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

//upload a document

variant for web applications running in a web browser with access token:

curl -H 'Authorization: BEARER <token>'
    --form 'file=@file.pdf'
    -H 'Accept: application/vnd.gini.v1+json'
    -i https://pay-api.gini.net/documents
variant for all other types of applications:

curl -H 'Authorization: BEARER <token>'
    --data-binary '@file.pdf'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/pdf'
    -i https://pay-api.gini.net/documents?filename=file.pdf
or with X-User-identifier (see how to setup X-User-identifier):

curl -H 'X-User-Identifier: user1'
    --form 'file=@file.pdf'
    -H 'Accept: application/vnd.gini.v1+json'
    -u 'client-id:client-secret'
    -i https://pay-api.gini.net/documents

Upload a document page by page

Partial upload should be performed in two steps: partial document upload and composite document upload.

Step 1 (upload each page as a partial document)

Pages that are part of the document are referred to as partial documents. If you want to upload a page (or a page picture) that belongs to the document, your request header should additionally include Content-Type field with application/vnd.gini.v1.partial+png value or application/vnd.gini.v1.partial+pdf in case of PDF page. See the examples below.

In case you want to submit a parsed QR code, please use application/vnd.gini.v1.partial+qr+json. The parsing of the QR fields is optional. The paymentdata needs to contain at least the iban and the paymentRecipient keys. Hence, the minimal valid QR code body could be the following:

{
  "qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65&currency=EUR",
  "paymentdata": {
    "iban": "DE01234567898765432101",
    "paymentRecipient": "Telekom GmbH"
  }
}

Mandatory QR fields

Optional QR fields

See the complete QR request example below.

Request

In order to upload a page picture or a partial document, specify a different content type:

Headers

The x-document-metadata-* headers can be used to add some meta information to the upload. This information is used in analytics and reporting.

• branchid is used to group uploads from a specific client (e.g. branches for banks)

• deviceclass specifies from which kind of device the upload comes from. E.g. if it was uploaded from a desktop computer or a smartphone.

Request query parameters

Body

File contents of the document.

Response

Headers

Errors

//upload a partial document

//variant for web applications running in a web browser with access token:

curl -H 'Authorization: BEARER <token>'
    --form 'file=@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents
    
//variant for other types of applications with access token:

curl -H 'Authorization: BEARER <token>'
    --data-binary '@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents?filename=file.JPEG

//or with X-User-identifier (see how to setup X-User-identifier):

curl -H 'X-User-Identifier: user1'
    --form 'file=@file.JPEG'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -u 'client-id:client-secret'
    -i https://pay-api.gini.net/documents
    
// variant for QR code 
curl -H 'Authorization: BEARER <token>'
    --form 'data.json={
        "qrcode": "bank://singlepaymentsepa?name=Gini%20Online%20Shop&reason=A12345-6789&iban=DE89370400440532013000&bic=GINIBICXXX&amount=47%2C65&currency=EUR",
          "paymentdata": {
            "amountToPay": "25.79:EUR",
            "paymentRecipient": "Telekom GmbH",
            "iban": "DE01234567898765432101",
            "bic": "SPESDE3EXXX",
            "paymentReference": "Nr.12345"
          }
      }'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.partial+png'
    -i https://pay-api.gini.net/documents

Step 2 (upload JSON as a composite document)

After successfully uploading all pages as partial documents, announce their locations to the extraction system by uploading a composite document, which is a simple JSON file with corresponding locations of partial documents.

Request

In order to upload a composite document that aggregates one or multiple partial documents, specify a different content type.

Headers

Request query parameters

If the upload is performed without multipart/form-data, you can optionally provide a file name for the submitted document with a query parameter:

Body

Raw bytes of the composite JSON.

Response

Headers

Errors

//upload a composite document

//variant for web applications running in a web browser with access token:

curl -H 'Authorization: BEARER <token>'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.composite+json'
    -X POST -d'{...}'
    -i https://pay-api.gini.net/documents
//or

curl -H 'Authorization: BEARER <token>'
    --data-binary '@data.json'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.composite+json'
    -i https://pay-api.gini.net/documents
//or with X-User-identifier (see how to setup X-User-identifier):

curl -H 'X-User-Identifier: user1'
    -H 'Accept: application/vnd.gini.v1+json'
    -H 'Content-Type: application/vnd.gini.v1.composite+json'
    -u 'client-id:client-secret'
    -X POST - d'{...}'
    -i https://pay-api.gini.net/documents
    
//with post body of

{
  "partialDocuments": [
    {
      "rotationDelta": 0,
      "document": "localtion of parital doc 1"
    },
    {
      "rotationDelta": 0,
      "document": "location of partial doc 2"
    },
    ...
  ]
}

//location in form of https://pay-api.gini.net/documents/e8606210-56ed-11ea-b823-b351b84ae4b3