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

# Manage contacts

> Create and maintain customer profiles used across YCloud workflows.

## What it is

Contacts store customer identity and profile data such as phone number, email,
tags, custom attributes, and ownership. Other YCloud features can use contacts
for segmentation, events, campaigns, and service workflows.

## Before you begin

* Normalize phone numbers to E.164 format.
* Decide which system owns each profile field.
* Define custom attributes before writing values that depend on them.
* Establish consent and retention rules for customer data.

## How it works

1. Create a contact with a unique phone number.
2. Store the returned contact ID.
3. Retrieve or list contacts by identifiers and filters.
4. Update profile, tags, custom attributes, or ownership.
5. Delete the contact when your retention policy requires it.

Use webhook events to synchronize contact creation, deletion, and attribute
changes with downstream systems.

## Request

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

Only `phoneNumber` is required for creation. Email and phone number uniqueness
rules still apply when those fields are present.

## Response

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

Store `id` as the stable YCloud contact identifier. Use it when sending custom
events or reconciling webhook changes.

## Search and pagination

List contacts with filters such as tag, country code, phone number, or email.
Use explicit pagination and preserve filters between pages.

## Data consistency

* Select one system of record for each field.
* Treat webhook updates as events, not as guaranteed full replacement records.
* Make imports and webhook consumers idempotent.
* Avoid overwriting newer customer data with delayed events.

## Limits and troubleshooting

* Phone numbers must use E.164 format.
* Email addresses, when provided, must be unique and valid.
* A contact supports up to 50 tags, with field-specific length limits.
* Use the contact attributes endpoint to discover available custom attributes.
* Redact personal data from general logs and support evidence.

<CardGroup cols={2}>
  <Card title="Create a contact API" icon="user-plus" href="/api-reference/contacts/create-a-contact">
    Inspect field formats, limits, and the complete response.
  </Card>

  <Card title="Contact webhooks" icon="webhook" href="/en/api-reference/guides/examples/webhook-examples/contact-created-webhook-examples">
    Handle creation, deletion, attribute, and unsubscribe changes.
  </Card>
</CardGroup>


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