> 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] → Participants**.
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 | 字符串 | 参与者的姓氏。 |
| email | 字符串 | 参与者的电子邮件地址。 |
| 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)。区域设置必须符合以下格式 `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] → Reporting → Imports & Exports** 您 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.