> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Process via API

> Step-by-step quickstart for processing a document with the ABBYY Vantage REST API: authenticate, pick a skill, upload a file, and download extracted JSON data.

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)

<Callout type="info">
  Don't have credentials yet? Your tenant admin can create API client credentials in **Administration > API clients**.
</Callout>

### 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`:

<CodeGroup>
  ```bash US theme={null}
  BASE_URL="https://vantage-us.abbyy.com"
  ```

  ```bash EU theme={null}
  BASE_URL="https://vantage-eu.abbyy.com"
  ```

  ```bash AU theme={null}
  BASE_URL="https://vantage-au.abbyy.com"
  ```
</CodeGroup>

## Step 1: Authenticate

Get an access token using your client credentials.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"]
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "$BASE_URL/api/publicapi/v1/skills" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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']}")
    ```
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"]
    ```
  </Tab>
</Tabs>

## Step 4: Check status

Poll the transaction until processing is complete.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

<Callout type="info">
  Poll every 5–10 seconds. Typical processing takes 10–30 seconds depending on document complexity.
</Callout>

## 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.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # 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)
    ```
  </Tab>
</Tabs>

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`.

<Expandable title="Example: Invoice extraction result (values only)">
  ```json theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</Expandable>

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](/vantage/developer/output/json/json-schema).

For a full walkthrough of the output structure, see [Understanding your results](/vantage/getting-started/results).

## Full example

<Expandable title="Complete Python script">
  <CodeGroup>
    ```python US theme={null}
    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)
    ```

    ```python EU theme={null}
    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)
    ```

    ```python AU theme={null}
    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)
    ```
  </CodeGroup>
</Expandable>

## Next steps

<CardGroup cols={2}>
  <Card title="Understanding your results" icon="magnifying-glass" href="/vantage/getting-started/results">
    Learn how to read extracted fields, confidence scores, and table data.
  </Card>

  <Card title="API Reference" icon="rectangle-terminal" href="/vantage/developer/api-introduction">
    Full API documentation with interactive playground.
  </Card>

  <Card title="Authentication options" icon="lock" href="/vantage/developer/authentication/authentication">
    Authorization Code Flow, ROPC, and other auth methods.
  </Card>

  <Card title="Batch processing" icon="layer-group" href="/vantage/developer/processing-documents/processing-documents-with-separate-api-calls">
    Process multiple documents with separate API calls for more control.
  </Card>
</CardGroup>