Manage contacts

​

What it is

​

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.

​

Request

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

​

Response

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

​

Search and pagination

​

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.