> ## 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. # Read a collection > Reads a collection of the key's organization, with the documents of the collection. The call also finds an archived collection. ## OpenAPI ````yaml /en/openapi.yaml get /collections/{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: /collections/{id}: get: tags: - Collections summary: Read a collection description: >- Reads a collection of the key's organization, with the documents of the collection. The call also finds an archived collection. operationId: getCollection parameters: - name: id in: path required: true description: The id of the collection. The id starts with `col_`. schema: type: string example: col_40 responses: '200': description: The collection, with the documents. content: application/json: schema: $ref: '#/components/schemas/Collection' examples: invoice_arrived: summary: >- The collection after the arrival and the reading of the invoice value: id: col_40 protocol: DOC-2026-00123 state: assembling discarded: false contact: id: com_12 type: company name: Importadora Exemplo Ltda recipient: null packs: - id: pck_12 name: Importação marítima numbers: - INV-81244/2026 created_at: '2026-09-25T10:31:12.000-03:00' ready_at: null documents: - id: doc_311 document_type: id: dtp_32 name: Bill of Lading (B/L) status: pending has_content: false - id: doc_312 document_type: id: dtp_33 name: Romaneio de Carga (Packing List) status: pending has_content: false - id: doc_318 document_type: id: dtp_31 name: Fatura Comercial (Commercial Invoice) status: uploaded has_content: true '400': $ref: '#/components/responses/MalformedRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: Collection: description: A collection, with the list of documents. allOf: - $ref: '#/components/schemas/CollectionFields' - type: object required: - documents properties: documents: type: array description: >- The documents of the collection, from the oldest to the newest. The list does not include a discarded document. items: $ref: '#/components/schemas/CollectionDocument' unevaluatedProperties: false CollectionFields: type: object description: The fields of every collection. required: - id - protocol - state - discarded - contact - recipient - packs - numbers - created_at - ready_at properties: id: type: string pattern: ^col_[1-9][0-9]*$ description: The id of the collection. examples: - col_40 protocol: type: string description: The protocol of the collection. examples: - DOC-2026-00123 state: $ref: '#/components/schemas/CollectionState' discarded: type: boolean description: With `true`, the collection is archived. contact: description: >- The contact of the collection. The value is `null` on a collection without a contact, until the recipient identifies themselves. anyOf: - $ref: '#/components/schemas/CollectionContact' - type: 'null' recipient: description: >- The recipient of a collection created without a contact. On a collection created with a contact, the value is `null`. anyOf: - $ref: '#/components/schemas/CollectionRecipient' - type: 'null' packs: type: array description: The packs that the collection asks for. items: $ref: '#/components/schemas/PackReference' numbers: type: array description: >- The operation numbers, as the collection screen shows them. The list includes the numbers printed on the documents of the identifier requirements of the pack. Without these numbers, the list includes the numbers printed on the other documents of the collection. On a collection without an operation pack, the list is empty. items: type: string examples: - - INV-81244/2026 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' ready_at: type: - string - 'null' format: date-time description: >- The date and the time when the collection last became ready, in the time zone of the organization. The value is `null` when the collection never became ready. CollectionDocument: type: object additionalProperties: false required: - id - document_type - status - has_content 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: 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. has_content: type: boolean description: >- With `true`, the document has an attached file or a field with an answer. With `false`, the document is an empty slot. 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. CollectionState: type: string enum: - assembling - reviewing - ready_to_dispatch - awaiting_partner - cancelled description: >- The state of the collection. `assembling`: the collection is in assembly and waits for the documents. `reviewing`: the operator reviews the documents. `ready_to_dispatch`: every required document arrived, and no validation blocks the collection. `awaiting_partner`: the operator sent the collection to the partner. `cancelled`: the operator canceled the collection. 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 CollectionRecipient: type: object additionalProperties: false required: - name - email description: >- The recipient of a collection without a contact. The recipient gets the invitation and identifies themselves on the portal with the CPF or the CNPJ. Send the recipient only when the call has no `contact_id` and no `tax_id`. properties: name: type: string description: The name of the recipient. examples: - Importadora Exemplo Ltda email: type: string format: email description: The email of the recipient. examples: - fiscal@importadora.com.br PackReference: type: object additionalProperties: false required: - id - name properties: id: type: string pattern: ^pck_[1-9][0-9]*$ description: The id of the pack. examples: - pck_12 name: type: string description: The name of the pack. examples: - Importação marítima 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) responses: MalformedRequest: description: >- 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 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: - malformed_request examples: 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' 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: 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 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_`. ````