> ## 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 grupos de signatários

> Lista os grupos de contatos cadastrados no projeto, com seus membros.

Lista os grupos de signatários do seu projeto. Cada grupo contém uma lista ordenada de contatos que podem ser adicionados em massa ao criar envelopes.

**Autenticação**: `x-api-key` no header. Também aceita `Authorization: Bearer`.

## Parâmetros

<ParamField query="search" type="string" optional>
  Busca por nome do grupo (case-insensitive).
</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 grupos com seus membros.

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

    <ResponseField name="name" type="string">
      Nome do grupo (ex.: `"Diretoria"`).
    </ResponseField>

    <ResponseField name="members" type="array">
      Contatos no grupo, **na ordem**. Cada item é um contato completo (mesma estrutura de [`GET .../signer-contacts`](/plataforma/assinatura-digital/api/get-signer-contacts)).
    </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 grupos.
</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": "6ba7b820-9dad-11d1-80b4-00c04fd430c9",
        "name": "Diretoria",
        "members": [
          {
            "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "name": "João Silva",
            "cpf": "12345678901",
            "email": "joao@empresa.com"
          },
          {
            "uuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
            "name": "Maria Santos",
            "cpf": "98765432109",
            "email": "maria@empresa.com"
          }
        ],
        "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-contact-groups?search=diretoria" \
  -H "x-api-key: YOUR_API_KEY"
```

## Importante

* **Escopo por projeto**: grupos são por projeto — você só vê os do seu.
* **Ordem dos membros**: preservada (importante para fluxos sequenciais).

## Relacionado

* [`GET .../signer-contact-groups/:uuid`](/plataforma/assinatura-digital/api/get-signer-contact-group-by-id) — detalhe de um grupo
* [`POST .../signer-contact-groups`](/plataforma/assinatura-digital/api/post-signer-contact-group) — criar grupo


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