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

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

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>

Sample Request

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

Sample Response

Element	Description
`<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.

Sample Response

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

Example (with 307 redirect OR when uploading to the provided URL):

Sample Request

POST https://api-app.xtracta.com/v1/documents/upload HTTP/1.1

api_key=123&workflow_id=456&userfile={file}

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<status>200</status>
	<message>Succeeded to upload</message>
	<document_id>228060</document_id>
</xml>

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>

Element	Description
`<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.

Sample Response

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

Example (with 307 redirect OR when uploading to the provided URL):

Sample Request

POST https://api-app.xtracta.com/v1/documents/upload HTTP/1.1

api_key=123&workflow_id=456&userfile={file}

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<xml>
	<status>200</status>
	<message>Succeeded to upload</message>
	<document_id>228060</document_id>
</xml>

Upload Document

POST Parameters

Example of field_data for above case

Sample Request

Sample Response

Sample Response

Sample Request

Sample Response

Schema Definition

Sample Response

Sample Request

Sample Response

Was this page helpful?