Process via API

This guide walks you through the Vantage API workflow: authenticate, find a skill, upload a document, and download structured results. What you’ll accomplish: Submit a document to the Vantage REST API and receive structured extracted data as JSON. Time to complete: ~10 minutes

Prerequisites

A Vantage tenant with API client credentials (client_id and client_secret)
A sample document to process (PDF, TIFF, JPEG, or PNG)

Don’t have credentials yet? Your tenant admin can create API client credentials in Administration > API clients.

Set your base URL

All requests go to your tenant’s regional endpoint. Pick your region below (the assignment works in both shell and Python) and every sample in this guide uses BASE_URL:

BASE_URL="https://vantage-us.abbyy.com"

BASE_URL="https://vantage-eu.abbyy.com"

BASE_URL="https://vantage-au.abbyy.com"

Step 1: Authenticate

Get an access token using your client credentials.

cURL
Python

curl -X POST "$BASE_URL/auth2/connect/token" \
  -d "grant_type=client_credentials" \
  -d "scope=openid permissions global.wildcard" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

import requests

response = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)

token = response.json()["access_token"]

The response includes an access_token (valid for 24 hours). Use it in the Authorization header for all subsequent requests.

Step 2: Find a skill

List the skills available in your tenant to find the right one for your document.

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/skills" \
  -H "Authorization: Bearer $TOKEN"

skills = requests.get(
    f"{BASE_URL}/api/publicapi/v1/skills",
    headers={"Authorization": f"Bearer {token}"},
).json()

for skill in skills:
    print(f"{skill['id']}: {skill['name']}")

Note the id of the skill you want to use (e.g., an Invoice skill).

Step 3: Process a document

Upload a document and process it with a skill in a single API call.

cURL
Python

curl -X POST "$BASE_URL/api/publicapi/v1/transactions/launch?skillId=SKILL_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'Model={"files": [{}]}' \
  -F "Files=@invoice.pdf;type=application/pdf"

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": "SKILL_ID"},
        headers={"Authorization": f"Bearer {token}"},
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": ("invoice.pdf", f, "application/pdf"),
        },
    )

transaction_id = response.json()["transactionId"]

Step 4: Check status

Poll the transaction until processing is complete.

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

import time

while True:
    status = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()

    print(f"Status: {status['status']}")

    if status["status"] == "Processed":
        break
    if status["status"] in ("Failed", "Canceled"):
        raise Exception("Processing failed")

    time.sleep(5)

Poll every 5–10 seconds. Typical processing takes 10–30 seconds depending on document complexity.

Step 5: Download results

Get the extracted data as JSON. The result file identifiers come from the transaction status response you polled in Step 4: each entry in documents[].resultFiles[] has a fileId and a type. By default, a Document skill produces two result files: type: "Json" (the full results, including field metadata) and type: "FieldsJson" (the extracted values, which is the easiest place to start); skill export settings can add other formats.

cURL
Python

# Get the transaction status; find documents[].resultFiles[] in the response
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

# Download a result file using its fileId
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o result.json

# The status response from Step 4 lists the result files
result_files = status["documents"][0]["resultFiles"]

# Pick the values-only file
fields_file = next(f for f in result_files if f["type"] == "FieldsJson")

result = requests.get(
    f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{fields_file['fileId']}/download",
    headers={"Authorization": f"Bearer {token}"},
).json()

print(result)

The values-only result maps each field defined by the skill to its extracted value. If any rule checks failed during processing, the file also contains a top-level RuleErrors array alongside Version and Fields.

Show Example: Invoice extraction result (values only)

{
  "Version": "3.0",
  "Fields": {
    "Invoice Number": "INV-2024-0042",
    "Invoice Date": "01/15/2024",
    "Currency": "USD",
    "Total": "1,250.00",
    "Business Unit": {
      "Name": "Acme Corp",
      "City": "Springfield",
      "CountryCode": "US"
    },
    "Line Items": [
      {
        "Description": "Widget, industrial grade",
        "Quantity": "2",
        "Unit Price": "625.00",
        "Total Price": "1,250.00"
      }
    ]
  }
}

The exact field names and nesting depend on the skill. For confidence scores, character coordinates, and other field metadata, download the type: "Json" result file instead; its structure is documented in the JSON schema reference. For a full walkthrough of the output structure, see Understanding your results.

Full example

Show Complete Python script

import requests
import time

# Configuration
BASE_URL = "https://vantage-us.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Step 1: Authenticate
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Step 2: Find skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Step 3: Process document
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Step 4: Poll for completion
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Step 5: Download results (result file ids come from the status response)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# Configuration
BASE_URL = "https://vantage-eu.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Step 1: Authenticate
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Step 2: Find skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Step 3: Process document
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Step 4: Poll for completion
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Step 5: Download results (result file ids come from the status response)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# Configuration
BASE_URL = "https://vantage-au.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Step 1: Authenticate
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Step 2: Find skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Step 3: Process document
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Step 4: Poll for completion
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Step 5: Download results (result file ids come from the status response)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

Next steps

Understanding your results

Learn how to read extracted fields, confidence scores, and table data.

API Reference

Full API documentation with interactive playground.

Authentication options

Authorization Code Flow, ROPC, and other auth methods.

Batch processing

Process multiple documents with separate API calls for more control.

Getting Started

Go Deeper

Prerequisites

Set your base URL

Step 1: Authenticate

Step 2: Find a skill

Step 3: Process a document

Step 4: Check status

Step 5: Download results

Full example

Next steps

Understanding your results

API Reference

Authentication options

Batch processing

​Prerequisites

​Set your base URL

​Step 1: Authenticate

​Step 2: Find a skill

​Step 3: Process a document

​Step 4: Check status

​Step 5: Download results

​Full example

​Next steps

Understanding your results

API Reference

Authentication options

Batch processing

Prerequisites

Set your base URL

Step 1: Authenticate

Step 2: Find a skill

Step 3: Process a document

Step 4: Check status

Step 5: Download results

Full example

Next steps