> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendify.dingstore.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。
</Warning>

## 请求体

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

## 请求示例

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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)
    ```
  </Tab>
</Tabs>

## 成功响应

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.