> ## 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.

# Gestionar contactos

> Crea y mantén perfiles de clientes utilizados en todos los flujos de trabajo de YCloud.

## Qué es

Los contactos almacenan la identidad del cliente y los datos de perfil como el número de teléfono, correo electrónico, etiquetas, atributos personalizados y asignación de propietario. Otras funciones de YCloud pueden usar los contactos para segmentación, eventos, campañas y flujos de trabajo de servicio.

## Antes de comenzar

* Normaliza los números de teléfono al formato E.164.
* Decide qué sistema es el propietario de cada campo del perfil.
* Define los atributos personalizados antes de escribir valores que dependan de ellos.
* Establece reglas de consentimiento y retención para los datos de los clientes.

## Cómo funciona

1. Crea un contacto con un número de teléfono único.
2. Guarda el ID de contacto devuelto.
3. Recupera o lista contactos mediante identificadores y filtros.
4. Actualiza el perfil, etiquetas, atributos personalizados o la asignación de propietario.
5. Elimina el contacto cuando tu política de retención lo requiera.

Usa eventos de Webhook para sincronizar la creación, eliminación y cambios de atributos de contactos con sistemas posteriores.

## Solicitud

`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"
  }'
```

Solo `phoneNumber` es obligatorio para la creación. Las reglas de unicidad para correo electrónico y número de teléfono siguen aplicando cuando dichos campos están presentes.

## Respuesta

```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"
}
```

Almacena `id` como el identificador de contacto estable de YCloud. Utilízalo al enviar eventos personalizados o conciliar cambios mediante Webhook.

## Búsqueda y paginación

Lista contactos con filtros como etiqueta, código de país, número de teléfono o correo electrónico. Usa paginación explícita y conserva los filtros entre páginas.

## Consistencia de datos

* Selecciona un sistema de registro único para cada campo.
* Trata las actualizaciones de Webhook como eventos, no como registros de reemplazo completos garantizados.
* Haz que las importaciones y los consumidores de Webhook sean idempotentes.
* Evita sobrescribir datos de clientes más recientes con eventos retrasados.

## Límites y resolución de problemas

* Los números de teléfono deben usar el formato E.164.
* Las direcciones de correo electrónico, cuando se proporcionan, deben ser únicas y válidas.
* Un contacto admite hasta 50 etiquetas, con límites de longitud específicos por campo.
* Usa el endpoint de atributos de contacto para consultar los atributos personalizados disponibles.
* Oculta datos personales en registros generales y evidencias de soporte.

<CardGroup cols={2}>
  <Card title="API para crear un contacto" icon="user-plus" href="/api-reference/contacts/create-a-contact">
    Inspecciona formatos de campo, límites y la respuesta completa.
  </Card>

  <Card title="Webhooks de contactos" icon="webhook" href="/es/api-reference/guides/examples/webhook-examples/contact-created-webhook-examples">
    Gestiona cambios de creación, eliminación, atributos y bajas de suscripción.
  </Card>
</CardGroup>


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