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

# Processing Documents with Separate API Calls

> Process documents in ABBYY Vantage with separate API calls: create an empty transaction, add files, start processing, monitor status, and download results.

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;
    return text.replace(hostRegex, `https://vantage-${currentRegion}.abbyy.com`).replace(tokenRegex, `https://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>;
};

A typical scenario for processing documents using separate API calls (for creating a transaction, uploading a file, and starting a transaction) consists of the following steps:

1. [Receiving a list of all available skills](#receiving-a-list-of-all-available-skills)
2. [Creating an empty transaction](#creating-an-empty-transaction)
3. [Adding a set of files to be processed in the transaction](#adding-a-set-of-files-to-be-processed-in-the-transaction)
4. [Starting the transaction](#starting-the-transaction)
5. [Monitoring the transaction status](#monitoring-the-transaction-status)
6. [Downloading source files and result files](#downloading-source-files-and-result-files)

Each request to the server must include authentication information (such as an access token). For more information, see [Authentication](/vantage/developer/authentication/authentication).

### Receiving a list of all available skills

To do so, send a `GET` request to the `skills` resource:

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/skills
  ```
</VantageRegion>

Run the following command:

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

The response will contain a JSON file that will look something like the following:

```
[
   {
      "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 an empty transaction

To do so, send the following `POST` request to the `transactions` resource:

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions
  ```
</VantageRegion>

Run the following command:

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions" \
  -H "accept: */*" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d "{\"skillId\":\"123\"}"
  ```
</VantageRegion>

After an empty transaction has been successfully created, you will receive a response with the transaction identifier:

```
{
   "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

### Adding a set of files to be processed in the transaction

<Info>
  The maximum number of files in a transaction is 1000.
</Info>

A set of files can be added in two ways:

* [Directly to the transaction](#adding-files-directly-to-the-transaction)
* [To a document, and then adding this document to the transaction](#adding-files-to-a-document)

#### Adding files directly to the transaction

To do so, send a `POST` request to the `transactions/<transaction-id>/files` resource:

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files
  ```
</VantageRegion>

<VantageRegion>
  In the body of the request send the file to be processed. For details on the available parameters for customizing files, see the [API Reference](https://vantage-us.abbyy.com/api/swagger).
</VantageRegion>

Run the following command:

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
  -H "Authorization: Bearer token" \
  -F "Files=@Invoice07.jpg; type=image/jpeg"
  ```
</VantageRegion>

As a result, you will receive a response with a list of added files and their identifiers. You can add as many files as you need by repeating this call multiple times.

Additional options for uploading files:

* [Editing added images](/vantage/developer/processing-documents/editing-added-images)
* [Ordering files and documents](/vantage/developer/processing-documents/ordering-files-and-docs)

#### Adding files to a document

First, create a document by sending a `POST` request to the `transactions/<transaction-id>/documents` resource:

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents
  ```
</VantageRegion>

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json-patch+json"
  ```
</VantageRegion>

As a result, you will receive a response with the document identifier.

Then add files to the document by sending a `POST` request to the `transactions/<transaction-id>/documents/<document-id>/sourceFiles` resource:

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles
  ```
</VantageRegion>

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
  -H "Authorization: Bearer token" \
  -F "Files=@Invoice07.jpg; type=image/jpeg"
  ```
</VantageRegion>

### Starting the transaction

To start the transaction with the specified skill and files, send the following `POST` request to the `transactions/<transaction-id>/start` resource:

<VantageRegion>
  ```
  POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start
  ```
</VantageRegion>

<VantageRegion>
  ```bash theme={null}
  curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
  -H "accept: */*" \
  -H "Authorization: Bearer token" \
  -d ""
  ```
</VantageRegion>

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

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id
  ```
</VantageRegion>

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

The response will look something like the following:

```
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-us.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}
```

In the response:

* If the value of the **status** key is set to:
  * **New** — the transaction is created, but not currently in progress.
  * **Processing** — the transaction has started, but the results are not ready yet.
  * **Processed** — the transaction has been successfully completed, and you will be able to download the results.
  * **Failed** — the transaction failed.
  * **Canceled** — the transaction was canceled.
* 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](/vantage/developer/integrating-manual-review).

<Info>
  Users authorized via this link are not able to view or modify any other documents or transactions.
</Info>

For a Document skill, the response will now look something like the following:

```
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "resultFiles": [
            {
               "fileId": "3a3e6245-48e1-489a-9fef-a10b5ba28515",
               "type": "Json"
            }
         ],
         "businessRulesErrors": []
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}
```

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

For a Classification skill, the response received after the documents have been processed will look something like the following:

```
{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": "Invoice",
            "classConfidences": [
               {
                  "class": "Invoice",
                  "confidence": 89
               },
               {
                  "class": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}
```

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](/vantage/developer/output/json/json-output) by default (the output format is set by the skill).

<Info>
  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](#monitoring-the-transaction-status) response (`documents[].resultFiles[].fileId`).
</Info>

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:

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents
  ```
</VantageRegion>

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

As a result, you will receive a list of all the documents which have been created within this transaction. The response also contains the identifiers of these documents, which may be needed to request detailed information about specific documents.

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

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download
  ```
</VantageRegion>

Run the following command:

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>

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](#monitoring-the-transaction-status) (each entry has a `fileId` and a `type`, such as `Json`):

<VantageRegion>
  ```
  GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download
  ```
</VantageRegion>

Run the following command:

<VantageRegion>
  ```bash theme={null}
  curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
  -H "Authorization: Bearer token"
  ```
</VantageRegion>