通过 API 管理线索

本节提供对您自己的 CRM 线索的程序化访问：网站或外部表单可以把咨询直接送进后台，您的系统也可以读取它们并推动其在各状态之间流转。

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

列表

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。

单条线索

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

expand 可以附带状态与操作的历史记录（history）以及附件文档列表（documents）。

线索的数据结构

• id、status、type、priority、source、tags、isArchived
• createdAt、updatedAt、lastActivityAt
• customer — 姓名、国家、即时通讯，以及 contact 块（phone、email、messengerHandle、profileUrl）
• budget — { value, currency }
• intent — 城市、区域、交易类型以及客户想要什么
• comments — 客户的留言和您自己的备注，分开存放
• object — 该咨询所指向的房源
• deadline、reminder
• 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": "olena@example.com" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Looking for a two-room flat near the metro",
    "priority": "warm",
    "consent": true
  }'

必填项：customer.name，以及 customer.contact 中至少一种联系方式。type 为 buy（默认）或 rent。priority 为 hot、warm 或 cold。若咨询针对某个具体房源，可以附上 objectId；tags 中最多可放十个您自定义的标签。

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。

收起线索

DELETE /leads/{id}

这是归档而非删除：线索会从常规列表中消失，但仍可通过 ?archived=true 访问。

为线索匹配房源

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

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

机构线索池

机构密钥可以执行两类线索池操作：

POST /leads/{id}/claim               把池中的线索领给自己
POST /leads/{id}/claim?assignTo=…    把线索指派给团队成员
POST /leads/{id}/return-to-pool      把线索退回池中

两者都需要机构中允许分配线索的角色。个人密钥会被拒绝；领取他人已领走的线索会返回 409。

跟踪变化

与其轮询列表，不如订阅 lead.created 和 lead.updated 事件 — 参见 Webhook。事件本身不含个人数据：它只说明哪条线索发生了变化，具体卡片需另发一次请求读取。

相关文章

• 对象（读取） — 线索所指向的房源目录。
• Webhook — 新增和变更线索的事件。
• 错误 — 如何解读一次拒绝。