> ## 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. # Listar os contatos > Lista as pessoas e as empresas da organização da chave, do contato mais novo ao mais antigo. A lista não traz o contato arquivado nem o sócio que a consulta do CNPJ criou. Cada filtro reduz a lista, e os filtros valem juntos. ## OpenAPI ````yaml /openapi.yaml get /contacts openapi: 3.1.0 info: title: QX API version: 1.0.0 description: >- A API do QX cria e lê os contatos, as coletas e os documentos da organização e lista os pacotes. Cada chamada leva a chave de API da organização. servers: - url: https://app.useqx.com/api/v1 description: Produção security: - bearerAuth: [] tags: - name: Coletas description: >- As coletas da organização. A coleta pede ao contato os documentos de um pacote. - name: Contatos description: >- As pessoas e as empresas da organização. A pessoa tem um CPF, e a empresa tem um CNPJ. - name: Documentos description: >- Os documentos da organização. O documento enviado sem coleta entra na Triagem, e o documento enviado com coleta ocupa o slot do tipo. - name: Pacotes description: Os pacotes da organização e os requisitos de cada pacote. paths: /contacts: get: tags: - Contatos summary: Listar os contatos description: >- Lista as pessoas e as empresas da organização da chave, do contato mais novo ao mais antigo. A lista não traz o contato arquivado nem o sócio que a consulta do CNPJ criou. Cada filtro reduz a lista, e os filtros valem juntos. operationId: listContacts parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - name: tax_id in: query description: O CPF ou o CNPJ do contato, com ou sem pontuação. schema: type: string example: 12.345.678/0001-95 - name: email in: query description: >- O e-mail do contato. A busca compara o endereço inteiro e ignora a diferença entre maiúscula e minúscula. schema: type: string example: fiscal@importadora.com.br - name: name in: query description: >- Uma parte do nome do contato. A busca ignora a diferença entre maiúscula e minúscula. schema: type: string example: exemplo - name: type in: query description: >- Com `person`, a lista traz só as pessoas. Com `company`, a lista traz só as empresas. schema: type: string enum: - person - company example: company - name: created_from in: query description: >- A primeira data de criação, no formato `AAAA-MM-DD`. A data usa o fuso horário da organização, e o dia inteiro entra na lista. schema: type: string format: date example: '2026-09-01' - name: created_to in: query description: >- A última data de criação, no formato `AAAA-MM-DD`. A data usa o fuso horário da organização, e o dia inteiro entra na lista. schema: type: string format: date example: '2026-09-30' responses: '200': description: Uma página de contatos. content: application/json: schema: $ref: '#/components/schemas/ContactList' examples: page: summary: Uma página com uma empresa e uma pessoa value: data: - id: com_12 type: company name: Importadora Exemplo Ltda trade_name: Exemplo email: fiscal@importadora.com.br tax_id: '12345678000195' lookup_status: completed discarded: false origin: contact created_at: '2026-09-25T10:30:00.000-03:00' - id: per_7 type: person name: Maria Souza trade_name: null email: maria.souza@exemplo.com.br tax_id: '52998224725' lookup_status: completed discarded: false origin: contact created_at: '2026-09-22T11:10:00.000-03:00' has_more: true next_cursor: WyIyMDI2LTA5LTIyVDE0OjEwOjAwLjAwMDAwMFoiLCJwZXJzb24iLDdd '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: Limit: name: limit in: query description: A quantidade de itens da página, de 1 a 100. O padrão é 25. schema: type: integer minimum: 1 maximum: 100 default: 25 example: 25 Cursor: name: cursor in: query description: >- O valor de `next_cursor` da página anterior. Sem este parâmetro, a lista começa no item mais novo. schema: type: string example: WyIyMDI2LTA5LTI1VDEzOjMxOjEyLjAwMDAwMFoiLDQwXQ schemas: ContactList: type: object additionalProperties: false required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/Contact' has_more: type: boolean description: Com `true`, a lista tem mais itens depois desta página. next_cursor: type: - string - 'null' description: >- O valor do parâmetro `cursor` para a próxima página. Na última página, o valor é `null`. Contact: type: object additionalProperties: false required: - id - type - name - trade_name - email - tax_id - lookup_status - discarded - origin - created_at properties: id: type: string pattern: ^(per|com)_[1-9][0-9]*$ description: >- O id do contato. O id da pessoa começa com `per_`, e o id da empresa começa com `com_`. examples: - com_12 type: type: string enum: - person - company description: '`person` para a pessoa e `company` para a empresa.' name: type: - string - 'null' description: >- O nome do contato. O valor é `null` até a consulta do CPF ou do CNPJ trazer o nome. examples: - Importadora Exemplo Ltda trade_name: type: - string - 'null' description: O nome fantasia da empresa. Na pessoa, o valor é `null`. examples: - Exemplo email: type: - string - 'null' description: O e-mail do contato, em minúsculas. examples: - fiscal@importadora.com.br tax_id: type: - string - 'null' description: >- O CPF da pessoa ou o CNPJ da empresa, sem pontuação e com as letras em maiúscula. O valor é `null` na pessoa que espera a confirmação do CPF. examples: - '12345678000195' lookup_status: type: string enum: - not_enqueued - pending - completed - failed - stale - needs_review description: >- O andamento da consulta do CPF ou do CNPJ. `not_enqueued`: a consulta não começou. `pending`: a consulta está em curso. `completed`: a consulta terminou. `failed`: a consulta falhou. `stale`: os dados da consulta estão velhos. `needs_review`: a pessoa espera a confirmação do CPF. discarded: type: boolean description: Com `true`, o contato está arquivado. origin: type: string enum: - contact - shareholder description: >- `contact` para o contato que a organização criou. `shareholder` para o sócio que a consulta do CNPJ criou. created_at: type: string format: date-time description: A data e a hora da criação, no fuso horário da organização. examples: - '2026-09-25T10:30:00.000-03:00' Problem: type: object description: Um erro no formato da RFC 9457. required: - type - title - status - detail - code properties: type: type: string const: about:blank description: Sempre `about:blank`. title: type: string description: A frase do status HTTP, em inglês. examples: - Unauthorized status: type: integer description: O status HTTP. examples: - 401 detail: type: string description: A explicação do erro, em português. code: type: string description: O código do erro, em inglês. O código não muda entre versões da v1. responses: BadRequest: description: Um parâmetro falta ou tem um valor inválido. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - invalid_parameter examples: invalid_parameter: summary: O limit passa de 100 value: type: about:blank title: Bad Request status: 400 detail: O parâmetro limit tem um valor inválido. code: invalid_parameter Unauthorized: description: A chave falta, não existe ou está revogada. 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: A chave falta ou não vale value: type: about:blank title: Unauthorized status: 401 detail: >- A chamada não trouxe uma chave de API válida. Envie a chave no cabeçalho Authorization, no formato Bearer . code: unauthorized PaymentRequired: description: A assinatura da organização está bloqueada. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - subscription_blocked examples: subscription_blocked: summary: A assinatura está bloqueada value: type: about:blank title: Payment Required status: 402 detail: >- A assinatura da organização está bloqueada. Regularize o pagamento no QX para usar a API. code: subscription_blocked Forbidden: description: >- A organização está arquivada, ou o plano da organização não inclui a API. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - organization_archived - plan_required examples: plan_required: summary: O plano gratuito não inclui a API value: type: about:blank title: Forbidden status: 403 detail: >- O plano gratuito não inclui a API. Assine um plano pago no QX para usar a API. code: plan_required TooManyRequests: description: A chave ou o endereço IP passou de um limite. 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: A chave passou do limite por minuto value: type: about:blank title: Too Many Requests status: 429 detail: >- A chave passou de um limite por minuto. Espere os segundos do cabeçalho Retry-After e chame de novo. code: rate_limited headers: WwwAuthenticate: description: O esquema de autenticação que a API espera. required: true schema: type: string example: Bearer realm="QX API" RetryAfter: description: Os segundos de espera antes da próxima chamada. required: true schema: type: integer minimum: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: >- A chave de API da organização, no cabeçalho `Authorization: Bearer `. A chave começa com `qx_`. ````