联系人、商机与旅程 API

这些端点让你自己的代码、Zapier 或 n8n 可以操作你的账户：添加联系人、创建和移动商机、把联系人加入旅程，以及读取这些调用所需的 ID。它们使用与发送 API 相同的 API 密钥。

Authorization: Bearer mia_live_...

每组端点每个密钥每分钟最多 60 次请求，超过会返回 429。错误以 4xx 状态码和 {"error": "…"} 返回。包含所有响应格式的完整规范见 OpenAPI 规范。

联系人

创建或更新

POST /api/v1/contacts 把地址添加到联系人列表；如果已存在，则更新：

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

新联系人返回 201，更新返回 200，并附带保存后的联系人。要一次发送最多 500 个，改用 {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}，响应会返回数量统计。

每个地址在保存时都会被验证。API 从不记录同意答案，所以这些联系人和以前一样会收到邮件。如果单个联系人会让列表超出套餐的联系人上限，返回 409。

查找

GET /api/v1/[email protected] 返回该地址在每个列表中的联系人，按从新到旧排序。加上 &listId= 只在一个列表中查找。每次查找都会像在控制台查看联系人一样，记录到账户的个人数据访问日志中。

列表

GET /api/v1/lists 返回每个联系人列表的 id、name、fields 和 rowCount，不含任何联系人数据。

商机

创建

POST /api/v1/deals：

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 8000,
  "currency": "CNY"
}

用 email，或者 listId 加 rowId 指定联系人。只提供邮箱时，商机会放在包含该地址、最近更新的那个列表上。不提供 pipelineId 和 stageId 时，商机进入默认管道的第一个进行中阶段。currency 默认为 USD。

发送 Idempotency-Key 请求头（例如订单号）可让重试变得安全。使用相同的键重复请求，会返回 200 和 "created": false，而不会创建第二个商机。

更新或移动

PATCH /api/v1/deals/{id} 接受 title、value、currency 和 stageId。移到赢单或丢单阶段会结束商机。整个请求体会先校验，因此未知的阶段不会造成任何改动。移动会触发旅程触发器 商机阶段变化 和 Webhook deal.stage_changed，与在看板上移动相同。

管道

GET /api/v1/pipelines 返回你的管道（默认管道在前），每个管道附带其阶段（id、name、kind）。用它查找要把商机移到的 stageId。

旅程

GET /api/v1/journeys 列出你的旅程，包括 ID、名称、触发器以及是否开启。?trigger=api 只返回你的代码可以加入联系人的旅程。

POST /api/v1/journeys/{id}/trigger 配合 {"email": "…", "listId": "…"}，把联系人加入触发器为 API 调用 的旅程。参见旅程。

示例事件

GET /api/v1/events/sample?type=deal.stage_changed 返回 {"events": [ … ]}，其中是该类型的一个 Webhook 信封示例；不带 type 时返回每种类型各一个。自动化工具用它在真实事件到来之前向你展示字段。

Webhook

GET、POST /api/v1/webhooks 和 DELETE /api/v1/webhooks/{id} 用于管理事件订阅。参见 Webhook 与事件。