> ## Documentation Index > Fetch the complete documentation index at: https://docs.ziala.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar contatos > Lista os contatos da conta com a etapa atual e a primeira origem (anúncio ou link). Contatos do ambiente de teste não aparecem. ## OpenAPI ````yaml https://api.ziala.com.br/v1/openapi.json get /v1/contacts openapi: 3.0.0 info: title: API de dados da Ziala description: >- Leitura dos dados da sua conta (contatos, campos, conversas com origem de anúncio, mudanças de etapa e exclusões) para painéis e plataformas de dados. version: '1' contact: name: Suporte Ziala url: https://ziala.com.br email: contato@ziala.com.br servers: - url: https://api.ziala.com.br security: [] tags: - name: Conta description: A conta e os limites da chave. - name: Contatos description: Contatos e os valores dos campos personalizados. - name: Conversas description: Conversas, com origem e métricas. - name: Funis description: Etapas dos funis e o histórico de mudanças de etapa. - name: Campos description: Definições dos campos personalizados. - name: Exclusões description: Registros apagados, para replicar a exclusão. paths: /v1/contacts: get: tags: - Contatos summary: Listar contatos description: >- Lista os contatos da conta com a etapa atual e a primeira origem (anúncio ou link). Contatos do ambiente de teste não aparecem. operationId: listContacts parameters: - name: updated_since required: false in: query schema: type: string description: >- Retorna só registros criados ou alterados a partir deste instante: data e hora ISO 8601 com fuso, ou só a data (`AAAA-MM-DD`, meia-noite UTC). A busca recua 5 minutos para cobrir diferenças de relógio, então grave pela chave primária (`id`). - name: cursor required: false in: query schema: type: string description: Valor de `next_cursor` da página anterior. - name: limit required: false in: query schema: type: integer minimum: 1 maximum: 200 default: 100 description: Itens por página. responses: '200': headers: RateLimit-Limit: description: Requisições permitidas por minuto para a chave. schema: type: integer RateLimit-Remaining: description: Requisições restantes no minuto. schema: type: integer RateLimit-Reset: description: Segundos até o minuto reiniciar. schema: type: integer description: Página de contatos. content: application/json: schema: type: object required: - data - next_cursor - has_more - sync_watermark properties: data: type: array items: type: object required: - id - created_at - updated_at - name - first_name - last_name - email - phone - job_title - company_name - icp_id - qualification_score - temperature - source - source_detail - consent_given_at - do_not_contact - do_not_contact_at - won_at - lost_at - current_stage_id - current_stage_entered_at - current_agent_id - last_activity_at - first_origin_kind - first_origin_ad_id - first_origin_ctwa_clid - first_origin_headline - first_origin_at - first_campaign_id properties: id: type: string nullable: false description: Identificador único do registro. example: 3f6c2a9e-8b1d-4c7e-9a52-1e0d6b7f4a10 created_at: type: string format: date-time nullable: false description: Data de criação. example: '2026-10-13T14:02:11.000Z' updated_at: type: string format: date-time nullable: false description: Data da última alteração. example: '2026-10-13T14:31:02.000Z' name: type: string nullable: true description: Nome completo. example: Maria Souza first_name: type: string nullable: true description: Primeiro nome. example: Maria last_name: type: string nullable: true description: Sobrenome. example: Souza email: type: string nullable: true description: E-mail. example: maria@exemplo.com.br phone: type: string nullable: true description: >- Telefone no formato E.164, por exemplo `+5548999990000`. example: '+5548999990000' job_title: type: string nullable: true description: Cargo. example: Gerente comercial company_name: type: string nullable: true description: Empresa. example: Exemplo Ltda icp_id: type: string nullable: true description: >- Perfil de cliente ideal em que o contato foi enquadrado. example: c4d8e2f1-3a6b-4c9d-8e7f-1a2b3c4d5e6f qualification_score: type: integer nullable: true description: >- Pontuação de qualificação calculada pelas regras do perfil. example: 72 temperature: type: string nullable: true description: >- Propensão de compra estimada. Valores: `hot`, `warm` ou `cold`. example: warm source: type: string nullable: true description: >- Como o contato entrou. Valores: `manual`, `inbound_whatsapp`, `webhook_form`, `api` ou `hubspot`. example: inbound_whatsapp source_detail: type: string nullable: true description: >- Complemento da origem, como o material, a página ou a campanha. example: Campanha de outubro consent_given_at: type: string format: date-time nullable: true description: Data em que o contato deu consentimento. example: '2026-10-13T14:02:11.000Z' do_not_contact: type: boolean description: >- `true` quando o contato pediu para não receber mensagens. example: false do_not_contact_at: type: string format: date-time nullable: true description: Data do pedido para não receber mensagens. example: null won_at: type: string format: date-time nullable: true description: Data em que o contato chegou a uma etapa de ganho. example: null lost_at: type: string format: date-time nullable: true description: Data em que o contato chegou a uma etapa de perda. example: null current_stage_id: type: string nullable: true description: >- Etapa atual do contato. Detalhes em `/v1/pipeline_stages`. example: 9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d current_stage_entered_at: type: string format: date-time nullable: true description: Data de entrada na etapa atual. example: '2026-10-13T14:02:11.000Z' current_agent_id: type: string nullable: true description: Agente responsável pelo contato hoje. example: b7e1c0d2-5a4f-4e3b-8c9d-2f1a0e6d3c55 last_activity_at: type: string format: date-time nullable: true description: >- Data da última mensagem trocada com o contato, em qualquer conversa. example: '2026-10-13T14:30:48.000Z' first_origin_kind: type: string nullable: true description: >- Origem da primeira conversa com origem conhecida. Valores: `ad` (anúncio Click-to-WhatsApp da Meta) ou `link` (texto de um link de campanha). example: ad first_origin_ad_id: type: string nullable: true description: >- Identificador do anúncio na Meta, na primeira origem. example: '120211234567890123' first_origin_ctwa_clid: type: string nullable: true description: >- Identificador de clique da Meta (`ctwa_clid`), na primeira origem. example: >- ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO first_origin_headline: type: string nullable: true description: Título do anúncio, na primeira origem. example: Fale com um especialista first_origin_at: type: string format: date-time nullable: true description: Data em que a primeira origem foi registrada. example: '2026-10-13T14:02:11.000Z' first_campaign_id: type: string nullable: true description: >- Campanha cadastrada na Ziala que corresponde à primeira origem. example: d5e6f7a8-9b0c-4d1e-8f2a-3b4c5d6e7f80 next_cursor: type: string nullable: true example: >- eyJ0IjoiM2Y2YzJhOWUiLCJ0cyI6IjIwMjYtMTEtMDNUMTQ6MzE6MDIuMDAwWiJ9 description: >- Cursor da próxima página, para enviar em `cursor`. `null` na última página. has_more: type: boolean example: true description: '`true` se há mais páginas.' sync_watermark: type: string format: date-time example: '2026-10-13T14:29:00.000Z' description: >- Instante até o qual esta leitura está completa, igual em todas as páginas. Envie como `updated_since` na próxima sincronização. '400': description: Parâmetro inválido, ou cursor alterado ou de outra conta. content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. '401': description: Chave ausente, inválida ou revogada. content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. '403': description: API de dados desligada na conta, ou plano sem acesso. content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. '429': description: >- Limite de requisições atingido (por minuto, por dia ou simultâneas). Aguarde o `Retry-After`. headers: Retry-After: description: Segundos a aguardar antes de repetir a requisição. schema: type: integer RateLimit-Limit: description: Requisições permitidas por minuto para a chave. schema: type: integer RateLimit-Remaining: description: Requisições restantes no minuto. schema: type: integer RateLimit-Reset: description: Segundos até o minuto reiniciar. schema: type: integer content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. '500': description: Erro inesperado. Repita com espera crescente. content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. '503': description: Serviço temporariamente indisponível. Aguarde o `Retry-After`. headers: Retry-After: description: Segundos a aguardar antes de repetir a requisição. schema: type: integer RateLimit-Limit: description: Requisições permitidas por minuto para a chave. schema: type: integer RateLimit-Remaining: description: Requisições restantes no minuto. schema: type: integer RateLimit-Reset: description: Segundos até o minuto reiniciar. schema: type: integer content: application/problem+json: schema: type: object required: - type - title - status - detail - request_id properties: type: type: string example: about:blank description: Sempre `about:blank`. title: type: string example: Requisição inválida description: Resumo do erro, fixo por status. status: type: integer example: 400 description: Status HTTP. detail: type: string example: limit deve ser um número inteiro de 1 a 200. description: Explicação desta ocorrência. request_id: type: string example: req-3f2a description: Identificador da requisição, para o suporte. security: - bearer: [] components: securitySchemes: bearer: scheme: bearer bearerFormat: zk_live_… type: http description: Chave da API da conta, no formato `zk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.