## Open Document Upload UI

This endpoint allows you to get a pre-logged in URL for a file upload browser user interface. By using this endpoint, you can quickly provide users with a one-click opened interface to upload large numbers of documents.

## POST Parameters

{% apiTable %}
| Parameter | Required | Value | Description |
|-----------|----------|-------|-------------|
| `api_key` | {% requiredIcon type="required" /%} | `{key}` | An API key that has access to the resource you want to query for |
| `workflow_id` | {% requiredIcon type="required" /%} | `{integer}` | The ID of a workflow you want to open the interface for |
| `expire` | {% requiredIcon type="optional" /%} | `{integer}` | The number of seconds that the generated URL is valid for |
{% /apiTable %}

## Code Examples

The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.

{% callout type="warning" %}
Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.
{% /callout %}

{% tabbedCodeExamples %}
```bash
curl --request POST 'https://api-app.xtracta.com/v1/documents/upload/ui' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'workflow_id=<WORKFLOW_ID>' \
  --data-urlencode 'expire=1200'
```

```php
<?php
$endpoint = 'https://api-app.xtracta.com/v1/documents/upload/ui';
$payload = [
    'api_key' => getenv('XTRACTA_API_KEY'),
    'workflow_id' => '<WORKFLOW_ID>',
    'expire' => '1200',
];

$curl = curl_init($endpoint);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query($payload),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException('Xtracta returned HTTP ' . $status . ': ' . $body);
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
```

```python
import os
import requests

response = requests.post(
    "https://api-app.xtracta.com/v1/documents/upload/ui",
    headers={"Accept": "application/json"},
    data={
        "api_key": os.environ["XTRACTA_API_KEY"],
        "workflow_id": "<WORKFLOW_ID>",
        "expire": "1200",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
```

```javascript
const body = new URLSearchParams({
  "api_key": process.env.XTRACTA_API_KEY,
  "workflow_id": "<WORKFLOW_ID>",
  "expire": "1200",
});

const response = await fetch('https://api-app.xtracta.com/v1/documents/upload/ui', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body,
});

if (!response.ok) {
  throw new Error('Xtracta returned HTTP ' + response.status + ': ' + await response.text());
}

const data = await response.json();
```

```csharp
using System.Net.Http.Headers;

using var client = new HttpClient {
    Timeout = TimeSpan.FromSeconds(30)
};
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

using var content = new FormUrlEncodedContent(new Dictionary<string, string> {
    ["api_key"] = Environment.GetEnvironmentVariable("XTRACTA_API_KEY")!,
    ["workflow_id"] = "<WORKFLOW_ID>",
    ["expire"] = "1200",
});

using var response = await client.PostAsync("https://api-app.xtracta.com/v1/documents/upload/ui", content);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();
```

```jsx
async function callXtracta() {
  const response = await fetch('/api/xtracta/documents/upload/ui', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      "workflow_id": "<WORKFLOW_ID>",
      "expire": "1200",
    }),
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  return response.json();
}
```
{% /tabbedCodeExamples %}

## Sample Request

```
POST https://api-app.xtracta.com/v1/documents/upload/ui HTTP/1.1
api_key=123&workflow_id=456789
expire=1200
```

## Sample Response

{% tabbedResponse  title="" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <url>https://api-app.xtracta.com/v1/documents/upload/ui.html?t=...</url>
    <expire>1425900862</expire>
</documents_response>
```

{% /tabbedResponse %}

## Schema Definition


{% tabbedSchema title="" %}

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:simpleType name="ConfidenceType">
    <xs:union>
      <xs:simpleType>
        <xs:restriction base="xs:integer">
          <xs:minInclusive value="0"/>
          <xs:maxInclusive value="100"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value=""/>
        </xs:restriction>
      </xs:simpleType>
    </xs:union>
  </xs:simpleType>

  <xs:element name="documents_response">
    <xs:complexType>
      <xs:sequence>
      <xs:element name="status" type="xs:integer" minOccurs="0"/>
      <xs:element name="message" type="xs:string" minOccurs="0"/>
      <xs:element name="url" type="xs:anyURI" minOccurs="0"/>
      <xs:element name="expire" type="xs:integer" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
```

{% /tabbedSchema %}
## Error Responses

For JSON and XML responses generated by this endpoint, the response is wrapped in `documents_response` and includes the HTTP status code and a `message`.

{% apiTable %}
| Status | Message | Description |
|---|---|---|
| `400` | workflow_id is required | Supply the workflow whose upload interface should be opened. |
| `400` | workflow_id must be natural number | Use a positive integer workflow ID. |
| `400` | expire must be natural number / expire must be greater than ... / expire must be less than ... | Supply a positive expiry duration within the configured URL-expiry range. |
| `500` | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry the request. If it persists, contact support with the workflow ID and request timestamp. |
{% /apiTable %}

{% callout type="note" %}
Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm that the API key is active and can access the workflow.
{% /callout %}


Open Document Upload UI

Logging In

Overview

Home Page

Supported Languages

Get started

My Account

Workflow Overview

Uploading Documents

ELS Overview

Splitting Pages

Engine Learning Screen

New ELS Overview

Edit Document and Pages

Change Field Highlight Color

Learn & Extract

Learn & Extract (Previously Auto Line Extraction )

New Engine Learning Screen (New ELS)

User Manual

Get Document(s)

Update Document

Upload Document

Open Document UI

Open Reassign Pages

Documents

Create Batch

Update Batch

Get Batches

Get Batch Workflow

Batches

Get Tracking

Update Tracking Status

Tracking

Open Dashboard

Open Tracking Dashboard

Dashboard

Get Databases

Add Database

Update Database

Delete Database

Get Columns

Update Column

Add Column

Delete Column

Get Data

Add Data

Update Data

Delete Data

Database

Provisioning

Get Workflow

Update Workflow

Add Workflow from Template

Clone Workflow

Workflow

Delete Group

Add Group

List Group

Group

Get User

Add User

Update User

Delete User

Get Login Token

Authorize

User

Open Billing UI

Get Plans

Get Usage

Renew/Upgrade/Downgrade Plan

Get Billing History

Order Pack

Billing

Announcements

API Manual

Billing Settings

General Settings

Groups

OCR Override

Time Alerts

Confidence

Extraction & Classification

Clone a workflow

Reassignment / Output Non-API

Conditions

Permissions

Auto Deletion

AI Data Transformation

Fields

Transformation Order

Advanced Transformation

Workflow Details

Strip & Replace Rules

Creating a workflow

Input & Document Flow

Extraction Helper

Advanced Validation

Workflows

Users

Admin Manual

Databases

IP Access Control

Client Applications

Client Push Application

Applications

Alerts

Single Sign On (SSO)

Peppol Participants

General FAQs

Why is a document locked?

Which URL`s are needed for Xtracta to go through a firewall?

What type of documents are accepted by Xtracta?

What is a workflow?

What are the different statuses for a document?

What are the status for a document?

What does training a document mean?

What are the options when a document is selected?

What is Regex?

How does a document get a class and a designn?

How does a document get a class and a design?

How many pages and Line Items can Xtracta process?

Frequently Asked Questions

Parameter	Required	Value	Description
`api_key`	✅	`{key}`	An API key that has access to the resource you want to query for
`workflow_id`	✅	`{integer}`	The ID of a workflow you want to open the interface for
`expire`		`{integer}`	The number of seconds that the generated URL is valid for

Status	Message	Description
`400`	workflow_id is required	Supply the workflow whose upload interface should be opened.
`400`	workflow_id must be natural number	Use a positive integer workflow ID.
`400`	expire must be natural number / expire must be greater than ... / expire must be less than ...	Supply a positive expiry duration within the configured URL-expiry range.
`500`	Internal server error occurred. Please try again later or contact support@xtracta.com	Retry the request. If it persists, contact support with the workflow ID and request timestamp.

Open Document Upload UI

POST Parameters

Code Examples

Sample Request

Sample Response

Schema Definition

Error Responses

Was this page helpful?