Skip to main content
A typical scenario for processing documents using a single API call (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 and starting a transaction
  3. Monitoring the transaction status
  4. Downloading source files and result files
Each request to the server must include authentication information. See Authentication for details. Use this scenario if you only have one file that is less than 30 MB in size and you don’t need to edit images of the file.

​
Receiving a list of all available skills

To do so, send a GET request to the skills resource: Run the following command: For Windows: For Linux: The response will contain a JSON file that will look something like the following: Response: 
[
   {
      "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 and starting a transaction

To create and start a transaction to process an uploaded file with a specified skill, send the following POST request to the transactions/launch?skillId=<skill-id> resource: This will create and immediately start a new transaction. 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: :/?#[]@!$&'()*+,;=\. The changed file name will be displayed in both the Vantage API and Skill Monitor.

​
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: 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 Processing, the results are not ready yet. Once the status of the transaction changes to Processed, you will be able to download the results.
  • 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 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: Run the following command: For Windows: For Linux:

​
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: For Windows: For Linux: 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: For Windows: For Linux: