> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk.md).
# 批量导入 Advocate 参与者
Advocate 接受导入以下格式的文件 `.csv` 或 `.jsonl` 文件格式。请参阅我们的 [CSV 导入示例文件](https://assets.ctfassets.net/s68ib1kj8k5n/7LOYwhDlsI22uuaIMaWImE/71cefe860edc71c0968c8065e1d6e953/sample-user-upload.csv) 和 [JSONL 导入示例文件](https://assets.ctfassets.net/s68ib1kj8k5n/5rD1ZiKEjqStp54qjDB90N/48918dfa8b53a935c7c83ea5fbf3af77/userImportSample.jsonl) 以查看导入所需的文件结构。
{% hint style="info" %}
**注意：** 我们建议每次导入不超过 500,000 条记录。
{% endhint %}
#### 批量导入参与者
1. 从左侧导航菜单中，选择  **\[Engage] → 参与者**.
2. 选择 **导入用户**.
3. 在……下 *导入类型*，选择 **用户**.
4. 通过选择以下项添加您的导入文件 **选择文件**.
5. **\[可选]** 要将导入的参与者添加到或从某个特定用户分群中移除，请从下拉列表中选择该分群。
{% hint style="info" %}
**注意：** 此选择适用于 *所有* 此导入文件中包含的参与者。
{% endhint %}
6. 选择 **开始导入**.
导入完成后，将发送确认电子邮件。导入最多可能需要 30 分钟，具体取决于队列和文件大小。
#### 字段
批量用户导入在上传文件中同时支持标准字段和自定义字段。 **字段区分大小写。**
{% tabs %}
{% tab title="标准字段" %}
标准字段的解析验证与我们的 [Open Endpoint User Upsert API 调用](https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-api/api-open-endpoints):
| 字段 | 类型 | 说明 |
| ------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accountId（必填） | 字符串 | 此参与者所属账户的唯一标识符。 |
| id（必填） | 字符串 | 为此参与者提供的唯一标识符。 |
| firstName | 字符串 | 该参与者的名字。 |
| lastName | 字符串 | 该参与者的姓氏。 |
| 电子邮件 | 字符串 | 该参与者的电子邮件地址。 |
| referable | 布尔值 | impact.com 用于确定参与者是否可被推荐的标志。
注意： 该标志只能拼写为 一 个 r ，状态才能成功修改。
|
| locale | 字符串 | 参与者的区域设置，用于 [国际化](/brand/zh/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program.md)。locale 的格式必须为 `language_COUNTRY` ，其中语言代码必须为小写，国家代码必须为大写。分隔符必须是下划线。 |
| countryCode | 字符串 | 参与者的区域设置，用于 [国际化](/brand/zh/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program.md)。用户的国家代码（例如 CA）。 |
| referredBy.code | 字符串 | 推荐此参与者的客户倡导者的推荐码。 |
| referralCodes.{programId} | 字符串 | 此参与者在指定项目中分享的个性化推荐码（如果未包含，将自动生成）。 |
| sharelinks.{programId} | 字符串 | 此参与者在指定项目中分享的个性化分享链接（如果未包含，将自动生成）。 |
| dateCreated | 字符串 | 此参与者在您的 Advocate 项目中创建的日期。 |
| imageUrl | 字符串 | 可选用于小组件、电子邮件和主题中。如果您提供绝对的头像图片 URL，图片最小尺寸为 80px x 80px。 |
| dateUsTaxFormSubmitted | 整数 | 将参与者的 W-9 税务表标记为已收集的日期。如已配置，用于您租户中的 W-9 合规性。 |
| customFields.{fieldName} | 字符串 | 使用此结构可包含您选择的自定义字段。 |
| {% endtab %} | | |
{% tab title="自定义字段" %}
[自定义用户字段](/brand/zh/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/custom-and-calculated-fields/custom-fields-for-advocate-explained.md) 可包含属于您参与者的唯一数据。您可以根据自定义用户字段中的信息设置项目目标触发条件。
{% hint style="info" %}
**示例**：当参与者续订订阅会员资格时奖励他们。首先，包含自定义字段 `customFields.subscriptionPaid` ，其值为 **yes**。然后，将目标设置为在以下情况转化： `customFields.subscriptionPaid` 等于 **yes**.
{% endhint %}
按以下格式将自定义字段添加到列标题中： `customFields.yourCustomFieldName`.
{% hint style="info" %}
**注意：** 自定义字段不能接受数组或对象值。
{% endhint %}
{% endtab %}
{% endtabs %}
**结果**
导入完成后，我们会通过电子邮件通知您。您可以从  **\[Engage] → 报告 → 导入与导出** 您 Advocate 项目中的页面下载导入结果。
{% hint style="warning" %}
**警告：** 下载链接将在 30 天后失效。
{% endhint %}
{% tabs %}
{% tab title="上传成功" %}
如果导入成功完成，将生成一份包含参与者信息的文件并通过电子邮件发送给您。这些结果中包含的信息与我们的 [用户详情报告](/brand/zh/what-would-you-like-to-learn-about/advocate-program/advocate-reporting-and-analytics/advocate-program-reports-explained.md).
{% endtab %}
{% tab title="错误" %}
如果在导入过程中遇到任何错误，将生成一个附加文件。此错误文件包含每个发生错误的条目，包括失败记录（来自初始导入文件）的行号，以及任何相关错误消息。
| recordNumber | 消息 | apiErrorCode | statusCode |
| ------------ | ---------------- | ------------ | ---------- |
| 2 | 此请求需要一个有效且非空的 id | BAD\_REQUEST | 400 |
如果极少发生系统错误且导入中断，则导入将显示为 **已中止** 且不会恢复。如果您需要进一步帮助，请联系我们的支持团队。
{% endtab %}
{% endtabs %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participants/import-advocate-participants-in-bulk.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.