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

# Listar perfis

> Listar ou procurar perfis de pacientes por email

Lista os perfis de pacientes acessíveis à tua chave de API ou procura um pelo endereço de email exato.

Quando `email` é fornecido, o endpoint faz uma pesquisa exata em cache Redis pelo
email canónico de início de sessão e devolve 0 ou 1 resultado; `limit` e `offset` são ignorados nesse
caso. Quando omitido, o endpoint devolve uma lista paginada de perfis limitada ao contexto de acesso da tua chave
de API.

A correspondência de email não distingue maiúsculas de minúsculas e é exata — não são suportadas correspondências parciais nem por prefixo.
Apenas o email canónico de início de sessão é verificado; endereços alternativos como `work_email` não são
considerados.

Requer o scope `profiles_view` ou `impersonate`.

## Pedido

### Parâmetros de consulta

**email** `string`

Filtra pelo endereço de email exato (sem distinção entre maiúsculas e minúsculas). Quando definido, devolve 0 ou 1 resultado e
`limit`/`offset` são ignorados. A pesquisa usa um índice invertido em cache Redis, com fallback
para SQL indexado.

**limit** `integer` (default: 100)

Número máximo de perfis a devolver. O valor predefinido é 100 e o máximo é 500. Ignorado quando `email` está definido.

**offset** `integer` (default: 0)

Número de perfis a ignorar para paginação. O valor predefinido é 0. Ignorado quando `email` está definido.

## Resposta

Em caso de sucesso, a API devolve `200 OK` com um array de objetos de perfil. A estrutura de cada
entrada corresponde a [Obter perfil](https://docs.anivahealth.com/pt/api/profiles/get-profile.md).

**id** `string` *required*

Identificador único do perfil (UUID).

**handle** `string`

Handle ou nome de utilizador do perfil. Pode ser `null`.

**first\_name** `string`

Nome próprio. Pode ser `null`.

**last\_name** `string`

Apelido. Pode ser `null`.

**email** `string`

Endereço de email. Pode ser `null`.

**phone** `string`

Número de telefone no formato E.164. Pode ser `null`.

**sex** `integer`

Sexo biológico segundo a norma ISO/IEC 5218 (`0` = desconhecido, `1` = masculino, `2` = feminino). Pode ser `null`.

**date\_of\_birth** `string`

Data de nascimento no formato `YYYY-MM-DD`. Pode ser `null`.

**height** `number`

Altura em centímetros. Pode ser `null`.

**weight** `number`

Peso em quilogramas. Pode ser `null`.

**language** `string`

Idioma preferido: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` ou `uk`.

**transactional\_emails\_enabled** `boolean`

Indica se este perfil recebe emails transacionais (programáticos). `null` quando nunca foi definido.

**created\_at** `string`

Carimbo de data/hora ISO 8601 da criação do perfil.

**updated\_at** `string`

Data e hora ISO 8601 da última atualização. Pode ser `null`.

## Notas de comportamento

* É devolvido um array vazio tanto quando nenhum perfil corresponde ao email como quando existe uma correspondência
  fora do teu contexto de acesso. Isto é intencional — impede que o endpoint revele a
  existência de perfis que não consegues ler.
* Os perfis recém-criados podem ser encontrados de imediato por `email` porque o fluxo de criação
  aquece a cache de forma síncrona.
* A lista sem filtros é ordenada por `created_at` de forma descendente (mais recentes primeiro) e paginada através de
  `limit` e `offset`.

## Chamadas repetidas

A Aniva guarda a resposta deste endpoint durante 5 minutos por cada chave API. Uma chamada repetida dentro
deste período recebe a resposta guardada. Os cabeçalhos `Cache-Status` e `Age` mostram que a resposta está
guardada e há quanto tempo.

Para saberes de imediato quando há uma alteração, subscreve os eventos de webhook `profile.created`, `profile.updated` e `profile.deleted`.
Vê [Leituras repetidas](https://docs.anivahealth.com/pt/concepts/webhooks.md#leituras-repetidas).

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — formato de email inválido, ou `limit`/`offset` fora do intervalo permitido. |
| `403` | Proibido — a tua chave de API não tem o scope necessário (`profiles_view`/`impersonate`). |
| `500` | Erro interno do servidor. |

```bash cURL (lookup by email) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?email=maria.schmidt@example.com' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (paginated list) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?limit=50&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": "2026-04-01T11:05:00Z"
  }
]
```

```json 200 (no match) theme={null}
[]
```

```json 400 theme={null}
{
  "error": "email: Invalid email format"
}
```


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