Processing documents with separate API calls
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:
- Receiving a list of all available skills
- Creating an empty transaction
- Adding a set of files to be processed in the transaction
- Starting the transaction
- Monitoring the transaction status
- Downloading source files and result files
Each request to the server must include authentication information (such as an access token). See Authentication for details.
Receiving a list of all available skills
To do so, send a GET request to the skills resource:
|
GET https://vantage-eu.abbyy.com/api/publicapi/v1/skills for users in Western Europe, GET https://vantage-au.abbyy.com/api/publicapi/v1/skills for users in Australia |
Run the following command:
For Windows
For Linux
The response will contain a JSON file that will look something like the following:
Response
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:
POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions for users in Western Europe, POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions for users in Australia |
The request body is a form that contains an object with the skill identifier and the JSON file contents. To create and send the request, run the following command:
For Windows
For Linux
After an empty transaction has been successfully created, you will receive a response with the transaction identifier:
Response
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:
- You can add files directly to the transaction.
- You can create a document in the transaction first, and then add files to this document.
To add files directly to the transaction, send the following POST request to the transactions/<transaction-id>/files resource:
POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files for users in Western Europe, POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files for users in Australia |
Run the following command:
For Windows
For Linux
When uploading the file to Vantage, all of the following characters in the file name will be replaced with an underscore: :/?#[]@!$&'()*+,;=\z. The changed file name will be displayed in both the Vantage API and Skill Monitor.
The second option is to create a document in the transaction first, and then add files to that document. This will allow you to group files into different documents.
To create a document, send the following POST request to the transactions/<transaction-id>/documents resource:
POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in Western Europe, POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in Australia |
You can create at most one document for both Document and Classification skills. Multiple files should then be uploaded to that single document.
Run the following command:
For Windows
For Linux
To add files to the document, send the following POST request to the transactions/<transaction-id>/documents/<document-id>/sourceFiles resource:
POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/ for users in Western Europe, POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/ for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/ for users in Australia |
Run the following command:
For Windows
For Linux
On how to edit added images of the file, see Editing added images. On how to order the files in the document or documents in the transaction, see Ordering files and documents.
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:
POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/start/ for users in Western Europe, POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start/ for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/start/ for users in Australia |
Run the following command:
For Windows
For Linux
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:
GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id for users in Western Europe, GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id for users in North America and GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id for users in Australia |
Run the following command:
For Windows
For Linux
The response will look something like the following:
Response
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:
Response
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:
Response
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
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:
GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in Western Europe, GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in North America and GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents for users in Australia |
Run the following command:
For Windows
For Linux
To download a required source file,send a GET request tothe 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):
GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download for users in Western Europe,
GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download for users in North Americaand GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download for users in Australia |
Run the following command:
For Windows
For Linux
The response will contain the file in binary format. Repeat this step for all your source files.
To download the result files,send a GET request tothe transactions/<transaction-id>/files/<file-id>/download resource and specify the identifiers of the transaction, document, and file (from the last response):
GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download for users in Western Europe,
GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download for users in North Americaand GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download for users in Australia |
Run the following command:
For Windows
For Linux
22.12.2023 12:36:42