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

# Gerenciar contatos

> Crie e mantenha perfis de clientes usados em todos os fluxos de trabalho da YCloud.

## O que é

Os contatos armazenam a identidade e os dados de perfil do cliente, como número de telefone, e-mail, tags, atributos personalizados e propriedade. Outros recursos da YCloud podem usar contatos para segmentação, eventos, campanhas e fluxos de trabalho de atendimento.

## Antes de começar

* Normalize os números de telefone para o formato E.164.
* Defina qual sistema é o proprietário de cada campo do perfil.
* Defina os atributos personalizados antes de gravar valores que dependem deles.
* Estabeleça regras de consentimento e retenção para os dados dos clientes.

## Como funciona

1. Crie um contato com um número de telefone exclusivo.
2. Armazene o ID de contato retornado.
3. Recupere ou liste contatos por identificadores e filtros.
4. Atualize o perfil, tags, atributos personalizados ou propriedade.
5. Exclua o contato quando sua política de retenção exigir.

Use eventos de webhook para sincronizar a criação, a exclusão e as alterações de atributos de contatos com sistemas downstream.

## Requisição

`POST /contact/contacts`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/contact/contacts \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "nickname": "Avery",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "email": "avery@example.com",
    "tags": ["customer", "vip"],
    "customAttributes": [
      {
        "name": "plan",
        "value": "premium"
      }
    ],
    "ownerEmail": "sales@example.com"
  }'
```

Apenas `phoneNumber` é obrigatório para a criação. As regras de exclusividade de e-mail e número de telefone ainda se aplicam quando esses campos estão presentes.

## Resposta

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "1693364594105000000",
  "nickname": "Avery",
  "phoneNumber": "+16315551111",
  "countryCode": "US",
  "email": "avery@example.com",
  "tags": ["customer", "vip"],
  "sourceType": "API",
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

Armazene `id` como o identificador estável de contato da YCloud. Use-o ao enviar eventos personalizados ou reconciliar alterações via webhook.

## Busca e paginação

Liste contatos com filtros como tag, código do país, número de telefone ou e-mail. Use paginação explícita e mantenha os filtros entre as páginas.

## Consistência de dados

* Selecione um sistema de registro oficial (system of record) para cada campo.
* Trate as atualizações de webhook como eventos, e não como registros de substituição completa garantidos.
* Torne as importações e os consumidores de webhook idempotentes.
* Evite sobrescrever dados mais recentes do cliente com eventos atrasados.

## Limites e solução de problemas

* Os números de telefone devem usar o formato E.164.
* Os endereços de e-mail, quando fornecidos, devem ser exclusivos e válidos.
* Um contato suporta até 50 tags, com limites de comprimento específicos por campo.
* Use o endpoint de atributos de contato para descobrir os atributos personalizados disponíveis.
* Oculte dados pessoais de logs gerais e evidências de suporte.

<CardGroup cols={2}>
  <Card title="API de criação de contato" icon="user-plus" href="/api-reference/contacts/create-a-contact">
    Inspecione os formatos de campos, limites e a resposta completa.
  </Card>

  <Card title="Webhooks de contato" icon="webhook" href="/pt/api-reference/guides/examples/webhook-examples/contact-created-webhook-examples">
    Gerencie alterações de criação, exclusão, atributos e cancelamento de inscrição.
  </Card>
</CardGroup>


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