> 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 | boolean | impact.com 用于确定参与者是否可被推荐的标志。
注意： 该标志必须仅使用 一个 r 个 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 | integer | 参与者的 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` 并将其值设为 **是**。然后，将目标设置为在以下情况转换： `customFields.subscriptionPaid` 等于 **是**.
{% 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, 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.