> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar contatos de signatários

> Lista os signatários cadastrados na agenda do projeto, com paginação e busca.

Lista a agenda de signatários do seu projeto. Cada contato armazena dados reutilizáveis (nome, CPF, e-mail, telefone, data de nascimento, qualificação) que podem ser preenchidos automaticamente ao criar envelopes.

**Autenticação**: `x-api-key` no header. Também aceita `Authorization: Bearer` com headers de projeto/organização.

## Parâmetros

<ParamField query="search" type="string" optional>
  Busca por nome, e-mail ou CPF (case-insensitive). Se contiver dígitos, também busca CPF.
</ParamField>

<ParamField query="page" type="integer" optional>
  Número da página (padrão: 1).
</ParamField>

<ParamField query="perPage" type="integer" optional>
  Itens por página (padrão: 20, máximo: 100).
</ParamField>

## Respostas

<ResponseField name="data" type="array">
  Lista de contatos (pode estar vazia).

  <Expandable title="Propriedades de data[]">
    <ResponseField name="uuid" type="string">
      UUID do contato.
    </ResponseField>

    <ResponseField name="name" type="string">
      Nome completo.
    </ResponseField>

    <ResponseField name="cpf" type="string">
      CPF (só dígitos).
    </ResponseField>

    <ResponseField name="cpfFormatted" type="string">
      CPF formatado (ex.: `000.000.000-00`).
    </ResponseField>

    <ResponseField name="email" type="string">
      E-mail.
    </ResponseField>

    <ResponseField name="phoneCountryCode" type="string" nullable>
      Código de país do telefone (ex.: `55`).
    </ResponseField>

    <ResponseField name="phoneNumber" type="string" nullable>
      Número de celular (só dígitos).
    </ResponseField>

    <ResponseField name="birthDate" type="string" nullable>
      Data de nascimento (AAAA-MM-DD).
    </ResponseField>

    <ResponseField name="qualification" type="string" nullable>
      Qualificação habitual (ex.: `"Contratante"`).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp de criação.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Timestamp da última atualização.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total de contatos (filtrando pela busca, se houver).
</ResponseField>

<ResponseField name="page" type="integer">
  Página atual.
</ResponseField>

<ResponseField name="perPage" type="integer">
  Itens por página.
</ResponseField>

## Erros

Veja [Autenticação e erros](/plataforma/assinatura-digital/api/erros-e-autenticacao).

* **401**: API key inválida.

<ResponseExample>
  ```json theme={"theme":"catppuccin-latte"}
  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "data": [
      {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "João Silva",
        "cpf": "12345678901",
        "cpfFormatted": "123.456.789-01",
        "email": "joao@empresa.com",
        "phoneCountryCode": "55",
        "phoneNumber": "11987654321",
        "birthDate": "1990-05-15",
        "qualification": "Contratante",
        "createdAt": "2025-07-27T10:30:00Z",
        "updatedAt": "2025-07-27T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "perPage": 20
  }
  ```
</ResponseExample>

## Exemplo

```bash theme={"theme":"catppuccin-latte"}
curl -X GET "https://api.valid.com/signer/v1/signer-contacts?search=joao&page=1&perPage=20" \
  -H "x-api-key: YOUR_API_KEY"
```

## Importante

* **Escopo por projeto**: a agenda é por projeto — você só vê contatos cadastrados no seu projeto.
* **Busca flexível**: se a busca contiver dígitos, busca também no CPF.
* **Ordenação**: contatos são listados por nome.

## Próximas etapas

1. Use os UUIDs dos contatos em [`PUT .../signers`](/plataforma/assinatura-digital/api/put-envelope-signers) ao criar envelopes.
2. Ou use [`POST .../signer-contact-groups`](/plataforma/assinatura-digital/api/post-signer-contact-group) para agrupar contatos (ex.: "Diretoria").

## Relacionado

* [`GET .../by-cpf/:cpf`](/plataforma/assinatura-digital/api/get-signer-contact-by-cpf) — buscar por CPF
* [`POST .../signer-contacts`](/plataforma/assinatura-digital/api/post-signer-contact) — cadastrar novo contato
* [`GET .../signer-contact-groups`](/plataforma/assinatura-digital/api/get-signer-contact-groups) — listar grupos


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.