Open Document UI

This endpoint allows you to open a document within the Xtracta App web UI. This allows the document to be fixed should it have an error or if data hasn't been captured, the user can help the App learn by clicking on the pertinent data for a field.

POST Parameters

ParameterRequiredValueDescription
api_key{key}An API key that has access to the resource you want to query for.
document_id{integer}The ID of a specific document you want to open in the UI of the Xtracta App.
expire{integer}The length of time the returned URL will be valid for before it expires and cannot be used (and thus must be regenerated). The time will be in seconds. It has a maximum value of 86,400 (One day) and a default value of 600 seconds (Ten Minutes).
callback_url{url}Open a specific URL when the document has been processed through the provided URL.
after_api_download_statusactive, archivedChoose which status you wish the document to have after it has been processed through the provided URL. If not set, the archived status will not change.
no_lockout{integer}Passing this as true ("1") will enable multiple users to access a single document concurrently, by default only a single user can access a document at any given time.
free_form{string}Custom data can be passed to this field. It can be used to track the user accessing the document. Previous values will be overwritten.
buttonssave, output, indexing, qa, reject, archive, delete, save_and_learnAdditional buttons to display. Comma separated. By default, Save and Output are displayed.
user_email{unicode}This optional field can be used to record the email address of the user uploading the document.
user_id{integer}This optional field can be used to record the user ID of the user uploading the document.
field_options{xml}Gives the ability to disable and hide fields from the user when accessing the document.
version{integer}Used to select whether to open a document in the legacy Engine Learning Screen (ELS) with default value = 1. Use value = 2 to open the document using the New ELS
Information Circle

URL Expiration: Generated URLs expire after the specified time (default: 10 minutes, max: 24 hours). Use no_lockout=1 to allow multiple concurrent users.

Information Circle
User email and ID
  • If a value is passed for the user_email that does not exist as a current user, a new user record will be created.
  • If the user_id option is passed, the user ID must be a valid value.

If both are passed, user_email will take precedence.

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.

Warning

Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.

curl --request POST 'https://api-app.xtracta.com/v1/documents/ui' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'document_id=<DOCUMENT_ID>'

Sample Request

POST https://api-app.xtracta.com/v1/documents/ui HTTP/1.1
api_key=123&document_id=456789

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
    <status>200</status>
    <message>The request has been successfully processed</message>
    <url>https://api-app-ui.xtracta.com/main/an_entry/index/d/XXvVBmX.Jdk.rx2OKLOleBzLC__Q3VLbDYYWqvCUrOQ-</url>
    <expire>1426630034</expire>
</documents_response>

Schema Definition

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

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.

StatusMessageDescription
400<parameter> must be natural numberdocument_id, workflow_id, expire, document_expire, items_per_page, and page must use supported positive integer values.
400<parameter> must be greater than ... / <parameter> must be less than ...Keep expire and document_expire within the configured URL-expiry range.
400<parameter> must be '0' or '1'Boolean options such as redirect and no_lockout accept only 0 or 1.
400<parameter> must be one of the values of [...]Use a supported document status, download status, or document order.
400<parameter> must be URL format / <parameter> must be email address formatSupply a valid callback_url or user_email.
400Invalid XML format in field_options / Invalid field_id in field_options / Invalid field_name in field_optionsCorrect the field_options XML and reference fields from the selected document workflow.
400Neither valid workflow_id nor document_id is specifiedSupply one valid selector: workflow_id or document_id.
403Document is not in valid status to process this request (...)The selected document cannot be opened in its current processing state.
403This document is not available because of the billing issue.Resolve the billing issue, then retry.
404No documents foundCheck the document ID and API-key access.
409Document is being processed by someone elseWait for the current user or process to release the document, or use the supported lockout option where appropriate.
500Failed to generate the New ELS URL for document ...Retry the request. If it persists, contact support with the document ID and request timestamp.
500Internal server error occurred. Please try again later or contact support@xtracta.comRetry and contact support if the error persists.
Information Circle

Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.