curl --request POST \
  --url https://app.useqx.com/api/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form contact_id=com_12 \
  --form document_type_id=dtp_31 \
  --form collection_id=col_40

{
  "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
    }
  ]
}

Documents

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.

POST

documents

curl --request POST \
  --url https://app.useqx.com/api/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form contact_id=com_12 \
  --form document_type_id=dtp_31 \
  --form collection_id=col_40

{
  "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
    }
  ]
}

Authorizations

Authorization

string

header

required

The API key of the organization, in the Authorization: Bearer <key> header. The key starts with qx_.

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Body

multipart/form-data

file

required

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.

document_type_id

string

required

The id of the document type. GET /packs lists the types that each pack asks for.

Example:

"dtp_31"

contact_id

string

The id of the contact of the document. Send the contact_id or the tax_id, only one of the two.

Example:

"com_12"

tax_id

string

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.

Example:

"12.345.678/0001-95"

collection_id

string

The id of an open collection of the same contact. Without this field, the document goes to Triage.

Example:

"col_40"

Response

The new document, with the fields.

A document, with the fields.

string

required

The id of the document.

Pattern: ^doc_[1-9][0-9]*$

Example:

"doc_310"

document_type

object

required

Show child attributes

status

enum<string>

required

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.

Available options:

pending,

uploaded,

approved,

rejected

reading_status

enum<string>

required

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.

Available options:

not_started,

extracting,

enriching,

validating,

complete,

failed,

no_reader

contact

object | null

required

The contact of the document. The value is null when the document has no contact.

Show child attributes

collection_id

string | null

required

The id of the collection of the document. The value is null while the document is in Triage.

Pattern: ^col_[1-9][0-9]*$

Example:

"col_40"

in_triage

boolean

required

With true, the document is in Triage and has no collection yet.

discarded

boolean

required

With true, the document is discarded.

discard_reason

enum<string> | null

required

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.

Available options:

outside_pack,

identical_copy,

superseded,

operator,

replaced,

null

replaced_by

string | null

required

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.

Pattern: ^doc_[1-9][0-9]*$

Example:

"doc_325"

number

string | null

required

The printed number that identifies the document, such as the invoice number. The value is null before the reading.

Example:

"INV-81244/2026"

arrival_channel

enum<string> | null

required

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.

Available options:

email,

portal_upload,

operator_upload,

spreadsheet,

vault,

api,

null

arrived_at

string<date-time> | null

required

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

object[]

required

The files of the document. On an empty slot, the list is empty.

Show child attributes

created_at

string<date-time>

required

The date and the time of the creation, in the time zone of the organization.

Example:

"2026-09-25T10:30:00.000-03:00"

fields

object[]

required

The fields of the document type, in the catalog order, without the file fields. A field without an answer has value equal to null.

Show child attributes

Getting started

Reference

Send a document

Authorizations

Headers

Body

Response