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

export const VantageRegion = ({children}) => {
  const STORAGE_KEY = "abbyy.vantage.region";
  const REGIONS = [{
    code: "eu",
    label: "Europe"
  }, {
    code: "us",
    label: "North America"
  }, {
    code: "au",
    label: "Australia / Asia-Pacific"
  }];
  const [region, setRegion] = useState("eu");
  const [open, setOpen] = useState(false);
  const containerRef = useRef(null);
  const dropdownRef = useRef(null);
  function safeGetSavedRegion() {
    try {
      const saved = typeof window !== "undefined" ? window.localStorage.getItem(STORAGE_KEY) : null;
      const valid = new Set(REGIONS.map(r => r.code));
      return saved && valid.has(saved) ? saved : "eu";
    } catch {
      return "eu";
    }
  }
  function safeSetSavedRegion(code) {
    try {
      if (typeof window !== "undefined") {
        window.localStorage.setItem(STORAGE_KEY, code);
      }
    } catch {}
  }
  function dispatchRegionChanged(code) {
    try {
      if (typeof window !== "undefined") {
        window.dispatchEvent(new CustomEvent("abbyy:region-changed", {
          detail: {
            code
          }
        }));
      }
    } catch {}
  }
  function replaceRegionInString(text, currentRegion) {
    if (typeof text !== "string") return text;
    const hostRegex = /https:\/\/vantage-(eu|us|au)\.abbyy\.com/gi;
    const tokenRegex = /https:\/\/vantage-\[region\]\.abbyy\.com/gi;
    const bareHostRegex = /vantage-(eu|us|au)\.abbyy\.com/gi;
    const bareTokenRegex = /vantage-\[region\]\.abbyy\.com/gi;
    return text.replace(hostRegex, `https://vantage-${currentRegion}.abbyy.com`).replace(tokenRegex, `https://vantage-${currentRegion}.abbyy.com`).replace(bareHostRegex, `vantage-${currentRegion}.abbyy.com`).replace(bareTokenRegex, `vantage-${currentRegion}.abbyy.com`);
  }
  useEffect(() => {
    setRegion(safeGetSavedRegion());
  }, []);
  useEffect(() => {
    const root = containerRef.current;
    if (!root) return;
    const anchors = root.querySelectorAll("a[href]");
    anchors.forEach(a => {
      const href = a.getAttribute("href");
      if (href) {
        const next = replaceRegionInString(href, region);
        if (next !== href) {
          a.setAttribute("href", next);
        }
      }
    });
    const walker = typeof document !== "undefined" ? document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null) : null;
    if (walker) {
      const toUpdate = [];
      let node = walker.nextNode();
      while (node) {
        const updated = replaceRegionInString(node.nodeValue, region);
        if (updated !== node.nodeValue) {
          toUpdate.push([node, updated]);
        }
        node = walker.nextNode();
      }
      toUpdate.forEach(([textNode, value]) => {
        textNode.nodeValue = value;
      });
    }
  }, [region, children]);
  useEffect(() => {
    const root = containerRef.current;
    if (!root) return;
    const anchors = root.querySelectorAll("a[href]");
    anchors.forEach(a => {
      a.style.fontWeight = "600";
      a.style.textDecoration = "underline";
      a.style.textUnderlineOffset = "2px";
    });
  }, [region, children]);
  useEffect(() => {
    const onRegionChanged = evt => {
      const code = evt && evt.detail && evt.detail.code;
      if (!code || code === region) return;
      setRegion(code);
    };
    if (typeof window !== "undefined") {
      window.addEventListener("abbyy:region-changed", onRegionChanged);
    }
    return () => {
      if (typeof window !== "undefined") {
        window.removeEventListener("abbyy:region-changed", onRegionChanged);
      }
    };
  }, [region]);
  useEffect(() => {
    const onClickAway = e => {
      if (!dropdownRef.current) return;
      if (!dropdownRef.current.contains(e.target)) {
        setOpen(false);
      }
    };
    document.addEventListener("click", onClickAway, true);
    return () => document.removeEventListener("click", onClickAway, true);
  }, []);
  const onSelect = code => {
    setRegion(code);
    safeSetSavedRegion(code);
    dispatchRegionChanged(code);
    setOpen(false);
  };
  const current = REGIONS.find(r => r.code === region) || REGIONS[0];
  return <div className="not-prose">
      <div className="mb-4 inline-flex items-center gap-2" ref={dropdownRef}>
        <span className="text-sm text-zinc-950/80 dark:text-white/80">Tenant Region:</span>
        <div className="relative">
          <button type="button" aria-haspopup="listbox" aria-expanded={open ? "true" : "false"} onClick={() => setOpen(v => !v)} className="h-8 px-3 rounded-md bg-zinc-900/5 dark:bg-white/5 border border-zinc-950/20 dark:border-white/20 text-sm inline-flex items-center gap-2">
            <span className="text-zinc-950 dark:text-white">{current.label}</span>
            <svg width="8" height="24" viewBox="0 -9 3 24" className="transition-transform text-gray-400 overflow-visible dark:text-gray-600 ml-auto" style={{
    transform: open ? "rotate(270deg)" : "rotate(90deg)"
  }}>
              <path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"></path>
            </svg>
          </button>
          {open ? <div role="listbox" className="absolute z-50 left-full top-0 ml-2 w-56 rounded-xl border border-zinc-950/20 dark:border-white/20 bg-white dark:bg-zinc-900 shadow-lg p-2">
              {REGIONS.map(r => {
    const selected = r.code === region;
    return <button key={r.code} type="button" role="option" aria-selected={selected ? "true" : "false"} onClick={() => onSelect(r.code)} className={"w-full flex items-center justify-between px-3 py-2 rounded-lg text-sm hover:bg-zinc-950/5 dark:hover:bg-white/10 text-zinc-950 dark:text-white" + (selected ? " font-medium" : "")}>
                    <span style={selected ? {
      color: "#ff2038"
    } : undefined}>{r.label}</span>
                    <span className={selected ? "ml-3" : "ml-3 invisible"} style={selected ? {
      color: "#ff2038"
    } : undefined}>✓</span>
                  </button>;
  })}
            </div> : null}
        </div>
      </div>
      <div ref={containerRef} className="prose dark:prose-invert max-w-none">{children}</div>
    </div>;
};

<VantageRegion>
  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>

  ## Step 1: Authenticate

  Get an access token using your client credentials.

  <Tabs>
    <Tab title="cURL">
      ```bash theme={null}
      curl -X POST "https://vantage-us.abbyy.com/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(
          "https://vantage-us.abbyy.com/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.

  <Callout type="tip">
    Use the **Tenant Region** selector at the top of this page to update all URLs to match your region.
  </Callout>

  ## 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 "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
        -H "Authorization: Bearer $TOKEN"
      ```
    </Tab>

    <Tab title="Python">
      ```python theme={null}
      skills = requests.get(
          "https://vantage-us.abbyy.com/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 "https://vantage-us.abbyy.com/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(
              "https://vantage-us.abbyy.com/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 "https://vantage-us.abbyy.com/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"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}",
              headers={"Authorization": f"Bearer {token}"},
          ).json()

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

          if status["status"] in ("Processed", "ProcessedWithWarnings"):
              break
          if status["status"] == "NotProcessed":
              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.

  <Tabs>
    <Tab title="cURL">
      ```bash theme={null}
      # List documents in the transaction
      curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID/documents" \
        -H "Authorization: Bearer $TOKEN"

      # Download result file
      curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
        -H "Authorization: Bearer $TOKEN" \
        -o result.json
      ```
    </Tab>

    <Tab title="Python">
      ```python theme={null}
      # Get documents
      docs = requests.get(
          f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}/documents",
          headers={"Authorization": f"Bearer {token}"},
      ).json()

      # Download result for first document
      result_file_id = docs[0]["resultFiles"][0]["id"]

      result = requests.get(
          f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}/files/{result_file_id}/download",
          headers={"Authorization": f"Bearer {token}"},
      ).json()

      print(result)
      ```
    </Tab>
  </Tabs>

  The result contains extracted fields with values and confidence scores.

  <Expandable title="Example: Invoice extraction result">
    ```json theme={null}
    {
      "SkillName": "ABBYY Invoice",
      "Documents": [
        {
          "ExtractedData": {
            "RootObject": {
              "Fields": [
                {
                  "Name": "InvoiceNumber",
                  "List": [{
                    "Value": "INV-2024-0042",
                    "Annotation": { "Confidence": 97, "RawValue": "INV-2024-0042" },
                    "NeedVerification": false
                  }]
                },
                {
                  "Name": "VendorName",
                  "List": [{
                    "Value": "Acme Corp",
                    "Annotation": { "Confidence": 95, "RawValue": "Acme Corp" },
                    "NeedVerification": false
                  }]
                },
                {
                  "Name": "TotalAmount",
                  "List": [{
                    "Value": "1,250.00",
                    "Annotation": { "Confidence": 88, "RawValue": "1,250.00" },
                    "NeedVerification": false
                  }]
                }
              ]
            }
          }
        }
      ]
    }
    ```
  </Expandable>

  Each field includes a `Value` (the extracted text after normalization), an `Annotation.Confidence` score from 0 to 100, and a `NeedVerification` flag indicating whether human review is recommended. Fields with low confidence or validation rule failures are automatically flagged.

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

  ## Full example

  <Expandable title="Complete Python script">
    ```python 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"] in ("Processed", "ProcessedWithWarnings"):
            break
        if tx["status"] == "NotProcessed":
            raise Exception(f"Processing failed")
        time.sleep(5)

    # Step 5: Download results
    docs = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/documents",
        headers=headers,
    ).json()

    for doc in docs:
        for rf in doc.get("resultFiles", []):
            result = requests.get(
                f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['id']}/download",
                headers=headers,
            ).json()
            print(result)
    ```
  </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>
</VantageRegion>