Page Comparison

...

Table of Contents

minLevel	1
maxLevel	4
outline	false
type	list
printable	false

Feedback Transfer Summary is approved or corrected extraction values that are submitted by you back your application to the extraction system.

You should always submit the feedback on extractions. The feedback that is correctly submitted lets Gini summary to be able to measure the extraction quality in order to and let Gini know whether the extracted information is correct. This way we can provide the best possible user experience . Moreover, since it also helps us continuously improve the extraction system and perform valuable data analytics for you.

Info
The feedback transfer summary should only be sent if real users see, approve, correct, and complement the extraction-based data.

Gini employs various machine learning techniques in order to learn from feedback the transfer summary automatically. Therefore, it is equally important for Gini to receive the summary both feedback on correct and incorrect extractions.

...

Ways of submitting

...

the transfer summary

There are currently two ways to submit the feedbacksummary.

The first and the most common one is to submit the complete feedback summary in one request. This is the easiest way if your frontend (application) displays the extractions on a screen in an editable form. A user can modify the extractions before pressing the confirmation button.

The second (rarely used) way is where the final approvement approval signal (button click) is not possible. In such case, send the feedback summary on one label per request.

Types of

...

There are three different types of feedback:

...

transfer summaries

positive summary (preferred): the extraction was correct and confirmed by the user without modification.
complementary feedback
Anchor
positive
positive
complementary summary: the extraction system extracted nothing, for example, the response doesn't contain the requested label. The user manually entered the correct value.
Anchor
complementary
complementary
negative feedbacksummary: the extraction was incomplete or erroneous. The user manually corrected the extraction.
Anchor
negative
negative
informative feedbacksummary: the extraction was changed for another reason, for example, if a line item is returned, the quantity extraction gets feedback summary "0" and a return reason.

...

The Gini Pay API lets you submit feedback transfer summary on multiple extractions for a single document with a single request. It is strongly recommended that you submit your feedback the summary in this way for two reasons. On the one hand, the total number of round trips is reduced to one and the feedback summary is handled internally as a batch. Therefore, the update is more efficient for multiple extractions compared to submitting the feedback summary with each separate request. On the other hand, Gini's machine learning training techniques can benefit from the feedback summary on multiple extractions, since Gini is aware of the fact that single parts of the submitted feedback summary belong together.

Info
Send feedback transfer summary only on those labels that are physically seen by the user. Unseen labels except Return Assistant (RA) specific “amountsAreConsistent” should be filtered out.

Code Block

language	json

//submitting transfer feedbacksummary on extractions


    PUT /documents/{id}/extractions/feedback

Note
IMPORTANT! In REST requests, the transfer summary is called feedback. Hence, in the examples below, “feedback” is transfer summary.

Request

Headers

Header	Value
`Content-Type`	`application/vnd.gini.v1+json`

Body

Key	Type	Description
`extractions`	`object`	Feedback transfer summary on atomic extractions.
`compoundExtractions`	`object`	Feedback transfer summary on compound extractions.

Response

Status Code	Description
204 (No Content)	The feedback transfer summary was successfully processed.
404 (Not Found)	The document or the label could not be found.
406 (Not Acceptable)	The request headers were not set correctly.
422 (Unprocessable Entity)	At least one value was not valid regarding entity validation rules of the label.

Test example

In order to test the integration of the feedback summary functionality, we offer a PDF test document with the expected outcome in a JSON format. This document can be used for an integration test of Gini’s Pay API in general. Furthermore, we provide a query for sending feedback summary where all fields are correct except for the amountToPay. After sending this feedbacksummary, we show you how to ensure that the feedback summary with your confirmation and correction for the field values was successful.

Sending the test document to the Gini Pay API. See Submit Files.
Requesting the results. See Retrieve Extractions.
You should get a JSON like in the example.
Correcting the document with the following JSON. Here we change the amountToPay from "995.00:EUR" to "950.00:EUR" and confirm the other field values (iban, bic, paymentRecipient, paymentReference).

//Example //We show a more elaborated example here in order to explain different types of the feedback. The example scenario is as follows: the user uploads a document where the labels amountToPay, paymentReference, iban are extracted. Unfortunately the label paymentRecipient could not be extracted. The response to the extractions request is as follows: { "candidates": { }, "extractions": {

Code Block

language	json

{

  "feedback": {
  
    "amountToPay": {
    
      "value": "950.00:EUR"
  
    },

      "iban": {
    
      "value": "DE68130300000017850360"

      },
 
     "bic": {
    
      "value": "BYLADEM1001"
  
    },
  
    "paymentPurpose": {
    
      "value": "RE-20170512-02"
 
     },
       "paymentRecipient": {
   
       "value": "Fahrrad Rückenwind"
       }
   }
}

Code Block

language	json

Below we show a more elaborated example including the Return Assistant compound extractions (if RA is enabled) in order to explain different types of the transfer summary. In our current API, we started to support alternative JSON keys for it. For example, instead of "feedback" key when submitting the summary, you can use "extractions" and "compoundExtractions" as you will see in the examples below.

The next example scenario is as follows: the user uploads a document where the labels amountToPay, paymentReference, iban, discount-addon are extracted. Unfortunately, the label paymentRecipient could not be extracted. Such response to the extractions request is as follows:

Info
The boxes are optional. Boxes should only be sent if your use case visualizes the document with the locations of the extractions. Thus, the user can confirm the correct location of an extraction.

Code Block

language	json

{
  "candidates": {},
  "extractions": {
    "amountToPay": {
     
      "box": {
  
             "height": 8.0,
  
             "left": 545.0,
                "page"page": 1,
     
          "top": 586.0,
     
          "width": 17.0
     
      },
     
      "candidates": "amounts",
     
      "entity": "amount",
  
         "value": "545.6044:EUR"

       },

       "iban": {
            ""box": {
       
        "height": 7.0,
                "left": 447.0,
       
        "page": 1,
       
        "top": 746.0,
      
         "width": 100.0
            },

           "candidates": "ibans",
            "entity"entity": "iban",
     
      "value": "DE68130300000017850360DE14200800000816170700"
        },
   
    "paymentReference": {
            "entity": "reference",
     
      "value": "ReNr 123, KdNr 32"
        }
    },
    "compoundExtractionsdiscount-addon": {
 
      "lineItemsentity": ["amount",
      "value": "-2.51:EUR"
    {
   },
          "artNumber"amountsAreConsistent": {
         "entity": "text",
      "value": "10101true",
    }
  },
  "compoundExtractions": {
    "entitylineItems": "text" ,[
       {
        "boxartNumber": {
            "value": "10101",
          "heightentity": 7.0,"text"
           },
        "leftquantity": 55.0, {
          "value": "2",
          "pageentity": 1,"numeric"
        },
           "topdescription": 546.0,{
              "value": "Trocknerbälle, Wolle, 2er",
     "width": 100.0    "entity": "text"
        },
  }      "sumGross": {
       },   "value": "17.98:EUR",
          "quantityentity": {"amount"
        }
       "value": "12"},
      {
         "entityartNumber": "numeric"{
          "value": "10103",
  }        "entity": "text"
   },     },
       {    "quantity": {
          "artNumbervalue": {
    "3",
           "valueentity": "10103numeric",
        },
        "entitydescription": "text"{
          "value": "Faltenstopp f.  }Wäscheständer",
              "quantity": {"entity": "text"
        },
        "valuesumGross": "3",
     {
          "entityvalue": "numeric29.97:EUR",
          "entity": "amount"
  }      }
      }
        ]
    }
}

//The user adds missing paymentRecipient value (complementary feedback) and corrects the paymentReference to "ReNr 1735, KdNr 37" (negative feedback). Sets the quantity of one line item to 0 and adds a reason for returning the articles. The iban, amountToPay and the remaining part of lineItems are correct (positive feedback). The document is not shown, so we can leave out the boxes. Then the resulting feedback request is as follows:

{
   "extractions": {
       "amountToPay

The iban, amountToPay, discount-addon and the lineItems are correct (positive summary). amountsAreConsistent should be always delivered if it exists in the extractions response. The user adds the missing paymentRecipient value (complementary summary) and corrects the paymentReference to "ReNr 1735, KdNr 37" (negative summary). Sets the quantity of one line item to “0” and adds a reason for returning the articles.

Then the resulting transfer summary request to submit is as follows:

Code Block

language	json

{
  "extractions": {
    "amountToPay": {
      "value": "45.44:EUR"
    },
    "iban": {
      "value": "DE14200800000816170700"
    },
    "bic": {
           ""value": "5.60:EUR"
  BYLADEM1001"
    },

      "ibanpaymentPurpose": {
   
       "value": "DE68130300000017850360"
  RE-20170512-02"
    },
  
    "paymentReferencepaymentRecipient": {
    
      "value": "ReNr 1735, KdNr 37"
 Tchibo GmbH"
     },
       "paymentRecipientamountsAreConsistent": {
       "entity": "text",
      "value": "Zalando SEtrue"
       }
,
  },  "compoundExtractionsdiscount-addon": {

       "lineItemsentity": ["amount",
      "value": "-2.51:EUR"
    {}
  },
     "compoundExtractions": {
     "artNumberlineItems": {[
       {
        "valueartNumber": "10101"{
          "value": "10101"
  },      },
        "quantity": {
  
             "value": "0"
        },
     },   "description": {
          "returnReasonvalue": {"Trocknerbälle, Wolle, 2er",
              "valueentity": "r3text"
        },
     }   "sumGross": {
        }  "value": "17.98:EUR",
          "entity": "amount"
 {       },
        "artNumberreturnReason": {
     
          "value": "10103r3"
        }
      },
      {
        "quantityartNumber": {
  
             "value": "310103"
        },
     }   "quantity": {
        }     "value": "3"
   ]     },
} Give feedback and correct or verify multiple specific labeled extraction patterns with a single PUT or POST request to the document extractions URI.

The labels must correspond to the names of the extraction types e.g. amountToPay. See available specific extractions for possible values.

Headers
Header	Value
Content-Type	application/vnd.gini.v1+json
Body
Key	Type	Description
extractions	object	Feedback on atomic extractions
compoundExtractions	object	Feedback on compound extractions
 The boxes are optional. Boxes should only be sent if your use case visualize the document with the locations of the extractions. Thus, the user can confirm the correct location of a extraction.
Response
Status Code	Description
204 (No Content)	The feedback was successfully processed.
404 (Not Found)	The document or the label could not be found.
406 (Not Acceptable)	The request headers were not set correctly.
422 (Unprocessable Entity)	At least one value was not valid regarding entity validation rules of the label.
Test Example
In order to test the integration of the feedback functionality, we offer a PDF test document with the expected outcome in a JSON format. This document can be used for an integration test of Gini’s Pay API in general. Furthermore, we provide a query for sending feedback where all fields are correct except for the amountToPay. After sending this feedback we show you how you can ensure that the feedback with your confirmation and correction for the field values was successful.

Sending the test document to the Gini Pay API (see also submitting files)
Requesting the results (see also retrieving extractions)
You should get a JSON like in example.
Correcting the document with the following JSON (see also submitting feedback on extractions). Here we change the amountToPay from "995.00:EUR" to "950.00:EUR" and confirm the other field values (iban, bic, paymentRecipient, paymentReference).
{
   "feedback": {
       "amountToPay": {
           "value": "950.00:EUR"
       },
       "iban": {
           "value": "DE68130300000017850360"
       },
       "bic": {
           "value": "BYLADEM1001"
       },
       "paymentPurpose": {
           "value": "RE-20170512-02"
       },
       "paymentRecipient": {
           "value": "Fahrrad Rückenwind"
       }
   }
}

Submit feedback on invalid extractions

...

"description": {
          "value": "Faltenstopp f. Wäscheständer",
          "entity": "text"
        },
        "sumGross": {
          "value": "29.97:EUR",
          "entity": "amount"
        }
      }
    ]
  }
}

Info
Notice, that `"feedback"` key is not present in the above transfer summary. However, you can still keep it when submitting non-compound extractions summary, our API is compatible.

Submit transfer summary on invalid extractions

Request

In case an extraction was erroneously found (i.e. not present in the source document), you can delete it by issuing a DELETE request to the extraction URI:

Code Block

language	json

//submitting summary on invalid extractions

    DELETE /documents/{id}/extractions/{label}

Response

Status Code	Description
204 (No Content)	Label removal was successful.
404 (Not Found)	The document or the label could not be found.

...

language	json

...

Versions Compared

Old Version 15

New Version Current

Key

Ways of submitting

the transfer summary

Types of

transfer summaries

Request

Headers

Body

Response

Test example

Submit feedback on invalid extractions

Submit transfer summary on invalid extractions

Request

Response