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

# 创建联系人

> 通过标签名称和自定义字段创建联系人

通过标签名称和自定义字段 Key 创建联系人。默认标签名称不存在或匹配不唯一时请求失败，字段 Key 不存在或匹配不唯一时请求失败。

```http theme={null}
POST https://api.sendify.dingstore.cn/dmx/v2/contacts
```

## 认证

在 `Authorization` 请求头中使用 Bearer API Key：

```http theme={null}
Authorization: Bearer YOUR_TOKEN
```

> [!WARNING]
>
> 请勿在前端代码、公开仓库或日志中保存真实 API Key。

## 请求体

Content-Type：`application/json`

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `email` | `string` | 是 | 联系人的邮件地址 |
| `tagNames` | `array<string>` | 否 | 要添加到联系人的标签名称列表。保留已有标签，仅添加本次列表中的新标签 |
| `customFields` | `array<object>` | 否 | 自定义字段值 |
| `autoCreateTags` | `boolean` | 否 | 标签不存在时是否自动创建，默认为 `false` |
| `conflictPolicy` | `enum<string>` | 否 | 联系人已存在时的处理策略，默认创建失败 |

### `customFields` 对象

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `fieldName` | `string` | 是 | 自定义字段名称。字段必须已存在且唯一；不存在或匹配不唯一时请求失败 |
| `fieldValue` | `string` | 否 | 自定义字段值 |

### 标签自动创建

`autoCreateTags` 控制 `tagNames` 中不存在的标签如何处理：

* `false`：请求中存在未命中的标签名称时，请求失败。
* `true`：自动创建不存在的标签，并将其添加到联系人。

### 联系人冲突策略

| 值 | 行为 |
| - | - |
| `CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS` | 联系人已存在时返回冲突错误，不更新联系人 |
| `CONTACT_CONFLICT_POLICY_UPDATE_IF_EXISTS` | 按 `email` 更新已有联系人；保留已有标签，仅追加本次提交的新标签 |

### 请求体示例

```json theme={null}
{
  "email": "string",
  "tagNames": [
    "string"
  ],
  "customFields": [
    {
      "fieldName": "string",
      "fieldValue": "string"
    }
  ],
  "autoCreateTags": true,
  "conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS"
}
```

## 请求示例

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST \
>   "https://api.sendify.dingstore.cn/dmx/v2/contacts" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "email": "string",
>     "tagNames": ["string"],
>     "customFields": [
>       {
>         "fieldName": "string",
>         "fieldValue": "string"
>       }
>     ],
>     "autoCreateTags": true,
>     "conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS"
>   }'
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> const response = await fetch(
>   "https://api.sendify.dingstore.cn/dmx/v2/contacts",
>   {
>     method: "POST",
>     headers: {
>       Authorization: "Bearer YOUR_TOKEN",
>       "Content-Type": "application/json",
>     },
>     body: JSON.stringify({
>       email: "string",
>       tagNames: ["string"],
>       customFields: [
>         {
>           fieldName: "string",
>           fieldValue: "string",
>         },
>       ],
>       autoCreateTags: true,
>       conflictPolicy: "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS",
>     }),
>   }
> );
>
> const data = await response.json();
> console.log(data);
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> url = "https://api.sendify.dingstore.cn/dmx/v2/contacts"
> headers = {
>     "Authorization": "Bearer YOUR_TOKEN",
>     "Content-Type": "application/json",
> }
> payload = {
>     "email": "string",
>     "tagNames": ["string"],
>     "customFields": [
>         {
>             "fieldName": "string",
>             "fieldValue": "string",
>         }
>     ],
>     "autoCreateTags": True,
>     "conflictPolicy": "CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS",
> }
>
> response = requests.post(url, headers=headers, json=payload)
> print(response.status_code)
> print(response.text)
> ```

## 成功响应

HTTP `200` 返回创建或更新后的联系人：

| 字段 | 类型 | 说明 |
| - | - | - |
| `contact` | `object` | 联系人对象 |
| `contact.id` | `string` | 联系人 ID |
| `contact.email` | `string` | 邮件地址 |
| `contact.tagNames` | `array<string>` | 标签名称列表 |
| `contact.customFields` | `array<object>` | 自定义字段值 |
| `contact.customFields[].fieldName` | `string` | 自定义字段名称 |
| `contact.customFields[].fieldValue` | `string` | 自定义字段值 |
| `contact.createTime` | `string (date-time)` | 创建时间 |

### 响应示例

```json theme={null}
{
  "contact": {
    "id": "string",
    "email": "string",
    "tagNames": [
      "string"
    ],
    "customFields": [
      {
        "fieldName": "string",
        "fieldValue": "string"
      }
    ],
    "createTime": "string"
  }
}
```

## 错误响应

| HTTP 状态码 | 说明 |
| - | - |
| `401` | 访问未授权，请检查是否传递了正确的 Bearer API Key |
| `403` | 无 API 访问权限，请检查 API Key 的权限配置 |


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