How to Process Documents Using the REST API
Your application may call ABBYY Vantage services directly via the REST API. The API lets you process your files using any of the available skills and review documents in the Manual Review Client. To design or edit skills and monitor activities, you will have to use the web interface.
For more information, see the API description in the Swagger documentation.
Processing Documents
This guide walks you through a few simple steps where you will choose a skill to use, upload the files to be processed with that skill, and retrieve the results.
Each request to the server must include authentication information. See Authentication for details.
- To receive a list of all the available skills, 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 |
Execute the following command:
For Windows
For Linux
The response will contain a JSON file that will look something like the following:
Response
If you know the name of the skill you are going to use, use this list to find out its identifier.
Next, you can either:
- use three separate API calls in three steps: create a transaction, upload a file, and start the transaction (steps 2 through 4), or
- use a single API call that does all of the above in one step (step 5).
- To create an empty transaction, send the following POST request to the transactions resource:
|
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, perform the following command:
For Windows
For Linux
After an empty transaction has been successfully created, you will receive a response with the transaction identifier:
{
"transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
|
- In this step, you can add a set of files to be processed in the transaction. Alternatively, you can first create a document in the transaction and then add files to this document. This will allow you to group files into different documents.
Important! You can create at most one document for both Document and Classification Skills. Multiple files should then be uploaded to that single document.
- To add a set of files directly to the transaction, send the following POST request to the transactions resource:
|
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 |
Execute the following command:
For Windows
For Linux
- To create a document in the transaction, send the following POST request to the transactions resource:
|
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 |
Execute the following command:
For Windows
For Linux
Next, you need to add files to the document. To do this, send the following POST request to the transactions resource:
|
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 |
Execute the following command:
For Windows
For Linux
Important! The maximum number of files in a transaction is 1000.
By default, added images are edited according to specific skill properties. For example, the following changes can be applied:
- Cropping: page borders are detected and cropped, skewing and distortions are also fixed;
- Rotation: pages with non-standard orientation (e.g. pages with vertical text) are rotated.
You can allow or cancel automatic image editing using the AutoCrop and AutoOrientation flags. To do so, pass these parameters in the transaction with the yes or no value:
For Windows
For Linux
The AutoCrop and AutoOrientation parameters can be set for both transactions and skills. If these parameters are set to yes or no for a specific transaction, images are edited according to those values. If these values are set to default, images are preprocessed according to values specified for these parameters in the skill itself. By default, these parameters are set to default.
Important! Currently, values for these parameters can only be set for OCR skills.
- To start the transaction with the specified skill and files, send the following POST request to the transactions resource:
|
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 |
Execute the following command:
For windows
For Linux
Important! Steps 2 through 4 allow you to process large files in multiple threads. If you only have one file that is less than 30 MB, you can follow step 5 instead of steps 2 through 4.
- To create and start a transaction to process an uploaded file with a specified skill, send the following POST request to the transactions resource:
|
POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/launch?skillId=skill-id for users in North America and POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/launch?skillId=skill-id for users in Australia |
This will create and immediately start a new transaction.
Execute the following command:
For Windows
For Linux
- 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) and send a GET request to the transactions resource with the transaction identifier in the request URI:
|
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 |
Execute the following command:
For Windows
For Linux
The response will look something like the following:
Response
Look at the value of the status key. If it is set to Processing, the results are not ready yet.
If Manual Review is required, the manualReviewLink key in the response will contain a link to the web interface of the Manual Review Client and a Vantage access token. This link and token can be used to review and correct the classification and field extraction results of a particular transaction. See more in Integrating Manual Review. 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.
Important! Users authorized via this link are not able to view other documents, transactions, create new transactions, etc.
Once the status changes to Processed, you will be able to download the results. 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.
- In this step, you can download a result file and a source file.
To download a result file, call the download method for the transactions resource and specify the transaction and file identifiers:
|
GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download for users in North America and GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download for users in Australia |
Execute the following command:
For Windows
For Linux
To download a source file of the transaction, call the sourceFiles method for the transactions resource and specify the transaction, document, and file identifiers:
|
GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id for users in North America and GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id for users in Australia |
Execute the following command:
For Windows
For Linux
The response will contain the file in binary format. Repeat this step for all your result files.
06.09.2022 16:21:49