> 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/impact-brand/docs/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 %}
**结果**
当您的导入完成时，我们会通过电子邮件通知您。您可以从您 Advocate 项目中的  **\[Engage] → 报告 → 导入与导出** 页面下载导入结果。
{% 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 | message | 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:
```
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=
```
The question should be specific, self-contained, and written in natural language.
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.