Update Document
This endpoint allows you to update a single document with one or two parameters within the Xtracta App. These parameters are mainly designed to allow you to track which documents have been downloaded by your application to ensure processed documents are not picked up for re-downloading.
POST Parameters
| Parameter | Required | Value | Description |
|---|---|---|---|
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. | |
new_workflow_id | {integer} | The ID of a specific workflow that you would like to reassign the document to. | |
api_download_status | active, archived | Define 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. | |
document_status | indexing, qa, reject, output, re-extract, re-ocr, complete reprocess, learning | Shift the document to a different status. This will override any validations set in the Xtracta App workflow for that document. | |
reason | {unicode} | Attach an arbitrary rejection reason to the document. Useful if you run pre-import validation which has requirements that the Xtracta App validation system does not support – you can move the document into rejection status and alert the user to what they need to fix. | |
free_form | {unicode} | Allows you to add any value to the field you want. This could be used for your own tracking purposes. | |
delete | {integer} | null – no value, 0 – restore document, 1 – delete document | |
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. Before passing a custom classification please contact one of our support technicians for assistance. | |
validation | {integer} | Enable the validations to run for this document once submitted. | |
learning | {integer} | Enable the learning for this document. This flag should be used with field_data parameter. | |
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. |
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.
Document Status Override: Using document_status parameter will override workflow validations. Use validation=1 to re-enable validations after status change.
Example of field_data for above case
<?xml version="1.0" encoding="UTF-8"?>
<documents_response>
<status>200</status>
<message>The request has been successfully processed</message>
</documents_response>
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.
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/update' \ --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 'api_download_status=archived'
Sample Request
POST https://api-app.xtracta.com/v1/documents/update HTTP/1.1 api_key=123&document_id=456789&api_download_status=archived
Sample Response
<?xml version="1.0" encoding="UTF-8"?> <documents_response> <status>200</status> <message>The request has been successfully processed</message> </documents_response>
Schema Definition
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<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:positiveInteger"/></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:element name="documents_response"><xs:complexType><xs:sequence>
<xs:element name="status" type="xs:positiveInteger"/><xs:element name="message" type="xs:string"/>
<xs:element name="error" type="xs:string" minOccurs="0"/><xs:element name="rejection" type="RejectionType" minOccurs="0"/>
</xs:sequence></xs:complexType></xs:element>
</xs:schema>
Archiving Note: When a document is archived via the API, the archival is specific to the API key used. If you have multiple API keys, the document can have a status of "active" with one API key and "archived" with others.
Error Responses
| Status | Message | Description |
|---|---|---|
400 | document_id is required / document_id must be natural number | Supply the positive integer document ID to update. |
400 | <parameter> must be '0' or '1' | Boolean options such as delete, validation, learning, acknowledge, and force_reprocess accept only 0 or 1. |
400 | api_download_status must be one of the values of [active,archived] | Use active or archived. |
400 | Document already acknowledged / Document not in error status to acknowledge | acknowledge=1 applies only once and only to an eligible error document. |
400 | Update failed due to validation error. | Correct the submitted field data or validation issue; the response includes the validation details. |
403 | Document is not in valid status to process this request (...) | The document cannot be updated in its current processing state. |
403 | This document is not available because of the billing issue. | Resolve the billing issue, then retry. |
404 | No documents found | Check the document ID and API-key access. |
409 | Document is being processed by someone else | Wait for the existing user/session to finish, or use the supported lockout option where applicable. |
500 | Internal server error occurred. Please try again later or contact support@xtracta.com | Retry and contact support with the request timestamp if it persists. |
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.