跳转到主要内容

​
概览

本指南将引导您准备 CSV 文件，以成功完成导入。 请按照以下步骤操作以避免错误。

​
步骤 1：检查文件要求

开始之前，请确保您的文件满足以下要求：
要求详情
格式CSV、XLSX 或 XLS
大小限制每个文件最多 10,000 条记录
编码建议使用 UTF-8
结构每个文件仅一种对象类型
对于超过 10,000 条记录的数据集，请拆分为多个文件，或使用API 导入。

​
步骤 2：下载示例文件

这是最重要的一步。 示例文件展示了 Twenty 期望的准确列名和格式。
  1. 进入对象视图（人员、公司等）
  2. 点击 ⋮ → 导入记录
  3. 点击 下载示例文件
  4. 将此文件用作模板
专业提示： 改为导出少量现有记录。 这将为您提供数据应如何格式化的真实示例，并且在导入过程中列名会自动映射。

​
步骤 3：移除重复值

Twenty 会对某些字段强制唯一性。 重复项会导致导入错误。
对象唯一字段
人员id, email
公司id, domain
自定义对象id，以及任何您标记为唯一的字段
导入之前：
  1. 按唯一字段（email 或 domain）对电子表格排序
  2. 删除或合并重复的行
  3. 检查 Twenty 中是否已存在重复项
软删除的记录计入唯一性。 位于“命令菜单 → 查看已删除的记录”中的记录会导致重复错误。 请永久删除这些记录，或将其恢复并更新。

​
步骤 4：正确格式化各字段类型

不同的字段类型需要特定格式。 以下是完整参考：

​
文本字段

  • 无需特殊格式
  • 首尾空格将自动去除

​
电子邮件字段

  • 必须是有效的电子邮件格式：name@domain.com
  • 必须唯一（文件内及 Twenty 中不得重复）
  • 对于附加电子邮件，请在 Emails / Additional Emails 列中使用此格式：
["jane@twenty.com","jane.doe@twenty.com"]

​
域名字段

  • 推荐格式：https://domain.com
  • 这与邮箱/日历同步所使用的格式一致（可防止重复）
  • 填写这两列：
    • Domain / Domain Label：domain.com
    • Domain / Domain URL：https://domain.com
  • 在您的文件内以及在 Twenty 中必须唯一

​
电话字段

电话是一个嵌套字段，需要多列：
列示例
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
电话 / 主电话号码国际区号+1

​
地址字段

地址是一个嵌套字段，包含多个列（有些可以留空）：
  • Address / Address 1：街道地址第 1 行
  • Address / Address 2：街道地址第 2 行（可选）
  • Address / City：城市名称
  • Address / State：州或省
  • Address / Country：国家名称
  • Address / Post Code：邮政/ZIP 编码

​
日期字段

在整个文件中使用一致的格式：
  • YYYY-MM-DD（推荐）：2024-03-15
  • MM/DD/YYYY：03/15/2024
  • DD/MM/YYYY：15/03/2024
  • ISO 8601：2024-03-15T10:30:00Z

​
数字字段

  • 仅数字（无文本）
  • 小数使用点号：1234.56
  • 不使用千位分隔符（不要写成 1,234.56）

​
货币字段

货币是一个嵌套字段，需要两列，且两列都必须填写：
列示例
Amount / Amount1234.56
Amount / CurrencyUSD

​
布尔字段

使用大写：TRUE 或 FALSE
小写的 true 或 false 将无法使用。

​
选择字段

使用选项的API 名称，而不是显示标签。 如何查找 API 名称：
  1. 进入 设置 → 数据模型
  2. 选择对象和字段
  3. 启用高级模式（右下角切换）
  4. 复制该 API 名称（例如：OPTION_1，而不是 “Option 1”）
新的选择项不会自动创建。 请在导入前于 设置 → 数据模型 中添加它们。

​
多选字段

以数组格式使用 API 名称： 
["VALUE1","VALUE2"]

​
数组字段

使用 JSON 数组格式： 
["value1","value2"]

​
评分字段

使用以下格式：RATING_1、RATING_2、RATING_3、RATING_4 或 RATING_5

​
链接/URL 字段

填写两列：
  • Links / Link Label：Twenty
  • Links / Link URL：https://twenty.com
对于次要链接，请使用 Links / Secondary Links 列： 
[{"url":"https://twenty.com","label":"Twenty"}]

​
JSON 字段

使用有效的 JSON 格式： 
{"key":"value","key2":"value2"}

​
ID 字段

  • 可选：如未提供，Twenty 将自动生成 ID
  • 格式：UUID（例如：c776ee49-f608-4a77-8cc8-6fe96ae1e43f）
  • 使用场景：包含 ID 以更新现有记录，而不是创建新记录

​
步骤 5：添加关系列（如果要关联记录）

要将记录关联到其他对象（例如，将人员关联到公司），请添加包含关联记录唯一标识符的列。 示例：将人员关联到公司 在您的人员 CSV 中添加一列： 
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
关系的重要规则：
  • 父记录必须已存在于 Twenty 中
  • 使用域名 URL 格式（https://domain.com），而不是标签
  • 仅映射一个唯一标识符（不要同时包含 companyId 和 companyDomain）
  • 对于工作区成员，请使用其电子邮箱（而不是姓名）
导入顺序很重要！先导入“1”端，再导入“多”端：
  1. 公司 优先
  2. 人员 其次（包含公司引用）
  3. 机会 第三
在引用之前，父记录必须已存在。
详细说明请参见如何导入关系。

​
步骤 6：确保 Twenty 中存在这些字段

导入会创建记录，而非字段。 要导入的所有字段必须已在您的数据模型中存在。 导入前：
  1. 进入 设置 → 数据模型
  2. 选择您的对象
  3. 创建所需的任何自定义字段
  4. 记录准确的字段名称（必须与列标题匹配）

​
步骤 7：最终检查清单

在上传文件之前，请确认：
文件为 CSV、XLSX 或 XLS 格式
文件少于 10,000 条记录
编码为 UTF-8
没有重复的电子邮箱（针对人员）或域名（针对公司）
日期在全篇使用一致的格式
域名使用 https://domain.com 格式
布尔字段使用 TRUE 或 FALSE（大写）
选择字段使用 API 名称，而非显示标签
所有自定义字段已存在于 设置 → 数据模型 中
父记录先于子记录导入
关系列引用现有记录

​
常见错误及避免方法

错误解决方案
使用 true 而非 TRUE布尔值必须为大写
在选择字段中使用显示标签在“设置”中查找并使用 API 名称
在公司之前导入人员始终先导入父对象
货币字段缺少货币代码填写金额和货币两列
域名格式错误始终使用 https://domain.com 格式
为关系映射了多个唯一字段仅映射一个（域名或 ID，不要同时映射）

​
下一步

您的文件已准备就绪！ 现在：