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.

Pass callback_url in the POST request to /v1/documents/ui when you generate the document UI URL. It sets the return URL for that UI session. You can use a different return URL for each environment or request. Open the generated UI URL from the response; adding callback_url to that URL later does not set the return URL.

The UI sends the browser to this URL after the user completes an action. This is browser navigation, not a server-to-server webhook or a POST of document data to your application.

In Classic ELS, both buttons use the same callback_url:

Save and Close: Saves the current field changes, then sends the browser to callback_url once the action succeeds. The buttons setting controls whether this button runs Save, Send to Indexing, or Output. If the action fails, the UI shows the error instead of returning through the success path.

Close Without Saving: Closes the document without saving the current field changes and releases it from processing, then sends the browser to the same callback_url. It does not undo changes saved earlier.

The New ELS also uses callback_url as the return destination after completed actions from the Open Document UI API.

If you omit callback_url, the UI attempts to close the browser tab. Browser rules may prevent the tab from closing.

Xtracta opens the supplied URL without adding a button name, save/cancel flag, document ID, or extracted field data. The callback alone cannot tell your application which button the user clicked.

You can include your own reference in the return URL, for example:

https://your-app.example/xtracta/return?reference=invoice-123

This reference helps your application identify the session; it does not report the action or its result. Use the Get Document(s) endpoint if your application needs to read the stored document data after the user returns.

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>' \
  --data-urlencode 'buttons=save' \
  --data-urlencode 'callback_url=https://your-app.example/xtracta/return?reference=invoice-123'

Use form URL encoding for callback_url, as shown by --data-urlencode above, so any query string stays part of the return URL.

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.

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

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

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

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

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.