Get Document(s)

This endpoint allows you to get a list of all documents (and their relating data & images) matching your query parameters OR if you pass a DocumentId, the data for a single document. This method cannot insert data into the Xtracta App. It can only be used to retrieve data.

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 information for
workflow_id{integer}The ID of a workflow you want document information for
any_user_documents1 or 0User documents you want to get
document_statuspre-processing, indexing, qa, reject, output, output-in-progress, api-ui-in-progress, prelearning, learningLimit the results to documents of a particular status within the workflow
api_download_statusactive, archivedDefine what status the document is in. Usually once you have downloaded the document, you would use the update document method to set it to archived. Thus when running this query you would usually set this parameter to active. By doing this, because previous documents you have downloaded would be in archive status, only new documents you haven't downloaded through the API would be present.
page{integer}If the number of matching documents exceeds items_per_page, use page to request the next result page.
items_per_page{integer}Define the number of documents returned per page. The default is 20 for XML/JSON responses (10 for HTML); the maximum is 1,000 for XML/JSON (100 for HTML).
documents_orderasc, descHow the documents are ordered when they are returned (by document_id)
detailed1, {null}When set to "1" this will return all data about each document being returned (including field data). By default this endpoint will only return summary information about each document (when workflow_id is POSTed – if document_id is POSTed then full information about that document will be supplied by default). Getting detailed information can reduce the number of calls you need to make (as you don't need to make a separate call for each document) but can increase the size of the returned XML which may be superfluous if you only want summary information about a document.
locations1, {null}When set to "1" this will return field value documents.
deleted1, {null}When set to "1" this will return all deleted documents.
days_to_check{integer}To which date you want to check, eg: 180
Information Circle

Important Requirements:

  • Either document_id OR workflow_id must be provided (⚠️ indicates at least one is required)
  • When using any_user_documents: set to 1 to get documents from all users, 0 to get only current user's documents

Code Examples

These examples request JSON and use placeholder values. Send either document_id or workflow_id, not both.

Warning

Keep your API key on a trusted server. Do not embed it in browser or React client code.

Get one document

Use document_id when you know the Xtracta document ID.

curl --request POST 'https://api-app.xtracta.com/v1/documents' \
  --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 'detailed=1'

List documents for a workflow

Use workflow_id with pagination to retrieve documents from a workflow.

curl --request POST 'https://api-app.xtracta.com/v1/documents' \
  --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 'page=1' \
  --data-urlencode 'items_per_page=100' \
  --data-urlencode 'detailed=1'

Sample Requests

By document_id

POST https://api-app.xtracta.com/v1/documents HTTP/1.1
api_key=123&document_id=228004&detailed=1

By workflow_id

POST https://api-app.xtracta.com/v1/documents HTTP/1.1
api_key=123&workflow_id=595&page=1&items_per_page=20

Sample Responses

By document_id

<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
  <status>200</status>
  <message>The request has been successfully processed</message>
  <document revision="2">
    <document_id>228004</document_id>
    <document_status>output</document_status>
    <number_of_pages>1</number_of_pages>
    <api_download_status>active</api_download_status>
    <free_form></free_form>
    <classification>full</classification>
    <classification_class>12</classification_class>
    <classification_design>34</classification_design>
    <document_url>https://example.xtracta.com/document.pdf</document_url>
    <image_url>https://example.xtracta.com/page-1.png</image_url>
    <image_skew>0.25</image_skew>
    <delete>0</delete>
    <ocr_data_url>https://example.xtracta.com/ocr-data</ocr_data_url>
    <ocr_text_url>https://example.xtracta.com/ocr-text</ocr_text_url>
    <field_data>
      <field><field_id>101</field_id><field_name>Invoice Number</field_name><field_value>INV-1001</field_value><field_extraction_confidence>98</field_extraction_confidence></field>
      <field_set><field_set_id>20</field_set_id><field_set_name>Line Items</field_set_name><row><field><field_id>201</field_id><field_name>Description</field_name><field_value>Service</field_value><field_extraction_confidence>95</field_extraction_confidence></field></row></field_set>
    </field_data>
    <siblings_documents></siblings_documents>
    <parent_document></parent_document>
  </document>
  <workflow_id>595</workflow_id>
</documents_response>

By workflow_id

<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
	<status>200</status>
	<message>The request has been successfully processed</message>
	<workflow_id>595</workflow_id>
	<documents_matching_query>3</documents_matching_query>
	<documents_number>
		<total>3</total>
		<usage-allowance-depleted>0</usage-allowance-depleted>
		<pre-processing>0</pre-processing>
		<indexing>3</indexing>
		<qa>0</qa>
		<reject>0</reject>
		<output-in-progress>0</output-in-progress>
		<completed>0</completed>
		<prelearning>0</prelearning>
		<learning>0</learning>
	</documents_number>
	<items_per_page>20</items_per_page>
	<page>1</page>
	<document revision="2">
		<document_id>228004</document_id>
		<document_status>indexing</document_status>
		<number_of_pages>1</number_of_pages>
		<api_download_status>active</api_download_status>
		<free_form/>
		<classification/>
		<classification_class>awaiting classification</classification_class>
		<classification_design>undetected</classification_design>
		<siblings_documents/>
		<parent_document/>
	</document>
	<document revision="2">
		<document_id>228003</document_id>
		<document_status>indexing</document_status>
		<number_of_pages>1</number_of_pages>
		<api_download_status>active</api_download_status>
		<free_form/>
		<classification/>
		<classification_class>awaiting classification</classification_class>
		<classification_design>undetected</classification_design>
		<siblings_documents/>
		<parent_document/>
	</document>
	<document revision="2">
		<document_id>228002</document_id>
		<document_status>indexing</document_status>
		<number_of_pages>1</number_of_pages>
		<api_download_status>active</api_download_status>
		<free_form/>
		<classification/>
		<classification_class>awaiting classification</classification_class>
		<classification_design>undetected</classification_design>
		<siblings_documents/>
		<parent_document/>
	</document>
</documents_response>

Schema Definition

The XML and JSON schemas below cover both selector forms, detailed and summary documents, empty collections, document relationships, rejection details, and status/message-only error responses.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:simpleType name="DocumentStatusType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="pre-processing"/>
      <xs:enumeration value="indexing"/>
      <xs:enumeration value="qa"/>
      <xs:enumeration value="reject"/>
      <xs:enumeration value="output"/>
      <xs:enumeration value="output-in-progress"/>
      <xs:enumeration value="api-ui-in-progress"/>
      <xs:enumeration value="prelearning"/>
      <xs:enumeration value="learning"/>
      <xs:enumeration value="usage-allowance-depleted"/>
      <xs:enumeration value="auto-separate"/>
      <xs:enumeration value="error"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="EmptyableDecimalType">
    <xs:union memberTypes="xs:decimal">
      <xs:simpleType><xs:restriction base="xs:string"><xs:length value="0"/></xs:restriction></xs:simpleType>
    </xs:union>
  </xs:simpleType>
  <xs:simpleType name="ConfidenceType">
    <xs:union>
      <xs:simpleType><xs:restriction base="xs:decimal"><xs:minInclusive value="0"/><xs:maxInclusive value="100"/></xs:restriction></xs:simpleType>
      <xs:simpleType><xs:restriction base="xs:string"><xs:length value="0"/></xs:restriction></xs:simpleType>
    </xs:union>
  </xs:simpleType>
  <xs:complexType name="DocumentsNumberType"><xs:sequence>
    <xs:element name="total" type="xs:nonNegativeInteger"/>
    <xs:element name="usage-allowance-depleted" type="xs:nonNegativeInteger"/>
    <xs:element name="pre-processing" type="xs:nonNegativeInteger"/>
    <xs:element name="indexing" type="xs:nonNegativeInteger"/>
    <xs:element name="qa" type="xs:nonNegativeInteger"/>
    <xs:element name="reject" type="xs:nonNegativeInteger"/>
    <xs:element name="output-in-progress" type="xs:nonNegativeInteger"/>
    <xs:element name="completed" type="xs:nonNegativeInteger"/>
    <xs:element name="prelearning" type="xs:nonNegativeInteger"/>
    <xs:element name="learning" type="xs:nonNegativeInteger"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="WordType"><xs:sequence>
    <xs:element name="page_number" type="xs:positiveInteger"/>
    <xs:element name="left" type="xs:decimal"/><xs:element name="top" type="xs:decimal"/>
    <xs:element name="width" type="xs:decimal"/><xs:element name="height" type="xs:decimal"/>
    <xs:element name="value" type="xs:string"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="FieldValueLocationType"><xs:sequence>
    <xs:element name="word" type="WordType" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="FieldType"><xs:sequence>
    <xs:element name="field_id" type="xs:positiveInteger"/>
    <xs:element name="field_name" type="xs:string"/>
    <xs:element name="field_value" type="xs:string" nillable="true"/>
    <xs:element name="field_extraction_confidence" type="ConfidenceType" nillable="true"/>
    <xs:element name="field_value_location" type="FieldValueLocationType" minOccurs="0"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="RowType"><xs:sequence>
    <xs:element name="field" type="FieldType" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="FieldSetType"><xs:sequence>
    <xs:element name="field_set_id" type="xs:positiveInteger"/>
    <xs:element name="field_set_name" type="xs:string"/>
    <xs:element name="field" type="FieldType" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="row" type="RowType" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="FieldDataType"><xs:sequence>
    <xs:element name="field" type="FieldType" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="field_set" type="FieldSetType" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="ValidationRuleType"><xs:sequence><xs:element name="type" type="xs:string"/></xs:sequence></xs:complexType>
  <xs:complexType name="LinkedFieldType"><xs:sequence><xs:element name="field_id" type="xs:string"/></xs:sequence></xs:complexType>
  <xs:complexType name="ReasonType"><xs:sequence>
    <xs:element name="message" type="xs:string"/><xs:element name="validation_rule" type="ValidationRuleType"/>
    <xs:element name="linked_field" type="LinkedFieldType"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="RejectionType"><xs:sequence><xs:element name="reason" type="ReasonType" maxOccurs="unbounded"/></xs:sequence></xs:complexType>
  <xs:complexType name="SiblingType"><xs:sequence>
    <xs:element name="document_id" type="xs:positiveInteger"/><xs:element name="number_of_page" type="xs:nonNegativeInteger"/>
    <xs:element name="document_url" type="xs:string"/><xs:element name="image_url" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="SiblingsType"><xs:sequence><xs:element name="sibling" type="SiblingType" minOccurs="0" maxOccurs="unbounded"/></xs:sequence></xs:complexType>
  <xs:complexType name="ParentType"><xs:sequence>
    <xs:element name="document_id" type="xs:positiveInteger" minOccurs="0"/><xs:element name="document_url" type="xs:string" minOccurs="0"/>
  </xs:sequence></xs:complexType>
  <xs:complexType name="DocumentType"><xs:sequence>
    <xs:element name="workflow_id" type="xs:positiveInteger" minOccurs="0"/>
    <xs:element name="document_id" type="xs:positiveInteger"/><xs:element name="document_status" type="DocumentStatusType"/>
    <xs:element name="number_of_pages" type="xs:positiveInteger" minOccurs="0"/>
    <xs:element name="api_download_status" type="xs:string" minOccurs="0"/>
    <xs:element name="free_form" type="xs:string" minOccurs="0" nillable="true"/>
    <xs:element name="classification" type="xs:string" minOccurs="0" nillable="true"/>
    <xs:element name="classification_class" type="xs:string" minOccurs="0"/>
    <xs:element name="classification_design" type="xs:string" minOccurs="0"/>
    <xs:element name="document_url" type="xs:string" minOccurs="0"/>
    <xs:element name="image_url" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="image_skew" type="EmptyableDecimalType" minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="delete" type="xs:nonNegativeInteger" minOccurs="0"/>
    <xs:element name="ocr_data_url" type="xs:string" minOccurs="0"/><xs:element name="ocr_text_url" type="xs:string" minOccurs="0"/>
    <xs:element name="field_data" type="FieldDataType" minOccurs="0"/>
    <xs:element name="rejection" type="RejectionType" minOccurs="0"/>
    <xs:element name="siblings_documents" type="SiblingsType" minOccurs="0"/>
    <xs:element name="parent_document" type="ParentType" minOccurs="0"/>
  </xs:sequence><xs:attribute name="revision" type="xs:positiveInteger" use="required"/></xs:complexType>
  <xs:element name="documents_response"><xs:complexType><xs:sequence>
    <xs:element name="status" type="xs:positiveInteger"/><xs:element name="message" type="xs:string"/>
    <xs:choice minOccurs="0">
      <xs:sequence>
        <xs:element name="workflow_id" type="xs:positiveInteger"/><xs:element name="documents_matching_query" type="xs:nonNegativeInteger"/>
        <xs:element name="documents_number" type="DocumentsNumberType" minOccurs="0"/>
        <xs:element name="items_per_page" type="xs:positiveInteger"/><xs:element name="page" type="xs:positiveInteger"/>
        <xs:element name="document" type="DocumentType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:sequence><xs:element name="document" type="DocumentType" maxOccurs="unbounded"/><xs:element name="workflow_id" type="xs:positiveInteger"/></xs:sequence>
    </xs:choice>
  </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 both the HTTP status code and a message.

StatusMessageDescription
400Neither valid workflow_id nor document_id is specifiedSupply one valid selector: workflow_id or document_id.
400<parameter> must be natural numberworkflow_id, document_id, page, and items_per_page must be positive integers.
400<parameter> must be '0' or '1'Boolean options such as any_user_documents, detailed, locations, deleted, and skew_angle accept only 0 or 1.
400document_status must be one of the values of [...]Use a supported document status.
400api_download_status must be one of the values of [active,archived]Use active or archived.
400items_per_page must be less than 1000Reduce the requested page size. The maximum is 1,000 for XML/JSON.
400documents_order must be one of the values of [asc,desc]Use asc or desc.
400days_to_check must be counting number 0-XXXXXXUse a non-negative integer.
400Specified field name is not found(...)A requested fields value is not a field in the selected workflow.
400Repeating field is not valid for response field(...)Remove the repeating field from fields for this response shape.
403This document is not available because of the billing issue.The selected document is in a billing-pending state. Resolve the billing issue, then retry.
404No documents foundThe request was valid but no document visible to this API application matched it. Check the selector, filters, API-key access, and whether deleted documents require deleted=1.
500Internal server error occurred. Please try again later or contact support@xtracta.comRetry the request. If it persists, contact support with the request timestamp and endpoint.
Information Circle

Authentication and access errors: requests rejected before this endpoint runs can return authentication, permission, IP-access-control, or rate-limit errors. Confirm that the API key is active, permitted for this controller and resource, and that the caller IP is allowed.