Upload Document

This endpoint allows you to upload a single document to a workflow in the Xtracta App. Because a workflow is linked to a specific geographic processing node, the document should be uploaded to the node that the workflow is located on. The API will issue a 307 redirect for your request by analysing the workflow_id and api_key. If your connecting system supports 307 redirects, then it should be automatically redirected to the correct node and the document will be POSTed to it. If your connect system does not support 307 redirects, then the App will return you a temporary URL for the geographic node where the workflow is based.

POST Parameters

ParameterRequiredValueDescription
api_key{key}An API key that has access to the resource you want to query for
workflow_id{integer}The ID of the workflow you wish to upload the document to.
batch_id{integer}The ID of the batch (e.g., 1234567)
field_data{xml}Data can be passed to a field using this parameter, for example you could pass data to a specific field in order to utilise the "custom classification" method.
userfile{file}Define the file you wish to upload. It must be an accepted file type. There is a maximum file size allowed of 110MB per POST. If no file is specified the return will be for a URL for direct POSTing to a regional node (as to avoid 307 redirect).
userfile_url{string}If userfile is not specified, the API checks if you have provided an URL of the file. The additional files will be merged with the first file generating one big file for processing.
learning{integer}Enable the learning for this document. This flag should be used with field_data parameter.
Information Circle

Upload Behavior: If no userfile is specified, the API returns a temporary URL for direct posting to avoid 307 redirects. Maximum file size is 110 MB per POST.

Example of field_data for above case

<field_data>
      <field Id="123">data</field>
      <field name="Invoice Number">INV001</field>
      <field Id="987"></field>
      <field_set id="1">
         <row id="3">
            <field id="123">val1</field>
         </row>
      </field_set>
	<field_set id="2"></field_set>
	<field_set id="2">
	   <row>
	      <field id="123">val1-1</field>
	      <field id="456">val1-2</field>
	   </row>
	   <row>
	      <field id="123">val2-1</field>
	      <field id="456">val2-2</field>
           </row>
      </field_set>
   </field_data>

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/upload' \
  --header 'Accept: application/json' \
  --form 'api_key=<API_KEY>' \
  --form 'workflow_id=<WORKFLOW_ID>' \
  --form 'userfile=@/path/to/document.pdf'

Sample Requests

Without an Uploaded File

POST https://api-app.xtracta.com/v1/documents/upload HTTP/1.1
api_key=123&workflow_id=456&userfile={file}

Following the 307 Redirect

Sample Responses

Without an Uploaded File

ElementDescription
<status>A status code in response to the operation.
<message>Additional information about the operation – human readable.
<url>If you didn't specify a file to upload or your connecting system does not support 307 redirects, this will be the URL on the Xtracta App node (for the chosen workflow) where you can POST the file
<expire>The time the URL will expire. This is expressed in UNIX time.
<document_id>Once the document has been successfully uploaded, this is the Document Id that the Xtracta App will have assigned. This Id is used extensively throughout the App so can be useful if you want to track individual documents.
<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
    <status>203</status>
    <message>userfile is not specified</message>
    <url>https://web1-akl.xtracta.com/v1/documents/upload/...</url>
    <expire>1408672099</expire>
</documents_response>

Following the 307 Redirect

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:complexType name="XmlType">
    <xs:sequence>
      <xs:element name="status" type="xs:integer" minOccurs="0"/>
      <xs:element name="message" type="xs:string" minOccurs="0"/>
      <xs:element name="document_id" type="xs:integer" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <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:element name="xml">
    <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="document_id" type="xs:integer" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>

Error Responses

StatusMessageDescription
400workflow_id is required or workflow_id must be natural numberSupply the target workflow ID.
400learning must be '0' or '1'Use 0 or 1 for the learning option.
400Upload file exceeds the permitted sizeReduce the upload size or split the files.
400userfile_url must be URL formatSupply a valid, accessible file URL.
202userfile is not specifiedNo file or usable URL was supplied; follow the returned upload URL when provided.
307Response includes url and expireUpload the file to the supplied temporary URL before it expires.
500Internal server error occurred. Please try again later or contact support@xtracta.comRetry and contact support with the request timestamp if it persists.
Information Circle

Authentication, permission, IP-access-control, and rate-limit failures can occur before the upload handler processes the request.