Skip to main content
A typical scenario for processing documents using separate API calls (for creating a transaction, uploading a file, and starting a transaction) consists of the following steps:
  1. Receiving a list of all available skills
  2. Creating an empty transaction
  3. Adding a set of files to be processed in the transaction
  4. Starting the transaction
  5. Monitoring the transaction status
  6. Downloading source files and result files
Each request to the server must include authentication information (such as an access token). For more information, see Authentication.

​
Receiving a list of all available skills

To do so, send a GET request to the skills resource: Run the following command: The response will contain a JSON file that will look something like the following: 
[
   {
      "id": "Receipt",
      "name": "Receipt",
      "type": "Document"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "NewClassifier",
      "type": "Classification"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "Invoice",
      "type": "Document"
   }
]
Define the skill identifier you are going to use. Detailed descriptions of skills can be found in built-in skills.

​
Creating an empty transaction

To do so, send the following POST request to the transactions resource: Run the following command: After an empty transaction has been successfully created, you will receive a response with the transaction identifier: 
{
   "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

​
Adding a set of files to be processed in the transaction

The maximum number of files in a transaction is 1000.
A set of files can be added in two ways:

​
Adding files directly to the transaction

To do so, send a POST request to the transactions/<transaction-id>/files resource: Run the following command: As a result, you will receive a response with a list of added files and their identifiers. You can add as many files as you need by repeating this call multiple times. Additional options for uploading files:

​
Adding files to a document

First, create a document by sending a POST request to the transactions/<transaction-id>/documents resource: As a result, you will receive a response with the document identifier. Then add files to the document by sending a POST request to the transactions/<transaction-id>/documents/<document-id>/sourceFiles resource:

​
Starting the transaction

To start the transaction with the specified skill and files, send the following POST request to the transactions/<transaction-id>/start resource:

​
Monitoring the transaction status

To start monitoring the transaction status by using a loop with a short timeout (we do not recommend checking the status more often than once per second), send a GET request to the transactions/<transaction_id> resource with the transaction identifier in the request URI: The response will look something like the following: 
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-us.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}
In the response:
  • If the value of the status key is set to:
    • New — the transaction is created, but not currently in progress.
    • Processing — the transaction has started, but the results are not ready yet.
    • Processed — the transaction has been successfully completed, and you will be able to download the results.
    • Failed — the transaction failed.
    • Canceled — the transaction was canceled.
  • The manualReviewLink key will contain a link to the web interface of the Manual Review client and a Vantage access token, if manual review is required. This link and token can be used to review and correct the classification and field extraction results of a particular transaction. Until the review is completed, the value of the status key will be set to Processing. The provided link is valid for 168 hours, after which a new link should be created and obtained for another period of 168 hours using the same method. See more in Integrating manual review.
Users authorized via this link are not able to view or modify any other documents or transactions.
For a Document skill, the response will now look something like the following: 
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "resultFiles": [
            {
               "fileId": "3a3e6245-48e1-489a-9fef-a10b5ba28515",
               "type": "Json"
            }
         ],
         "businessRulesErrors": []
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}
In the documents array, each document has a resultFiles array. Use this array to get the fileId values. The format of the output files is defined by the skill that you use. Currently, all skills return the extracted fields in JSON format. For a Classification skill, the response received after the documents have been processed will look something like the following: 
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": "Invoice",
            "classConfidences": [
               {
                  "class": "Invoice",
                  "confidence": 89
               },
               {
                  "class": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}
Extract the class of the document from the resultClass key and check the confidence of each probable class in the confidence keys. For a Process skill, the response may contain all or some of the information that is returned for Document and Classification skills, depending on the stages available in the Process skill.

​
Downloading source files and result files

After processing finishes, you can download two kinds of file:
  • Source files — the original files you uploaded, returned in their original binary format.
  • Result files — the processing output: the extracted data, in JSON format by default (the output format is set by the skill).
Source files and result files use different endpoints and different file identifiers:
  • Source file — GET transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download. The file ID comes from the GET transactions/<transaction-id>/documents response (sourceFiles[].id).
  • Result file — GET transactions/<transaction-id>/files/<file-id>/download. The file ID comes from the resultFiles array in the transaction status response (documents[].resultFiles[].fileId).
To request a list of documents with their identifiers, send a GET request to the transactions/<transaction-id>/documents resource and specify the transaction identifier: As a result, you will receive a list of all the documents which have been created within this transaction. The response also contains the identifiers of these documents, which may be needed to request detailed information about specific documents.

​
Source files

To download a required source file, send a GET request to the transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download resource and specify the identifiers of the transaction, document, and file (from the last response): Run the following command: The response will contain the file in binary format. Repeat this step for all your source files.

​
Result files

To download a result file, send a GET request to the transactions/<transaction-id>/files/<file-id>/download resource and specify the transaction identifier and the result file’s fileId. Get the fileId from the resultFiles array returned when monitoring the transaction status (each entry has a fileId and a type, such as Json): Run the following command: