> ## 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. # Send a document > Sends the file of a document, with the contact and the document type. A call carries one file, and the file becomes one document. Without `collection_id`, the document goes to Triage, like a document that arrives by email. The reading starts, and the routing looks for a collection for the document when the reading ends. A document that the routing does not put in a collection waits in Triage. With `collection_id`, the document fills the empty slot of its type in the collection, and the reading starts. When every required document of the collection arrives, the collection moves to `reviewing`, and QX notifies the operators. The call counts toward the paid write limit of the key. ## OpenAPI ````yaml /en/openapi.yaml post /documents 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: post: tags: - Documents summary: Send a document description: >- Sends the file of a document, with the contact and the document type. A call carries one file, and the file becomes one document. Without `collection_id`, the document goes to Triage, like a document that arrives by email. The reading starts, and the routing looks for a collection for the document when the reading ends. A document that the routing does not put in a collection waits in Triage. With `collection_id`, the document fills the empty slot of its type in the collection, and the reading starts. When every required document of the collection arrives, the collection moves to `reviewing`, and QX notifies the operators. The call counts toward the paid write limit of the key. operationId: createDocument parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/DocumentInput' examples: collection: summary: The invoice of a collection value: file: fatura.pdf contact_id: com_12 document_type_id: dtp_31 collection_id: col_40 triage: summary: The invoice without a collection, by the CNPJ of the contact value: file: fatura.pdf tax_id: 12.345.678/0001-95 document_type_id: dtp_31 responses: '201': description: The new document, with the fields. content: application/json: schema: $ref: '#/components/schemas/Document' examples: collection: summary: >- The invoice fills the slot of the collection, and the reading starts value: id: doc_318 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-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: 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: null - key: line_items label: Itens da Fatura value: null triage: summary: The invoice goes to Triage, and the reading starts value: id: doc_319 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: null in_triage: true discarded: false discard_reason: null replaced_by: null number: null arrival_channel: api arrived_at: '2026-09-25T10:40:18.000-03:00' files: - name: fatura.pdf content_type: application/pdf size: 182044 created_at: '2026-09-25T10:40:18.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: null - 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': description: >- The contact of `contact_id`, the document type or the collection 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' '409': $ref: '#/components/responses/IdempotencyKeyInUseOrStale' '413': $ref: '#/components/responses/FileTooLarge' '422': description: >- A field has an error, or QX cannot accept the document with this contact, this type, this file and this collection. The `code` gives the reason, and the API creates no document. 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/DocumentRefusedProblem' - $ref: '#/components/schemas/IdempotencyKeyReusedProblem' examples: contact_mismatch: summary: The collection belongs to another contact value: type: about:blank title: Unprocessable Content status: 422 detail: >- The collection belongs to another contact. Send the document of the collection's contact, or send the document without collection_id. code: contact_mismatch validation_failed: summary: The call did not include the file 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: file code: blank message: Send the file of the document in the file field. idempotency_key_reused: $ref: '#/components/examples/IdempotencyKeyReused' '429': $ref: '#/components/responses/TooManyRequests' '503': description: >- QX could not store the file, and the API created no document. Repeat the call in a few seconds, with the same `Idempotency-Key`. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - storage_unavailable examples: storage_unavailable: summary: QX did not store the file value: type: about:blank title: Service Unavailable status: 503 detail: >- QX could not store the file now. The API created no document. Call again in a few seconds. code: storage_unavailable components: parameters: 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: DocumentInput: type: object additionalProperties: false required: - file - document_type_id properties: file: type: string format: binary description: >- The file of the document, up to 25 MB. QX accepts PDF, JPEG, PNG, TIFF, TXT, XLS, XLSX and XML. A type without a file field accepts only PDF, JPEG and PNG, up to 10 MB. contact_id: type: string description: >- The id of the contact of the document. Send the `contact_id` or the `tax_id`, only one of the two. examples: - com_12 tax_id: type: string description: >- The CPF or the CNPJ of the contact of the document, with or without punctuation. Send the `contact_id` or the `tax_id`, only one of the two. examples: - 12.345.678/0001-95 document_type_id: type: string description: >- The id of the document type. `GET /packs` lists the types that each pack asks for. examples: - dtp_31 collection_id: type: string description: >- The id of an open collection of the same contact. Without this field, the document goes to Triage. examples: - col_40 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. 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' DocumentRefusedProblem: description: >- QX cannot accept the document with this contact, this type, this file and this collection. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - contact_not_found - contact_archived - contact_mismatch - collection_not_accepting - document_type_inactive - document_type_without_file - unsupported_file description: >- `contact_not_found`: the organization has no contact with the `tax_id`. `contact_archived`: the contact is archived. `contact_mismatch`: the collection belongs to another contact. `collection_not_accepting`: the collection is canceled, archived or with the partner, or it has no contact yet. `document_type_inactive`: the document type is inactive or archived. `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 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. 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 StaleProblem: description: >- The data changed during the call. The call created no document and no collection. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - stale 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 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' 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 IdempotencyKeyInUseOrStale: description: >- The write found a conflict. The `code` tells which conflict. `idempotency_key_in_use`: another call with the same `Idempotency-Key` is still in progress. Wait for that call to end, and then repeat the call with the same value. `stale`: the data changed during the call. The call created no document and no collection. Call again. If the call included an `Idempotency-Key`, use a new value, because the API keeps the `409` response. content: application/problem+json: schema: anyOf: - $ref: '#/components/schemas/IdempotencyKeyInUseProblem' - $ref: '#/components/schemas/StaleProblem' examples: idempotency_key_in_use: $ref: '#/components/examples/IdempotencyKeyInUse' stale: $ref: '#/components/examples/Stale' 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: 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 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 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 Stale: summary: The data changed during the call value: type: about:blank title: Conflict status: 409 detail: >- The data changed during the call. The call created no document and no collection. Call again. If the call included an Idempotency-Key, use a new value. code: stale headers: 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- The API key of the organization, in the `Authorization: Bearer ` header. The key starts with `qx_`. ````