> ## Documentation Index > Fetch the complete documentation index at: https://developers.useqx.com/llms.txt > Use this file to discover all available pages before exploring further. # Write fields or send the file > Makes one of two changes to a document. With `fields`, in JSON, the call writes the field answers, and the written value wins over the value that the reading extracted. A document in Triage goes back to the routing, and the collection of the document runs the validations again. With `file`, in `multipart/form-data`, the call sends the file of a document in an open collection, and the reading starts. On a document without a file, the call attaches the file to the same document and responds `200`. On a document with a file, the call makes a file swap and responds `201`. The file swap creates a new document with the file, and the `Location` header contains the path of the new document. The old document stays as the previous version, with its file, its state and its reading. The file swap also applies to an approved document, while the collection accepts documents. A call with `file` counts toward the paid write limit of the key and accepts the `Idempotency-Key` header. ## OpenAPI ````yaml /en/openapi.yaml patch /documents/{id} openapi: 3.1.0 info: title: QX API version: 1.0.0 description: >- The QX API creates and reads the contacts, the collections and the documents of the organization, and it lists the packs. Each call carries the API key of the organization. The API sends each error in the RFC 9457 format (`application/problem+json`), with a stable `code`. In addition to the errors of each endpoint, any path under `/api/v1` can return these errors: - `404` with `route_not_found`: the API does not have the path, or the path does not accept the HTTP method. - `405` with `method_not_allowed`: the API does not recognize the HTTP method. - `406` with `not_acceptable`: the API does not recognize the `Content-Type` or the `Accept` of the call. - another `4xx` status with `request_refused`: the API could not complete the call. - a `5xx` status with `internal_error`: QX had an internal error. servers: - url: https://app.useqx.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Collections description: >- The collections of the organization. A collection asks the contact for the documents of a pack. - name: Contacts description: >- The people and the companies of the organization. A person has a CPF, and a company has a CNPJ. - name: Documents description: >- The documents of the organization. A document sent without a collection goes to Triage. A document sent with a collection fills the slot of its type. - name: Packs description: The packs of the organization and the requirements of each pack. paths: /documents/{id}: patch: tags: - Documents summary: Write fields or send the file description: >- Makes one of two changes to a document. With `fields`, in JSON, the call writes the field answers, and the written value wins over the value that the reading extracted. A document in Triage goes back to the routing, and the collection of the document runs the validations again. With `file`, in `multipart/form-data`, the call sends the file of a document in an open collection, and the reading starts. On a document without a file, the call attaches the file to the same document and responds `200`. On a document with a file, the call makes a file swap and responds `201`. The file swap creates a new document with the file, and the `Location` header contains the path of the new document. The old document stays as the previous version, with its file, its state and its reading. The file swap also applies to an approved document, while the collection accepts documents. A call with `file` counts toward the paid write limit of the key and accepts the `Idempotency-Key` header. operationId: updateDocument parameters: - $ref: '#/components/parameters/DocumentId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DocumentFieldsInput' examples: fields: summary: Writes the Incoterm of the invoice value: fields: incoterm: CFR multipart/form-data: schema: $ref: '#/components/schemas/DocumentFileInput' examples: file: summary: Attaches the packing list to the empty slot of the collection value: file: romaneio.pdf swap: summary: Swaps the file of the invoice value: file: fatura-corrigida.pdf responses: '200': description: The document, with the fields. content: application/json: schema: $ref: '#/components/schemas/Document' examples: fields: summary: The invoice with the written Incoterm value: id: doc_318 document_type: id: dtp_31 name: Fatura Comercial (Commercial Invoice) status: uploaded reading_status: complete contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null replaced_by: null number: INV-81244/2026 arrival_channel: api arrived_at: '2026-09-25T10:32:05.000-03:00' files: - name: fatura.pdf content_type: application/pdf size: 182044 created_at: '2026-09-25T10:32:05.000-03:00' fields: - key: invoice_number label: Número da Fatura value: INV-81244/2026 - key: invoice_date label: Data da Fatura value: '2026-09-18' - key: exporter_name label: Exportador (Vendedor) value: Shanghai Example Trading Co., Ltd. - key: invoice_amount label: Valor da Fatura value: 48,250.00 - key: currency label: Moeda value: USD - key: incoterm label: Incoterm value: CFR - key: line_items label: Itens da Fatura value: - part_number: A-100 description: STAINLESS STEEL VALVE 1/2 IN quantity: '1000' quantity_unit: PCS unit_price: '25.00' total_price: 25,000.00 - part_number: B-220 description: BRASS FITTING 3/4 IN quantity: '500' quantity_unit: PCS unit_price: '46.50' total_price: 23,250.00 file: summary: The packing list fills the slot, and the reading starts value: id: doc_312 document_type: id: dtp_33 name: Romaneio de Carga (Packing List) status: uploaded reading_status: extracting contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null replaced_by: null number: null arrival_channel: api arrived_at: '2026-09-25T11:05:47.000-03:00' files: - name: romaneio.pdf content_type: application/pdf size: 96512 created_at: '2026-09-25T10:31:12.000-03:00' fields: - key: packing_list_number label: Número do Romaneio value: null - key: packing_list_date label: Data do Romaneio value: null - key: invoice_numbers label: Faturas Referenciadas value: null '201': description: >- The file swap created a new document. The body contains the new document, with the fields, and the `Location` header contains its path. headers: Location: $ref: '#/components/headers/Location' content: application/json: schema: $ref: '#/components/schemas/Document' examples: swap: summary: >- The new invoice arrives with the corrected file, and the reading starts value: id: doc_325 document_type: id: dtp_31 name: Fatura Comercial (Commercial Invoice) status: uploaded reading_status: extracting contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null replaced_by: null number: null arrival_channel: api arrived_at: '2026-09-26T09:14:22.000-03:00' files: - name: fatura-corrigida.pdf content_type: application/pdf size: 184310 created_at: '2026-09-26T09:14:22.000-03:00' fields: - key: invoice_number label: Número da Fatura value: null - key: invoice_date label: Data da Fatura value: null - key: exporter_name label: Exportador (Vendedor) value: null - key: invoice_amount label: Valor da Fatura value: null - key: currency label: Moeda value: null - key: incoterm label: Incoterm value: CFR - key: line_items label: Itens da Fatura value: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- The document does not accept the change. `document_has_content`: the document is in Triage and already has a file or an answer, and the call included `file`. `document_locked`: the document is discarded, or its collection does not accept documents. A call with `fields` also gets `document_locked` on an approved document. A call with `file` also gets `document_locked` on an approved document without a file and on a Triage document without a file. `document_replaced`: the document is a previous version, and the `replaced_by` field contains the id of the current document. The API also returns `409` when another call with the same `Idempotency-Key` is still in progress. content: application/problem+json: schema: anyOf: - allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - document_has_content - document_locked - $ref: '#/components/schemas/DocumentReplacedProblem' - $ref: '#/components/schemas/IdempotencyKeyInUseProblem' examples: document_has_content: summary: The Triage document already has a file value: type: about:blank title: Conflict status: 409 detail: >- The Triage document already has a file or an answer. The API swaps the file only on a collection document. code: document_has_content document_replaced: summary: The document is a previous version value: type: about:blank title: Conflict status: 409 detail: >- The document is a previous version. The replaced_by field contains the id of the current document. code: document_replaced replaced_by: doc_325 idempotency_key_in_use: $ref: '#/components/examples/IdempotencyKeyInUse' '413': $ref: '#/components/responses/FileTooLarge' '422': description: >- A field has an error, and the `errors` list gives the error of each field. The API also returns this response in three cases: the type has no field with the key, the type is a form without a file field, or the file format does not suit the type. The API writes no change. The API also returns `422` when the `Idempotency-Key` already served a call with different content. content: application/problem+json: schema: anyOf: - $ref: '#/components/schemas/ValidationProblem' - $ref: '#/components/schemas/DocumentUpdateRefusedProblem' - $ref: '#/components/schemas/IdempotencyKeyReusedProblem' examples: unknown_field: summary: The type has no field with the key value: type: about:blank title: Unprocessable Content status: 422 detail: >- The document type has no field with this key. The GET of the document lists the keys of the fields. code: unknown_field validation_failed: summary: The value has the wrong shape for this field value: type: about:blank title: Unprocessable Content status: 422 detail: >- One or more fields have an error. The errors list gives the error of each field. code: validation_failed errors: - field: fields.line_items code: invalid message: >- The value does not have the shape of the field. A list field and a table field take a list, and the other fields take a string. idempotency_key_reused: $ref: '#/components/examples/IdempotencyKeyReused' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: DocumentId: name: id in: path required: true description: The id of the document. The id starts with `doc_`. schema: type: string example: doc_310 IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A unique value that your system creates for each write, such as a UUID. A repeated call with the same value and the same content gets the first response, and the API writes nothing new. The API keeps the response for 24 hours. schema: type: string minLength: 1 maxLength: 255 example: 5f0c7e8a-3a1b-4d2e-9c61-2b7f4e0d9a13 schemas: DocumentFieldsInput: type: object additionalProperties: false required: - fields properties: fields: type: object minProperties: 1 description: >- The field answers, in the `{ "key": value }` format, with at least one key. The key is the `key` of a field in `GET /documents/{id}`. The value has the shape of the `value` of that field, and `null` erases the answer. additionalProperties: $ref: '#/components/schemas/DocumentFieldValue' examples: - invoice_number: INV-81244/2026 DocumentFileInput: type: object additionalProperties: false required: - file properties: file: type: string format: binary description: >- The file of the empty slot, up to 25 MB. The file field of the type decides the accepted formats. Document: description: A document, with the fields. allOf: - $ref: '#/components/schemas/DocumentFields' - type: object required: - fields properties: fields: type: array description: >- The fields of the document type, in the catalog order, without the file fields. A field without an answer has `value` equal to `null`. items: $ref: '#/components/schemas/DocumentField' unevaluatedProperties: false Problem: type: object description: An error in the RFC 9457 format. required: - type - title - status - detail - code properties: type: type: string const: about:blank description: Always `about:blank`. title: type: string description: The phrase of the HTTP status, in English. examples: - Unauthorized status: type: integer description: The HTTP status. examples: - 401 detail: type: string description: >- The explanation of the error, in the language of the organization. An answer that leaves before the key identifies the organization stays in Portuguese. code: type: string description: >- The error code, in English. The code does not change between versions of v1. DocumentReplacedProblem: description: >- The document is a previous version. The `replaced_by` field contains the id of the current document. allOf: - $ref: '#/components/schemas/Problem' - type: object required: - replaced_by properties: code: enum: - document_replaced replaced_by: type: string pattern: ^doc_[1-9][0-9]*$ description: The id of the current document. examples: - doc_325 IdempotencyKeyInUseProblem: description: Another call with the same `Idempotency-Key` is still in progress. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - idempotency_key_in_use ValidationProblem: description: A validation error. The `errors` list gives the error of each field. allOf: - $ref: '#/components/schemas/Problem' - type: object required: - errors properties: code: enum: - validation_failed errors: type: array items: $ref: '#/components/schemas/FieldError' DocumentUpdateRefusedProblem: description: >- The type has no field with the key, the type is a form without a file field, or the file format does not suit the type. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - unknown_field - document_type_without_file - unsupported_file description: >- `unknown_field`: the document type has no field with the key. `document_type_without_file`: the document type is a form without a file field. `unsupported_file`: the file format does not suit the document type. IdempotencyKeyReusedProblem: description: The `Idempotency-Key` already served a call with different content. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - idempotency_key_reused DocumentFieldValue: description: >- The answer of a field. A text field, a number field, a date field and an option field hold a string. A list field holds a list of strings. A table field holds a list of rows, and each row maps the column key to the cell string. anyOf: - type: string - type: number - type: boolean - type: array items: anyOf: - type: string - type: object additionalProperties: type: string - type: 'null' DocumentFields: type: object description: The fields of every document. required: - id - document_type - status - reading_status - contact - collection_id - in_triage - discarded - discard_reason - replaced_by - number - arrival_channel - arrived_at - files - created_at properties: id: type: string pattern: ^doc_[1-9][0-9]*$ description: The id of the document. examples: - doc_310 document_type: $ref: '#/components/schemas/DocumentTypeReference' status: $ref: '#/components/schemas/DocumentStatus' reading_status: type: string enum: - not_started - extracting - enriching - validating - complete - failed - no_reader description: >- The progress of the reading of the document. `not_started`: the reading did not start. `extracting`, `enriching` and `validating`: the reading is in progress. `complete`: the reading ended. `failed`: the reading failed. `no_reader`: the document type has no reading. contact: description: >- The contact of the document. The value is `null` when the document has no contact. anyOf: - $ref: '#/components/schemas/CollectionContact' - type: 'null' collection_id: type: - string - 'null' pattern: ^col_[1-9][0-9]*$ description: >- The id of the collection of the document. The value is `null` while the document is in Triage. examples: - col_40 in_triage: type: boolean description: With `true`, the document is in Triage and has no collection yet. discarded: type: boolean description: With `true`, the document is discarded. discard_reason: type: - string - 'null' enum: - outside_pack - identical_copy - superseded - operator - replaced - null description: >- The reason for the discard. The value is `null` on a document that is not discarded. `outside_pack`: no active operation pack asks for the type of the document. `identical_copy`: the document repeats the file of another document. `superseded`: a newer document replaced this document. `operator`: the operator discarded the document. `replaced`: a file swap created a new document, and this document stayed as the previous version. replaced_by: type: - string - 'null' pattern: ^doc_[1-9][0-9]*$ description: >- In the previous version of a file swap, the id of the current document. The current document is the last document in the chain of file swaps. On the other documents, the value is `null`. examples: - doc_325 number: type: - string - 'null' description: >- The printed number that identifies the document, such as the invoice number. The value is `null` before the reading. examples: - INV-81244/2026 arrival_channel: type: - string - 'null' enum: - email - portal_upload - operator_upload - spreadsheet - vault - api - null description: >- The arrival channel of the file. The value is `null` on an empty slot. `email`: the file arrived by email. `portal_upload`: the client sent the file on the portal. `operator_upload`: the operator sent the file on the QX screen. `spreadsheet`: the file came from a spreadsheet. `vault`: the client reused a file from the Vault on the portal. `api`: the file arrived through the API. arrived_at: type: - string - 'null' format: date-time description: >- The date and the time when the file arrived, in the time zone of the organization. The value is `null` on an empty slot. files: type: array description: The files of the document. On an empty slot, the list is empty. items: $ref: '#/components/schemas/DocumentFile' created_at: type: string format: date-time description: >- The date and the time of the creation, in the time zone of the organization. examples: - '2026-09-25T10:30:00.000-03:00' DocumentField: type: object additionalProperties: false required: - key - label - value properties: key: type: string description: The key of the field. The `PATCH` uses this key in `fields`. examples: - invoice_number label: type: string description: The label of the field, as the screen shows it. examples: - Número da Fatura value: $ref: '#/components/schemas/DocumentFieldValue' description: >- The answer of the field. The value is `null` when the field has no answer. FieldError: type: object additionalProperties: false required: - field - code - message properties: field: type: string description: The name of the field with the error. code: type: string description: The error code of the field, in English. message: type: string description: >- The explanation of the field error, in the language of the organization. DocumentTypeReference: type: object additionalProperties: false required: - id - name properties: id: type: string pattern: ^dtp_[1-9][0-9]*$ description: The id of the document type. examples: - dtp_31 name: type: string description: The name of the document type. examples: - Fatura Comercial (Commercial Invoice) DocumentStatus: type: string enum: - pending - uploaded - approved - rejected description: >- The progress of the document. `pending`: the document waits for the upload. `uploaded`: the document arrived and waits for the review. `approved`: the operator approved the document. `rejected`: the operator rejected the document. CollectionContact: type: object additionalProperties: false required: - id - type - name properties: id: type: string pattern: ^(per|com)_[1-9][0-9]*$ description: The id of the contact. examples: - com_12 type: type: string enum: - person - company description: '`person` for a person and `company` for a company.' name: type: - string - 'null' description: The name of the contact. examples: - Importadora Exemplo Ltda DocumentFile: type: object additionalProperties: false required: - name - content_type - size properties: name: type: string description: The name of the file. examples: - fatura.pdf content_type: type: - string - 'null' description: The MIME type of the file. examples: - application/pdf size: type: integer description: The size of the file, in bytes. examples: - 182044 headers: Location: description: The path of the new document. required: true schema: type: string example: /api/v1/documents/doc_325 WwwAuthenticate: description: The authentication scheme that the API expects. required: true schema: type: string example: Bearer realm="QX API" RetryAfter: description: The seconds to wait before the next call. required: true schema: type: integer minimum: 1 responses: BadRequest: description: >- The API refused the call. The `code` gives the reason: - `invalid_parameter`: a parameter is missing or has an invalid value. - `malformed_request`: the API could not read the call. Examples of causes: - the path or the query has an invalid encoding; - the query repeats a parameter in different forms, such as `limit=1&limit[]=2`; - the body is not valid JSON; - the address in the `Client-IP` header is not in the `X-Forwarded-For` header. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - invalid_parameter - malformed_request examples: invalid_parameter: summary: The limit is above 100 value: type: about:blank title: Bad Request status: 400 detail: The limit parameter has an invalid value. code: invalid_parameter malformed_request: $ref: '#/components/examples/MalformedRequest' Unauthorized: description: The key is missing, does not exist or is revoked. headers: WWW-Authenticate: $ref: '#/components/headers/WwwAuthenticate' content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - unauthorized examples: unauthorized: summary: The key is missing or not valid value: type: about:blank title: Unauthorized status: 401 detail: >- The call did not include a valid API key. Send the key in the Authorization header, in the format Bearer . code: unauthorized PaymentRequired: description: The subscription of the organization is blocked. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - subscription_blocked examples: subscription_blocked: summary: The subscription is blocked value: type: about:blank title: Payment Required status: 402 detail: >- The subscription of the organization is blocked. Settle the payment in QX to use the API. code: subscription_blocked Forbidden: description: >- The organization is archived, or the plan of the organization does not include the API. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - organization_archived - plan_required examples: plan_required: summary: The free plan does not include the API value: type: about:blank title: Forbidden status: 403 detail: >- The free plan does not include the API. Subscribe to a paid plan in QX to use the API. code: plan_required NotFound: description: The resource does not exist in the key's organization. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - not_found examples: not_found: $ref: '#/components/examples/NotFound' FileTooLarge: description: >- The file is larger than 25 MB, or larger than 10 MB for a type without a file field. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - file_too_large examples: file_too_large: summary: The file is larger than the maximum size value: type: about:blank title: Content Too Large status: 413 detail: >- The file is larger than the maximum size. The limit is 25 MB per file, and 10 MB for a type without a file field. code: file_too_large TooManyRequests: description: The key or the IP address went over a limit. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - rate_limited - daily_limit_reached - too_many_invalid_keys examples: rate_limited: summary: The key went over the per-minute limit value: type: about:blank title: Too Many Requests status: 429 detail: >- The key went over a per-minute limit. Wait for the seconds in the Retry-After header and call again. code: rate_limited examples: IdempotencyKeyInUse: summary: Another call with the same Idempotency-Key is in progress value: type: about:blank title: Conflict status: 409 detail: >- Another call with this Idempotency-Key is still in progress. Wait for that call to end and call again. code: idempotency_key_in_use IdempotencyKeyReused: summary: The Idempotency-Key already served another call value: type: about:blank title: Unprocessable Content status: 422 detail: >- This Idempotency-Key already served a call with different content. Use a new value for the new call. code: idempotency_key_reused MalformedRequest: summary: The API could not read the call value: type: about:blank title: Bad Request status: 400 detail: >- The API could not read the call. Check the shape and the encoding of the path and the query, the JSON of the body and the headers. code: malformed_request NotFound: summary: The id does not exist in the key's organization value: type: about:blank title: Not Found status: 404 detail: The resource does not exist in the key's organization. code: not_found securitySchemes: bearerAuth: type: http scheme: bearer description: >- The API key of the organization, in the `Authorization: Bearer ` header. The key starts with `qx_`. ````