CRM

管理组织的销售管道、阶段、商机、任务类型和 CRM 任务，并通过 HubSpot 或 Pipedrive 使用 CRM。

CRM 端点描述你的销售流程：商机在销售管道的各阶段间流转，CRM 任务记录关联联系人和商机的跟进工作。每条路由都限定在组织范围内，会话或 API 密钥必须具有当前组织。读取使用 CRM 读取权限范围（READ_CRM / 组织权限 view_contacts），修改使用 CRM 写入权限范围（WRITE_CRM / 组织权限 manage_contacts），但团队成员操作例外，需要 manage_team。权限范围与 API 密钥及成员角色的映射见身份验证和权限。

每个列表端点都返回 data 数组和标准 pagination 封装，其中包含不透明的 next_cursor。简单的 GET 列表端点使用键集游标；多条件 POST .../search 端点由于排序列可为空，无法使用键集游标，内部按偏移量分页，但仍提供相同的不透明 next_cursor，并额外返回准确的 total。

列出销售管道

GET /crm/pipelines

返回组织的所有销售管道，每个包含按顺序排列的阶段。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

直接返回销售管道对象数组，不额外封装。

[
  {
    "id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
    "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "Sales",
    "position": 0,
    "stages": [
      {
        "id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
        "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
        "name": "Lead",
        "color": "#0ea5e9",
        "position": 0,
        "deal_count": 12,
        "created_at": "2026-05-01T09:00:00Z",
        "updated_at": "2026-05-01T09:00:00Z"
      }
    ],
    "created_at": "2026-05-01T09:00:00Z",
    "updated_at": "2026-05-01T09:00:00Z"
  }
]

创建销售管道

POST /crm/pipelines

创建销售管道，可同时初始化一组有序阶段。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`name`	string	是	销售管道名称，1 至 255 个字符。
`stages`	array	否	随销售管道一同创建的阶段，按顺序排列。
`stages[].name`	string	是	阶段名称，1 至 255 个字符。
`stages[].color`	string	是	阶段颜色，十六进制。

{
  "name": "Sales",
  "stages": [
    { "name": "Lead", "color": "#0ea5e9" },
    { "name": "Qualified", "color": "#8b5cf6" },
    { "name": "Won", "color": "#22c55e" }
  ]
}

响应

201 Created，包含创建的销售管道对象，结构与列表响应一致，包含其 stages。

{
  "id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "name": "Sales",
  "position": 0,
  "stages": [
    {
      "id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
      "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
      "name": "Lead",
      "color": "#0ea5e9",
      "position": 0,
      "created_at": "2026-06-12T10:00:00Z",
      "updated_at": "2026-06-12T10:00:00Z"
    }
  ],
  "created_at": "2026-06-12T10:00:00Z",
  "updated_at": "2026-06-12T10:00:00Z"
}

获取销售管道

GET /crm/pipelines/:id

获取单个销售管道及其阶段。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。

响应

返回销售管道对象，结构与列表项相同。

{
  "id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "name": "Sales",
  "position": 0,
  "stages": [],
  "created_at": "2026-05-01T09:00:00Z",
  "updated_at": "2026-05-01T09:00:00Z"
}

更新销售管道

PATCH /crm/pipelines/:id

重命名销售管道。此处只能修改名称，阶段有各自的端点。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。

请求体

字段	类型	必填	说明
`name`	string	否	新的销售管道名称。

{
  "name": "Enterprise Sales"
}

响应

返回更新后的销售管道对象。

删除销售管道

DELETE /crm/pipelines/:id

删除销售管道及其阶段。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。

响应

204 No Content.

创建阶段

POST /crm/pipelines/:id/stages

向销售管道追加阶段。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。

请求体

字段	类型	必填	说明
`name`	string	是	阶段名称，1 至 255 个字符。
`color`	string	是	阶段颜色，十六进制。

{
  "name": "Negotiation",
  "color": "#f59e0b"
}

响应

201 Created，包含创建的阶段对象。

{
  "id": "9c0d1e2f-3a4b-4c5d-6e7f-8a9b0c1d2e3f",
  "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "name": "Negotiation",
  "color": "#f59e0b",
  "position": 3,
  "created_at": "2026-06-12T10:05:00Z",
  "updated_at": "2026-06-12T10:05:00Z"
}

更新阶段

PATCH /crm/pipelines/:id/stages/:stageId

修改阶段名称或颜色。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。
`stageId`	path	uuid	阶段 ID。

请求体

字段	类型	必填	说明
`name`	string	否	新的阶段名称。
`color`	string	否	新的阶段颜色，十六进制。

{
  "name": "Contract Sent",
  "color": "#6366f1"
}

响应

返回更新后的阶段对象。

删除阶段

DELETE /crm/pipelines/:id/stages/:stageId

从销售管道移除阶段。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	销售管道 ID。
`stageId`	path	uuid	阶段 ID。

响应

204 No Content.

列出商机

GET /crm/deals

列出商机，可按销售管道、阶段和状态筛选，采用键集分页。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`pipeline_id`	query	uuid	限定为此销售管道中的商机。
`stage_id`	query	uuid	限定为此阶段中的商机。
`status`	query	string	限定为 `open`、`won` 或 `lost`。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。
`limit`	query	int	每页数量，范围 1 至 100，默认 50。

响应

包含商机对象的 data 数组，加上键集分页 pagination 封装。列表行可能包含关联查询得到的 contact、stage 对象及 campaign_name。

{
  "data": [
    {
      "id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
      "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
      "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
      "name": "Acme renewal",
      "value": 12000,
      "currency": "USD",
      "status": "open",
      "expected_close_date": "2026-07-15T00:00:00Z",
      "assigned_to": "bb22cc33-dd44-4ee5-86ff-770011223344",
      "campaign_id": "cc33dd44-ee55-4ff6-9700-112233445566",
      "source_mailbox_id": "dd44ee55-ff66-4007-8811-223344556677",
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-10T09:30:00Z",
      "campaign_name": "Q2 outbound"
    }
  ],
  "pagination": {
    "total": null,
    "next_cursor": "c1_b3BhcXVlLWN1cnNvcg",
    "has_more": true
  }
}

创建商机

POST /crm/deals

在销售管道阶段中创建商机，可关联联系人，并归因于某个营销活动和来源邮箱。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`pipeline_id`	uuid	是	商机所属销售管道。
`stage_id`	uuid	是	初始阶段。
`contact_id`	uuid	否	关联联系人。
`name`	string	是	商机名称，1 至 255 个字符。
`value`	number	否	金额。
`currency`	string	否	ISO 货币代码。
`expected_close_date`	string (date-time)	否	预计成交日期。
`assigned_to`	uuid	否	负责人，组织成员的用户 ID。
`campaign_id`	uuid	否	归因的营销活动。
`source_mailbox_id`	uuid	否	产生原始回复的发件邮箱。

{
  "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
  "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
  "name": "Acme renewal",
  "value": 12000,
  "currency": "USD",
  "expected_close_date": "2026-07-15T00:00:00Z",
  "assigned_to": "bb22cc33-dd44-4ee5-86ff-770011223344"
}

响应

201 Created，包含创建的商机对象。新商机默认为 status: "open"。

{
  "id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
  "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
  "name": "Acme renewal",
  "value": 12000,
  "currency": "USD",
  "status": "open",
  "expected_close_date": "2026-07-15T00:00:00Z",
  "created_at": "2026-06-12T10:10:00Z",
  "updated_at": "2026-06-12T10:10:00Z"
}

搜索商机

POST /crm/deals/search

支持多条件筛选和服务端分页的商机搜索。所有筛选均可选，空请求体匹配组织的全部商机。筛选条件放在 JSON 请求体中，limit 和 cursor 则为查询参数。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`limit`	query	int	每页数量，范围 1 至 200，默认 50。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。第一页省略。

请求体

字段	类型	必填	说明
`query`	string	否	不区分大小写地匹配商机名称。
`statuses`	string[]	否	`open`、`won`、`lost` 中的任意项。
`pipeline_ids`	string[]	否	限定为这些销售管道中的商机。
`stage_ids`	string[]	否	限定为这些阶段中的商机。
`assigned_to`	string[]	否	负责人为这些用户 ID 之一。
`campaign_ids`	string[]	否	归因营销活动为这些活动之一。
`min_value`	number	否	金额大于或等于此值。
`max_value`	number	否	金额小于或等于此值。
`close_after`	string (date-time)	否	预计成交日期不早于此日期。
`close_before`	string (date-time)	否	预计成交日期不晚于此日期。
`created_after`	string (date-time)	否	创建时间不早于此时间。
`created_before`	string (date-time)	否	创建时间不晚于此时间。
`sort_by`	string	否	取值为 `created_at`、`updated_at`、`value`、`expected_close_date`、`name` 之一。
`reverse`	boolean	否	`true` 为升序，`false` 为降序，默认降序。

{
  "query": "renewal",
  "statuses": ["open"],
  "pipeline_ids": ["5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f"],
  "min_value": 1000,
  "sort_by": "value",
  "reverse": false
}

响应

包含商机对象的 data 数组，附有关联的 contact、stage 和 campaign_name，加上标准 pagination 封装，包含不透明的 next_cursor 和准确的 total。

{
  "data": [
    {
      "id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
      "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
      "name": "Acme renewal",
      "value": 12000,
      "currency": "USD",
      "status": "open",
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-10T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 137,
    "next_cursor": "o1_NTA",
    "has_more": true
  }
}

商机摘要

POST /crm/deals/summary

使用与商机搜索相同的筛选请求体，汇总数量和金额，使顶部总计和各阶段看板列总计反映完整匹配集合，而非单页。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

请求体

与搜索商机相同。所有筛选维度均可选，空请求体汇总组织全部商机。

{
  "pipeline_ids": ["5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f"],
  "statuses": ["open", "won"]
}

响应

返回汇总对象。stages 包含各阶段数量及未结商机金额。匹配商机涉及多种货币时，mixed_currency 为 true，此时顶层金额总和应视为近似值。

{
  "total": 42,
  "open_count": 30,
  "open_value": 415000,
  "won_count": 9,
  "won_value": 220000,
  "lost_count": 3,
  "lost_value": 0,
  "currency": "USD",
  "stages": [
    {
      "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
      "count": 18,
      "value": 240000
    }
  ],
  "mixed_currency": false
}

获取商机

GET /crm/deals/:id

获取单个商机。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`id`	path	uuid	商机 ID。

响应

返回商机对象。关联的 contact、stage 和 campaign_name 由列表及搜索查询填充，此单条读取不会填充。

{
  "id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "pipeline_id": "5d8a2b1e-0c4f-4a9b-9f2e-1a2b3c4d5e6f",
  "stage_id": "7f3c1a90-2b4d-4e6f-8a01-b2c3d4e5f607",
  "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
  "name": "Acme renewal",
  "value": 12000,
  "currency": "USD",
  "status": "open",
  "expected_close_date": "2026-07-15T00:00:00Z",
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-10T09:30:00Z"
}

更新商机

PATCH /crm/deals/:id

更新商机。移到不同的 stage_id 会记录阶段变更活动；将 status 设为 won 或 lost 会写入对应的结束时间戳。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	商机 ID。

请求体

字段	类型	必填	说明
`stage_id`	uuid	否	将商机移至此阶段。
`contact_id`	uuid	否	关联联系人。
`name`	string	否	商机名称。
`value`	number	否	金额。
`currency`	string	否	ISO 货币代码。
`status`	string	否	取值为 `open`、`won`、`lost` 之一。
`expected_close_date`	string (date-time)	否	预计成交日期。
`lost_reason`	string	否	标记为丢单时记录的原因。
`assigned_to`	uuid	否	负责人，组织成员的用户 ID。

{
  "stage_id": "9c0d1e2f-3a4b-4c5d-6e7f-8a9b0c1d2e3f",
  "status": "won"
}

响应

返回更新后的商机对象。

删除商机

DELETE /crm/deals/:id

删除商机。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	商机 ID。

响应

204 No Content.

列出任务类型

GET /crm/task-types

列出组织的 CRM 任务类型，即任务代表的工作种类，例如通话、邮件或会议。组织首次列出类型时，会初始化默认类型集合。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

返回任务类型对象的 data 数组，不带分页封装。

{
  "data": [
    {
      "id": "e1d2c3b4-a5f6-4071-8293-a4b5c6d7e8f9",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "name": "Call",
      "color": "#8b5cf6",
      "position": 0,
      "created_at": "2026-05-01T09:00:00Z",
      "updated_at": "2026-05-01T09:00:00Z"
    }
  ]
}

创建任务类型

POST /crm/task-types

创建 CRM 任务类型。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`name`	string	是	类型名称，1 至 60 个字符。
`color`	string	否	类型颜色，十六进制。

{
  "name": "Demo",
  "color": "#22c55e"
}

响应

201 Created，包含创建的任务类型对象。

{
  "id": "f0e1d2c3-b4a5-4607-8293-a4b5c6d7e8f9",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "name": "Demo",
  "color": "#22c55e",
  "position": 3,
  "created_at": "2026-06-12T10:20:00Z",
  "updated_at": "2026-06-12T10:20:00Z"
}

更新任务类型

PATCH /crm/task-types/:id

修改任务类型的名称、颜色或顺序。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	任务类型 ID。

请求体

字段	类型	必填	说明
`name`	string	否	新的类型名称。
`color`	string	否	新的类型颜色，十六进制。
`position`	int	否	新的排序位置。

{
  "name": "Product demo",
  "position": 1
}

响应

返回更新后的任务类型对象。

删除任务类型

DELETE /crm/task-types/:id

删除任务类型。任务按名称引用类型，因此已有任务会保留标签，并回退为中性颜色，不会成为失去类型信息的孤立任务。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	任务类型 ID。

响应

204 No Content.

列出任务

GET /crm/tasks

列出 CRM 任务，可按联系人、商机、负责人和状态筛选，采用键集分页。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`contact_id`	query	uuid	限定为关联此联系人的任务。
`deal_id`	query	uuid	限定为关联此商机的任务。
`assigned_to`	query	uuid	限定为分配给此用户的任务。
`status`	query	string	取值为 `pending`、`in_progress`、`completed`、`cancelled` 之一。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。
`limit`	query	int	每页数量，范围 1 至 100，默认 50。

响应

任务对象的 data 数组，加上键集分页 pagination 封装。

{
  "data": [
    {
      "id": "3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
      "deal_id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
      "assigned_to": "bb22cc33-dd44-4ee5-86ff-770011223344",
      "created_by": "bb22cc33-dd44-4ee5-86ff-770011223344",
      "title": "Send renewal quote",
      "description": "Include the multi-year discount",
      "due_date": "2026-06-20T17:00:00Z",
      "priority": "high",
      "type": "Email",
      "status": "pending",
      "created_at": "2026-06-12T08:00:00Z",
      "updated_at": "2026-06-12T08:00:00Z"
    }
  ],
  "pagination": {
    "total": null,
    "next_cursor": "c1_b3BhcXVlLWN1cnNvcg",
    "has_more": false
  }
}

创建任务

POST /crm/tasks

创建 CRM 任务，可关联联系人和商机，并分配给用户或团队。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`title`	string	是	任务标题，1 至 255 个字符。
`contact_id`	uuid	否	关联联系人。
`deal_id`	uuid	否	关联商机。
`assigned_to`	uuid	否	负责人用户 ID。
`assigned_team_id`	uuid	否	负责团队 ID。
`description`	string	否	自由文本说明。
`due_date`	string (date-time)	否	截止日期。
`priority`	string	否	取值为 `low`、`medium`、`high`、`urgent` 之一。
`type`	string	否	任务类型名称，与已配置的任务类型匹配。

{
  "title": "Send renewal quote",
  "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
  "deal_id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
  "assigned_to": "bb22cc33-dd44-4ee5-86ff-770011223344",
  "due_date": "2026-06-20T17:00:00Z",
  "priority": "high",
  "type": "Email"
}

响应

201 Created，包含创建的任务对象。created_by 设为当前通过身份验证的用户。

{
  "id": "3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "contact_id": "aa11bb22-cc33-4dd4-95ee-66ff77008811",
  "deal_id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
  "assigned_to": "bb22cc33-dd44-4ee5-86ff-770011223344",
  "created_by": "bb22cc33-dd44-4ee5-86ff-770011223344",
  "title": "Send renewal quote",
  "due_date": "2026-06-20T17:00:00Z",
  "priority": "high",
  "type": "Email",
  "status": "pending",
  "created_at": "2026-06-12T10:25:00Z",
  "updated_at": "2026-06-12T10:25:00Z"
}

搜索任务

POST /crm/tasks/search

支持多条件筛选和服务端分页的任务搜索。所有筛选均可选，空请求体匹配组织的全部任务。筛选条件放在 JSON 请求体中，limit 和 cursor 则为查询参数。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`limit`	query	int	每页数量，范围 1 至 200，默认 50。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。第一页省略。

请求体

字段	类型	必填	说明
`query`	string	否	不区分大小写地匹配任务标题。
`statuses`	string[]	否	`pending`、`in_progress`、`completed`、`cancelled` 中的任意项。
`priorities`	string[]	否	`low`、`medium`、`high`、`urgent` 中的任意项。
`types`	string[]	否	任务类型名称为这些名称之一。
`assigned_to`	string[]	否	负责人用户 ID 为这些 ID 之一。
`team_ids`	uuid[]	否	任务所属团队为这些团队之一，或负责人属于其中某个团队。
`contact_id`	string	否	关联联系人。
`deal_id`	string	否	关联商机。
`due_after`	string (date-time)	否	截止日期不早于此日期。
`due_before`	string (date-time)	否	截止日期不晚于此日期。
`overdue`	boolean	否	仅返回已逾期且未完成、未取消的任务。
`sort_by`	string	否	取值为 `created_at`、`due_date`、`priority`、`title`、`updated_at` 之一。
`reverse`	boolean	否	`true` 为升序，`false` 为降序，默认降序。

{
  "statuses": ["pending", "in_progress"],
  "priorities": ["high", "urgent"],
  "overdue": true,
  "sort_by": "due_date",
  "reverse": true
}

响应

任务对象的 data 数组，加上标准 pagination 封装，包含不透明的 next_cursor 和准确的 total。

{
  "data": [
    {
      "id": "3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "created_by": "bb22cc33-dd44-4ee5-86ff-770011223344",
      "title": "Send renewal quote",
      "priority": "high",
      "type": "Email",
      "status": "pending",
      "due_date": "2026-06-20T17:00:00Z",
      "created_at": "2026-06-12T08:00:00Z",
      "updated_at": "2026-06-12T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 64,
    "next_cursor": "o1_NTA",
    "has_more": true
  }
}

任务摘要

POST /crm/tasks/summary

使用与任务搜索相同的筛选请求体汇总数量，使顶部统计，包括各状态、逾期和高优先级数量，反映完整匹配集合，而非单页。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

请求体

与搜索任务相同。所有筛选维度均可选，空请求体汇总组织的全部任务。

{
  "assigned_to": ["bb22cc33-dd44-4ee5-86ff-770011223344"]
}

响应

返回汇总计数。

{
  "total": 64,
  "pending_count": 28,
  "in_progress_count": 9,
  "completed_count": 22,
  "cancelled_count": 5,
  "overdue_count": 7,
  "high_priority_count": 11
}

获取任务

GET /crm/tasks/:id

获取单个 CRM 任务。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`id`	path	uuid	任务 ID。

响应

返回任务对象，结构与列表项相同。

{
  "id": "3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912",
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "created_by": "bb22cc33-dd44-4ee5-86ff-770011223344",
  "title": "Send renewal quote",
  "priority": "high",
  "type": "Email",
  "status": "pending",
  "due_date": "2026-06-20T17:00:00Z",
  "created_at": "2026-06-12T08:00:00Z",
  "updated_at": "2026-06-12T08:00:00Z"
}

更新任务

PATCH /crm/tasks/:id

更新 CRM 任务。将 status 设为 completed 会写入完成时间戳；其他状态会清除该时间戳。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	任务 ID。

请求体

字段	类型	必填	说明
`title`	string	否	任务标题。
`assigned_to`	uuid	否	负责人用户 ID。
`assigned_team_id`	uuid	否	负责团队 ID。
`description`	string	否	自由文本说明。
`due_date`	string (date-time)	否	截止日期。
`priority`	string	否	取值为 `low`、`medium`、`high`、`urgent` 之一。
`type`	string	否	任务类型名称。
`status`	string	否	取值为 `pending`、`in_progress`、`completed`、`cancelled` 之一。

{
  "status": "completed"
}

响应

返回更新后的任务对象。

删除任务

DELETE /crm/tasks/:id

删除 CRM 任务。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`id`	path	uuid	任务 ID。

响应

204 No Content.

选择多个任务

以下两个批量端点接受相同的选择范围，有两种形式。可以明确列出 ID：

{ "tasks": ["3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912"] }

也可以选择搜索匹配的全部任务，再排除取消选择的任务：

{
  "all": true,
  "filters": { "statuses": ["pending"], "query": "out_of_office" },
  "exclude": ["3b4c5d6e-7f80-4912-a3b4-c5d6e7f80912"]
}

字段	类型	必填	说明
`tasks`	string[]	未设置 `all` 时	任务 ID。每次请求最多 `1000` 个。
`all`	boolean	否	将选择方式从 `tasks` 切换为 `filters`。
`filters`	object	设置 `all` 时	与搜索任务使用相同请求体，因此实际操作集合与搜索返回的集合完全一致。
`exclude`	string[]	否	从解析后的集合中移除的 ID。仅在设置 `all` 时生效。

选择范围解析后超过 50,000 个任务时，会返回 selection_too_large 并拒绝，而不会只应用一部分；应缩小筛选范围，分批执行。filters 中的 assigned_to、contact_id 或 deal_id 如果不是有效 ID，会返回 invalid_filter 并拒绝。

批量更新针对整次调用只触发一个 crm.task_updated Webhook，而不是每个任务各触发一个；事件携带 metadata.bulk 和 metadata.count，不含 entity_id。批量删除不会触发事件，因为单个任务删除也不会触发。

两个端点都不接受 Idempotency-Key：它们写入最终状态而非增量，因此重复调用会收敛到相同结果，但重复调用的返回计数不同。重复删除会找到更少记录，affected 最终降至 0。重复更新仍会触及选择范围中的每一行，因为会写入 updated_at，所以 affected 不会下降；状态和优先级只是保持不变。重复完成操作不会向联系人时间线添加第二条记录，也不会改变 completed_at。

批量更新任务

PATCH /crm/tasks

为选择范围内每个任务写入状态、优先级，或两者。至少提供其中一个字段。将 status 设为 completed 会写入完成时间戳，并在每个关联联系人的时间线记录完成事件，与单任务更新一致。其他状态会清除 completed_at，因此移回 pending 的任务不会保留之前的完成时间，同样与单任务更新一致。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

上述选择对象，另加：

字段	类型	必填	说明
`status`	string	否	取值为 `pending`、`in_progress`、`completed`、`cancelled` 之一。
`priority`	string	否	取值为 `low`、`medium`、`high`、`urgent` 之一。

{
  "all": true,
  "filters": { "statuses": ["pending"], "priorities": ["high"] },
  "status": "completed"
}

响应

返回写入的任务数量，而非具体记录，因为全选可能涵盖数万个任务。

{ "affected": 128 }

批量删除任务

DELETE /crm/tasks

删除选择范围内的每个任务。请求体可为选择对象，或直接使用 ID 数组。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

{ "all": true, "filters": { "query": "out_of_office" } }

响应

{ "affected": 128 }

CRM 服务商模式

工作区可使用 HubSpot 或 Pipedrive 运行 CRM，替代 Warmbly 内置 CRM。在外部 CRM 模式下，上述端点保持相同结构，返回的记录来自服务商并镜像到 Warmbly。HubSpot 模式下：

创建、更新或删除商机、任务和备注时，先写入 HubSpot，再在本地保存。HubSpot 拒绝时会返回错误，不保存任何内容；参阅CRM 服务商操作被拒绝的情况；
创建、更新或删除销售管道、阶段和任务类型时，返回 409 crm_managed_externally。GET /crm/pipelines 只列出 HubSpot 销售管道，GET /crm/task-types 返回 HubSpot 的四种类型（To-do、Call、Email、LinkedIn）；
未提供 pipeline_ids 筛选时，POST /crm/deals/search 和 POST /crm/deals/summary 只涵盖 HubSpot 销售管道，排除仅存在于 Warmbly 管道中的商机；
将商机 status 设为 won 或 lost，会将其移到管道中该类型的第一个结束阶段；将商机移到结束阶段，也会设置其 status。assigned_to 必须是已匹配 HubSpot 负责人的成员，否则返回 400 crm_owner_unmapped。

Pipedrive 模式遵循相同原则，但采用 Pipedrive 的数据模型：

任务对应 Pipedrive 活动。GET /crm/task-types 返回公司的活动类型；任务的 status 会写为已完成（completed、cancelled）或未完成，priority 则保留在 Warmbly；
商机 status 对应 Pipedrive 自身的商机状态，因此 won 和 lost 不改变商机阶段。lost_reason 随 lost 状态写入。assigned_to 必须是已匹配 Pipedrive 用户的成员，否则返回 400 crm_owner_unmapped；
Pipedrive 没有生命周期阶段或潜在客户状态。联系人的 lifecycle_stage 是其第一个人员标签，使用 GET /crm/metadata 中的 ID；lead_status 始终为空。

存在于外部 CRM 的商机、任务、备注和销售管道带有 external 对象；镜像管道中的阶段带有该服务商的阶段元数据。非外部 CRM 模式下，两者均省略。

字段	类型	说明
`external.provider`	string	`hubspot` 或 `pipedrive`。
`external.external_id`	string	外部 CRM 的记录 ID。
`external.url`	string	在外部 CRM 中打开记录的位置：商机、任务视图（Pipedrive 中为活动关联的商机，否则为活动列表）、备注关联的联系人，或销售管道。未知时省略。
`external.synced_at`	string (date-time)	上次向外部 CRM 写入或从其读取该记录的时间。
`external.owner_name`	string	商机或任务的负责人不是工作区成员时，返回外部 CRM 的负责人，此时 `assigned_to` 为空。
`stages[].closed`	boolean	该阶段是 HubSpot 的结束阶段。为 false 时省略；Pipedrive 中始终省略。
`stages[].won`	boolean	该阶段是 HubSpot 的赢单结束阶段。为 false 时省略；Pipedrive 中始终省略。
`stages[].probability`	number	外部 CRM 对该阶段设置的商机成交概率，范围 `0` 至 `1`。

{
  "id": "1f2e3d4c-5b6a-4789-90ab-cdef01234567",
  "name": "Acme renewal",
  "status": "open",
  "external": {
    "provider": "hubspot",
    "external_id": "18342007291",
    "url": "https://app.hubspot.com/contacts/4711/record/0-3/18342007291",
    "synced_at": "2026-06-10T09:30:04Z",
    "owner_name": "Dana Kim"
  }
}

以下路由用于配置外部 CRM 模式，并读取联系人的外部 CRM 数据；每条路由均操作工作区当前使用的 CRM。除 GET /crm/settings、GET /crm/owners、GET /crm/sync 和 GET /crm/backfill 外，工作区未启用外部 CRM 模式时均返回 409 crm_not_connected；实例不支持外部 CRM 服务商时返回 501。

获取 CRM 设置

GET /crm/settings

返回工作区 CRM 模式、设置选项和已连接账户。从未选择过的工作区返回 provider: "native" 及默认选项。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

{
  "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "provider": "hubspot",
  "connection_id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b",
  "config": {
    "activity": { "sent": true, "replies": true, "bounces": true, "unsubscribes": true, "opens": false, "clicks": false, "meetings": true },
    "create_contacts": true,
    "create_companies": true,
    "write_properties": true,
    "positive_reply": { "lead_status": "IN_PROGRESS", "lifecycle_stage": "", "create_deal": false },
    "exit_rules": { "deal_created": true, "lifecycle_stages": ["opportunity", "customer"], "opted_out": true },
    "guards": { "skip_lifecycle_stages": ["customer", "evangelist"], "skip_open_deals": true, "skip_other_owners": false, "skip_opted_out": true },
    "deal_pipelines": [],
    "display_properties": ["jobtitle"],
    "field_map": { "first_name": "firstname", "last_name": "lastname", "company": "company", "phone": "phone" },
    "field_direction": { "first_name": "both", "last_name": "both", "company": "both", "phone": "both" }
  },
  "setup_completed_at": "2026-06-01T12:04:00Z",
  "updated_at": "2026-06-01T12:04:00Z",
  "account": {
    "external_id": "4711",
    "name": "acme.com",
    "app_url": "https://app.hubspot.com/contacts/4711",
    "status": "connected",
    "health": "healthy"
  }
}

连接缺少外部 CRM 模式所需权限时，account.missing_scopes 会列出缺失权限。config.for 标明这些选项适用于哪个服务商。Pipedrive 模式下，account.external_id 为 Pipedrive 公司 ID，config.positive_reply.create_lead 会在收到有兴趣的回复时，将该人员添加到 Pipedrive 的 Leads Inbox。

更新 CRM 设置

PUT /crm/settings

选择 CRM 并保存设置选项。切换到 HubSpot 时，若开启 write_properties，会在 HubSpot 创建 Warmbly 联系人属性组，并在后台启动首次拉取。切换到 Pipedrive 时，未发送 config 则根据公司自身标签填充标签规则，然后添加 Warmbly 人员字段、注册变更通知并启动首次拉取。从一个服务商切换到另一个时，会替换原连接，原服务商保存的选项会重置为新服务商默认值。此操作写入最终状态，因此可安全重试。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings

请求体

字段	类型	必填	说明
`provider`	string	否	`native`、`hubspot` 或 `pipedrive`。
`connection_id`	uuid	否	工作区的 HubSpot 或 Pipedrive 集成连接。首次使用该服务商时必须提供。
`config`	object	否	完整选项集合，替换已存集合。结构见上方响应。
`complete_setup`	boolean	否	将设置向导标为已完成。

config 保存前会验证：field_map 的键可为 first_name、last_name、email、company、phone 或 custom:<key>；每个 field_direction 条目必须为 push、pull 或 both，并指定已映射字段；deal_pipelines 为外部 CRM 管道 ID，空表示全部，最多 50 项；display_properties 最多 40 项，field_map 最多 100 项，各生命周期阶段列表最多 20 项。positive_reply.create_deal 需要 deal_pipeline_id 和 deal_stage_id，它们是镜像管道及阶段在 Warmbly 中的 ID。

{
  "provider": "hubspot",
  "connection_id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b",
  "complete_setup": true
}

响应

设置对象，与 GET /crm/settings 返回相同。连接缺少外部 CRM 模式所需权限时，返回 409 crm_reauth_required；connection_id 不是工作区连接到该服务商的连接时，返回 400。

获取 CRM 元数据

GET /crm/metadata

返回设置选择器所需的服务商选项：生命周期阶段、潜在客户状态、任务类型、联系人属性（排除隐藏和计算属性）及销售管道。这里的管道使用服务商 ID，与 deal_pipelines 要求一致。对于 Pipedrive，lifecycle_stages 为人员标签，lead_statuses 为空，task_types 为活动类型；properties 先列出标准人员键（first_name、last_name、name、phone、org_name），再按代码列出自定义字段。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

{
  "lifecycle_stages": [{ "value": "lead", "label": "Lead" }, { "value": "customer", "label": "Customer" }],
  "lead_statuses": [{ "value": "IN_PROGRESS", "label": "In Progress" }],
  "task_types": [{ "value": "TODO", "label": "To-do" }, { "value": "CALL", "label": "Call" }],
  "properties": [{ "name": "jobtitle", "label": "Job Title", "type": "string", "group_name": "contactinformation", "read_only": false }],
  "pipelines": [{ "value": "default", "label": "Sales Pipeline" }]
}

列出 CRM 负责人

GET /crm/owners

列出外部 CRM 负责人，即 Pipedrive 用户，以及每人匹配到的成员。默认按邮件地址匹配；手动选择的匹配（user_pinned）优先。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

{
  "data": [
    {
      "external_id": "82731",
      "email": "[email protected]",
      "first_name": "Dana",
      "last_name": "Kim",
      "user_id": "bb22cc33-dd44-4ee5-86ff-770011223344",
      "user_pinned": false,
      "archived": false
    }
  ]
}

匹配 CRM 负责人

PUT /crm/owners/:externalId

将外部 CRM 负责人匹配到成员，或用 null 清除匹配。此处设置的匹配会在再次按邮件地址匹配时保留。可安全重试。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings

参数	位置	类型	说明
`externalId`	path	string	外部 CRM 负责人，即 Pipedrive 用户的 ID。

请求体

字段	类型	必填	说明
`user_id`	uuid or null	是	成员 ID，或用 `null` 清除。

响应

204 No Content。负责人或成员不在工作区时返回 404。

获取同步健康状态

GET /crm/sync

报告同步队列，包括待处理、失败和最近 24 小时已完成项，最近 50 次失败、各类拉取的上次运行情况，以及镜像记录数量。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

{
  "pending": 2,
  "failed": 1,
  "done_24h": 418,
  "last_synced_at": "2026-06-10T09:31:12Z",
  "cursors": [
    { "object_type": "deals", "cursor_at": "2026-06-10T09:30:58Z", "last_run_at": "2026-06-10T09:31:02Z" }
  ],
  "failures": [
    {
      "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "organization_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "provider": "hubspot",
      "kind": "push_deal",
      "subject": "Acme renewal",
      "status": "failed",
      "attempts": 6,
      "next_attempt_at": "2026-06-10T03:12:00Z",
      "last_error": "HubSpot refused the change: Property \"amount\" is required",
      "created_at": "2026-06-09T18:02:00Z",
      "updated_at": "2026-06-10T03:12:04Z",
      "finished_at": "2026-06-10T03:12:04Z"
    }
  ],
  "counts": { "contacts": 1820, "deals": 64, "tasks": 211, "pipelines": 2, "owners": 9 }
}

cursors[].object_type 为 owners、pipelines、deals、tasks 或 contacts；上次运行失败时设置 last_error。

立即同步

POST /crm/sync

在后台启动从外部 CRM 完整拉取。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings

响应

202 Accepted。30 秒内再次调用返回 429 crm_sync_running。

重试或丢弃失败的同步任务

POST /crm/sync/retry · POST /crm/sync/discard

将失败同步项重新入队，或丢弃它们。不提供请求体，或 ids 为空时，影响全部失败项。可安全重试：已经重新入队或丢弃的条目不再处于失败状态。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings

请求体

字段	类型	必填	说明
`ids`	array of uuid	否	要处理的失败项，最多 500 个。

响应

{ "affected": 3 }

将 Warmbly CRM 数据复制到服务商

GET /crm/backfill · POST /crm/backfill

GET 统计仅存在于 Warmbly、尚未存在于任何已连接 CRM 的商机、任务和备注；从工作区以前使用的 CRM 镜像而来的记录不计入。POST 在后台一次性复制所选类型：商机移到第一个镜像销售管道，优先保留同名阶段，否则使用第一个与其状态匹配的阶段；在 Pipedrive 中则使用第一个阶段，并保留商机状态。已复制的记录不会重复复制，已有运行时再次 POST 会合并到当前运行。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings

请求体

字段	类型	必填	说明
`deals`	boolean	否	复制商机。
`tasks`	boolean	否	复制任务。
`notes`	boolean	否	复制备注。

至少一项必须为 true。

响应

GET 返回 { "deals": 12, "tasks": 40, "notes": 7 }。POST 返回 202 Accepted；进度显示在同步健康状况中。

获取联系人的 CRM 记录

GET /crm/contacts/:id

返回最近一次镜像的 Warmbly 联系人在外部 CRM 中的数据：负责人、生命周期阶段（Pipedrive 中为标签）、潜在客户状态、公司（Pipedrive 中为组织）、退订状态，以及 display_properties 选定的属性。未关联到服务商的联系人只返回 linked: false。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

参数	位置	类型	说明
`id`	path	uuid	Warmbly 联系人 ID。

响应

{
  "provider": "hubspot",
  "linked": true,
  "external_id": "51234",
  "url": "https://app.hubspot.com/contacts/4711/record/0-1/51234",
  "owner": { "external_id": "82731", "email": "[email protected]", "first_name": "Dana", "last_name": "Kim", "user_pinned": false, "archived": false },
  "lifecycle_stage": { "value": "lead", "label": "Lead" },
  "lead_status": { "value": "IN_PROGRESS", "label": "In Progress" },
  "company": { "external_id": "9921", "name": "Acme", "domain": "acme.com", "url": "https://app.hubspot.com/contacts/4711/record/0-2/9921" },
  "opted_out": false,
  "properties": [{ "name": "jobtitle", "label": "Job Title", "value": "Head of Sales" }],
  "synced_at": "2026-06-10T09:30:04Z"
}

刷新联系人的 CRM 记录

POST /crm/contacts/:id/refresh

立即拉取联系人的外部 CRM 记录、商机、任务和备注。未关联的联系人会按邮件地址查找，服务商中存在时建立关联，不会创建任何记录。每个联系人均有防抖限制，因此打开联系人时可安全调用：HubSpot 每分钟最多一次拉取、每五分钟一次查找；Pipedrive 按公司每日计量 API 用量，因此人员记录最多每两分钟重读一次，其商机、活动和备注每六小时一次，未关联联系人每十五分钟查找一次。

身份验证：权限范围 READ_CRM · 组织权限 view_contacts

响应

联系人的 CRM 记录，结构与 GET /crm/contacts/:id 相同。

将联系人关联到 CRM

POST /crm/contacts/:id/link

按邮件地址在外部 CRM 中查找联系人；工作区允许创建联系人时，未找到则在外部创建，然后拉取其商机、任务和备注。可安全重试：已关联联系人保持关联到同一记录。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

响应

联系人的 CRM 记录，结构与 GET /crm/contacts/:id 相同。外部 CRM 中不存在联系人且未允许创建时，返回 404 crm_contact_missing。

更新联系人的 CRM 记录

PATCH /crm/contacts/:id

先向外部 CRM 写入联系人的负责人、生命周期阶段或潜在客户状态，再更新镜像。在 Pipedrive 中，lifecycle_stage 设置人员标签，使用 GET /crm/metadata 中的 ID，留空可清除；lead_status 会被忽略。

身份验证：权限范围 WRITE_CRM · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`owner_external_id`	string	否	外部 CRM 负责人，即 Pipedrive 用户的 ID。
`lifecycle_stage`	string	否	来自 `GET /crm/metadata` 的生命周期阶段值。
`lead_status`	string	否	来自 `GET /crm/metadata` 的潜在客户状态值。

每个值最多 100 个字符。

响应

更新后的外部 CRM 记录，结构与 GET /crm/contacts/:id 相同。联系人未关联到服务商时，返回 404 crm_contact_missing。

列出 CRM 列表

GET /crm/lists

列出 HubSpot 账户的联系人列表，最新优先，用于导入。需要 HubSpot 可选的列表权限，连接缺少该权限时返回 409 crm_reauth_required。Pipedrive 模式下，返回公司的已保存人员筛选器，按最近修改优先排列；每项包含 size: -1（Pipedrive 不统计筛选器结果数）和 dynamic: true。

身份验证：权限范围 READ_CRM · 组织权限 manage_contacts

参数	位置	类型	说明
`q`	query	string	按列表名称筛选，最多 200 个字符。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。无法识别时返回 `400`。
`limit`	query	int	每页数量，范围 1 至 100，默认 25。

响应

{
  "data": [
    { "external_id": "212", "name": "Q3 webinar attendees", "size": 840, "dynamic": true, "updated_at": "2026-06-08T15:20:00Z" }
  ],
  "pagination": { "next_cursor": "bGlzdDoyNQ", "has_more": true }
}

预览 CRM 列表导入

POST /crm/lists/preview

统计列表将导入和跳过哪些联系人，并按跳过原因分类，不写入任何内容。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts

请求体

字段	类型	必填	说明
`list_id`	string	是	HubSpot 列表 ID 或 Pipedrive 筛选器 ID，最多 64 个字符。
`apply_guards`	boolean	否	跳过工作区导入保护规则排除的联系人（`config.guards`）。

响应

{
  "list_name": "Q3 webinar attendees",
  "total": 840,
  "included": 772,
  "skipped": [
    { "reason": "opted_out", "label": "Opted out of email in HubSpot", "count": 31 },
    { "reason": "lifecycle", "label": "Lifecycle stage is Customer", "count": 25 },
    { "reason": "no_email", "label": "No email address", "count": 12 }
  ],
  "sample": [{ "email": "[email protected]", "first_name": "Sam", "last_name": "Lee", "company": "Globex" }],
  "truncated": false
}

reason 为 opted_out、lifecycle、open_deal、other_owner、no_email 或 duplicate。一次导入最多读取 25,000 个联系人；列表更大时，truncated 为 true。

导入 CRM 列表

POST /crm/lists/import

将列表转为联系人导入草稿，在常规导入审核中完成。请求体和跳过规则与预览相同。导入的联系人会在数分钟后关联到外部 CRM 记录。草稿归调用者所有；使用 API 密钥时，归创建该密钥的成员所有。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts

响应

201 Created.

{
  "import_id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
  "preview": { "list_name": "Q3 webinar attendees", "total": 840, "included": 772, "skipped": [], "sample": [], "truncated": false }
}

列表中没有任何可导入联系人时，返回 400。

错误

所有端点失败时均返回标准错误封装，例如路径 UUID 参数格式错误或请求体无效。完整列表见错误码。

{
  "error": "invalid_request",
  "message": "invalid request body",
  "code": "INVALID_REQUEST",
  "request_id": "req_8f2c1a90b34d4e6f"
}

本页目录