> 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. 在左侧导航菜单中，选择 ![](https://impact-1.gitbook.io/docs/emvxfLrwrlacc4y3y02Y/~gitbook/image?url=https%3A%2F%2F4048883401-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FwMLlMoFBtKJa8ptd3zaw%252Fuploads%252Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%252Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg%3Falt%3Dmedia\&width=300\&dpr=3\&quality=100\&sign=71dd50ef\&sv=2) **\[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                 | 布尔值 | <p>impact.com 用于确定参与者是否可以被推荐的标志。</p><p><strong>注意：</strong> 此标志的拼写必须仅使用 <em>一</em> <code>r</code> 以便成功修改状态。</p>                                                                                                                                         |
| 区域设置                      | 字符串 | 参与者的区域设置，用于 [国际化](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/advocate-program/advocate-program-settings/translate-and-localize-your-advocate-program.md)。区域设置必须采用以下格式： `language_COUNTRY` 其中，语言代码必须为小写，国家/地区代码必须为大写。分隔符必须是下划线。 |
| countryCode               | 字符串 | 参与者的区域设置，用于 [国际化](https://help.impact.com/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               | 字符串 | 在您的倡导者计划中创建此参与者的日期。                                                                                                                                                                                                                                     |
| imageUrl                  | 字符串 | 可选，用于小组件、电子邮件和主题。如果您提供绝对个人资料图片 URL，图片尺寸至少须为 80px x 80px。                                                                                                                                                                                                |
| dateUsTaxFormSubmitted    | 整数  | 参与者的 W-9 税表被标记为已收集的日期。如果已配置，则用于您租户的 W-9 合规性。                                                                                                                                                                                                            |
| customFields.{fieldName}  | 字符串 | 使用此结构添加您自定义的字段。                                                                                                                                                                                                                                         |
| {% endtab %}              |     |                                                                                                                                                                                                                                                         |

{% tab title="自定义字段" %}
[自定义用户字段](https://help.impact.com/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 %}

**结果**

导入完成后，我们会通过电子邮件通知您。您可以从倡导者计划中的 ![](https://impact-1.gitbook.io/docs/emvxfLrwrlacc4y3y02Y/~gitbook/image?url=https%3A%2F%2F4048883401-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FwMLlMoFBtKJa8ptd3zaw%252Fuploads%252Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%252Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg%3Falt%3Dmedia\&width=300\&dpr=3\&quality=100\&sign=71dd50ef\&sv=2) **\[Engage] → 报告 → 导入与导出** 页面下载导入结果。

{% hint style="warning" %}
**警告：** 下载链接将在 30 天后过期。
{% endhint %}

{% tabs %}
{% tab title="上传成功" %}
如果导入成功完成，系统会生成包含参与者信息的文件并通过电子邮件发送给您。这些结果中包含的信息与我们的 [用户详细信息报告](https://help.impact.com/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        |

如果极少发生的系统错误导致导入中断，导入状态将显示为 **aborted** 且无法恢复。如需进一步协助，请联系支持团队。
{% 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=<question>&goal=<user_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.
