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

# 管理联系人

> 创建并维护在各 YCloud 工作流中使用的客户画像。

## 功能简介

联系人用于存储客户身份和画像数据，例如电话号码、邮箱、标签、自定义属性以及归属关系。其他 YCloud 功能可将联系人用于受众细分、事件、营销活动和服务工作流。

## 准备工作

* 将电话号码规范化为 E.164 格式。
* 确定每个画像字段由哪个系统主导。
* 在写入依赖自定义属性的值之前，先定义好这些自定义属性。
* 建立客户数据的授权同意和保留规则。

## 工作原理

1. 使用唯一的电话号码创建联系人。
2. 存储返回的联系人 ID。
3. 通过标识符和筛选条件检索或列出联系人。
4. 更新画像、标签、自定义属性或归属关系。
5. 在数据保留策略要求时删除联系人。

使用 Webhook 事件将联系人的创建、删除和属性变更同步到下游系统。

## 请求

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

创建时仅 `phoneNumber` 为必填项。提供邮箱和电话号码字段时，其唯一性规则仍然适用。

## 响应

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

请将 `id` 存储为稳定的 YCloud 联系人标识符。在发送自定义事件或对账 Webhook 变更时使用该标识符。

## 搜索与分页

使用标签、国家代码、电话号码或邮箱等筛选条件列出联系人。请使用显式分页，并在翻页之间保留筛选条件。

## 数据一致性

* 为每个字段选定一个权威记录系统（system of record）。
* 将 Webhook 更新视为事件，而非绝对的全量替换记录。
* 确保数据导入程序和 Webhook 消费端具备幂等性。
* 避免因延迟到达的事件覆盖更新的客户数据。

## 限制与故障排查

* 电话号码必须采用 E.164 格式。
* 如果提供了邮箱地址，则必须唯一且有效。
* 每个联系人最多支持 50 个标签，且各字段有长度限制。
* 使用联系人属性端点发现可用的自定义属性。
* 在常规日志和支持凭证中脱敏个人数据。

<CardGroup cols={2}>
  <Card title="创建联系人 API" icon="user-plus" href="/api-reference/contacts/create-a-contact">
    查看字段格式、限制和完整响应。
  </Card>

  <Card title="联系人 Webhook" icon="webhook" href="/zh/api-reference/guides/examples/webhook-examples/contact-created-webhook-examples">
    处理创建、删除、属性变更以及退订变更。
  </Card>
</CardGroup>


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