通过 API 管理线索

最后更新: 2026-10-03阅读约 6 分钟

本节提供对 CRM 中您自己的线索的编程访问：网站或外部表单可以把咨询直接发送到后台，您的系统可以读取它们并推进状态。

基础地址：https://developers.grem.capital/api/v1。

线索是私密的。与公开的房源目录不同，没有相应权限范围就无法访问：读取需要 leads:read，修改需要 leads:write。您只能看到自己作为发送方或接收方的线索。请求不收费。

列表

GET /leads?status=new&type=buy&priority=hot&page=1&limit=20
Authorization: Bearer gsk_live_...

筛选条件：status、type、priority、source、role、archived、pool、from、to、page、limit、sort。已归档的线索不在普通列表中：请加上 archived=true。pool=true（仅机构密钥）：机构公共池中的线索；个人密钥会忽略它。

超出范围的 limit（1-50，默认 20）和 page（从 1 开始）会被限制到范围内，而不会被拒绝。已知参数的其他无效值（未知的枚举值、page 不是整数、from 或 to 中的日期无效）以 400 validation 拒绝，并指出字段名。

单条线索

GET /leads/{id}?expand=history,documents

expand 会附加状态和操作历史（history）以及附带的文件（documents）。

线索格式

id、status、type、priority、source、tags、isArchived；type 为 buy、rent、viewing、sell、contract、transfer 或 user
createdAt、updatedAt、lastActivityAt
customer：姓名、国家、即时通讯工具以及 contact 块（phone、email、messengerHandle、profileUrl）
budget：{ value, currency }
intent：城市、区域、交易类型和客户意向
comments：客户的留言和您的备注，分开存放
object：咨询所涉及的房源
agency：仅机构线索，包含机构 ID 以及线索是否在公共池中

不会返回其他经纪人的联系方式、内部评分或系统标记。

提交咨询

curl -X POST https://developers.grem.capital/api/v1/leads \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-07-0001" \
  -d '{
    "customer": {
      "name": "Olena Kovalchuk",
      "country": "UA",
      "contact": { "phone": "+380971234567", "email": "[email protected]" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "想找地铁附近的两居室",
    "priority": "warm",
    "consent": true
  }'

必填：customer.name，以及 customer.contact 中至少一种联系客户的方式。type：buy（默认）或 rent。priority：hot、warm 或 cold。如果咨询针对特定房源，请加上 objectId，还可以添加最多十个自定义 tags。

Idempotency-Key 可以防止重复：如果您的表单在超时后重发请求，线索不会被创建两次。见幂等性。

pool: true 会把咨询发送到公共分配池，而不是您的 CRM。默认情况下线索发给您。

通过 API 创建的每条线索在后台都标有「API」来源，便于区分。

修改线索

PATCH /leads/{id}
{ "status": "in progress", "priority": "hot", "tags": ["mortgage"], "brokerComments": "..." }

可以修改状态、优先级、标签和您自己的备注。一个字段即可。状态：new、in progress、processing、agreement、closed、not target、failed。适用后台规则：带房源的线索通过后台的结案流程关闭（code: finalize），等待佣金的线索保持其状态（fee_pending），有合同的已关闭交易只能在后台修改（closed）：返回 422，原因见 code。其他原因：sender（您已将线索转交他人，由接收方处理）、module（Swipe Match 线索，其状态由模块决定）、agreement、network_readonly、forbidden。

移除线索

DELETE /leads/{id}

线索会被归档而非删除：它会离开普通列表，但仍可通过 ?archived=true 访问。有生效合同或结案协议的线索、未结案的带房源已关闭线索以及等待佣金的线索不会被归档：返回 422，code 为 contract_active、agreement、finalize 或 fee_pending。

线索匹配的房源

GET /leads/{id}/matches?page=1&limit=20

返回符合客户需求的房源：类型、城市和预算取自线索本身或关联的房源。免费。

机构线索池

机构密钥有两个线索池操作：

POST /leads/{id}/claim               从池中领取线索
POST /leads/{id}/claim?assignTo=...  分配给团队成员
POST /leads/{id}/return-to-pool      将线索退回池中

领取：默认分配给机构所有者；assignTo（成员 ID）可由所有者或经理传入。
退回池中：经理及以上，或该线索被分配给的经纪人。可选请求体：{"reason": "..."}。被池规则归档的线索返回带 code: pool_archived 的 422：请先在后台恢复它。
使用个人密钥或角色不足：带 title: forbidden 的 403；领取已不在池中的线索：404。
两个操作都会发送 lead.updated 事件。

跟踪变化

无需轮询列表，订阅 lead.created 和 lead.updated 即可，见 Webhooks。事件不含个人数据：只说明哪条线索发生了变化；线索详情需单独请求读取。

房源：线索所关联的目录。
Swipe Match：面向合作经纪人的模块线索。
Webhooks：新线索和线索变更事件。
错误：理解拒绝原因。

这篇文章对您有帮助吗？