Docs

Leads over the API

Last updated: 2026-09-074 min read

This section gives programmatic access to your own CRM leads: a site or an external form can submit enquiries straight into the cabinet, and your system can read them and move them through the statuses.

Base URL: https://developers.grem.capital/api/v1.

Leads are private. Unlike the public object catalog, there is no scope-free access here: reading needs leads:read, changes need leads:write. You only ever see leads where you are the sender or the recipient.

The list

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

Filter parameters: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Archived leads are left out of the normal listing - add archived=true.

One lead

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

expand adds the status and action history (history) and the list of attached documents (documents).

The lead shape

  • id, status, type, priority, source, tags, isArchived
  • createdAt, updatedAt, lastActivityAt
  • customer - name, country, messenger, and a contact block (phone, email, messengerHandle, profileUrl)
  • budget - { value, currency }
  • intent - city, districts, deal type and what the client is after
  • comments - the client's comment and your own, separately
  • object - the listing the enquiry relates to
  • deadline, reminder
  • agency - present only on agency leads: the agency id and whether the lead is sitting in the shared pool

Other brokers' contacts, internal scoring and service flags are never returned.

Submit an enquiry from outside

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
  }'

Required: customer.name and at least one way to reach them in customer.contact. type is buy (the default) or rent. priority is hot, warm or cold. You can add an objectId when the enquiry is about a specific listing, and up to ten of your own labels in tags.

The Idempotency-Key header saves you from duplicates: if your form retried after a timeout, the lead is not created twice. See Idempotency.

The pool: true flag routes the enquiry into the shared pool for distribution instead of your own CRM. By default the lead lands with you.

Every lead created through the API is marked with the source "API" in the cabinet, so it stands apart from the rest.

Change a lead

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

You can change the status, the priority, the labels and your own comment. One field is enough. Available statuses: new, in progress, processing, agreement, closed, not target, failed.

Put a lead away

DELETE /leads/{id}

This archives rather than deletes: the lead drops out of the normal listing but stays reachable with ?archived=true.

Matching inventory for a lead

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

Returns listings that answer the client's request: the type, city and budget come from the lead itself or from the listing attached to it. The call is free.

The agency pool

Agency keys get two pool actions:

POST /leads/{id}/claim               take a pool lead for yourself
POST /leads/{id}/claim?assignTo=…    assign the lead to a team member
POST /leads/{id}/return-to-pool      hand the lead back to the pool

Both need an agency role that allows lead distribution. A personal key is refused, and claiming a lead someone already took returns 409.

Watching for changes

Instead of polling the list, subscribe to the lead.created and lead.updated events - see Webhooks. The event itself carries no personal data: it only says which lead changed, and you read the card in a separate request.

Was this article helpful?