Swipe Match finds a broker for a client and offers the lead to brokers in turn. Through the API a partner broker (or an agency) sees the leads offered to and assigned to them and reports their steps with the client. Reading needs the leads:read scope, events need leads:write. Not charged.
Leads
curl "https://developers.grem.capital/api/v1/match/leads?view=active&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /match/leads:
| Parameter | Description |
|---|---|
view | active (default) - leads assigned to you; inbox - open offers to you. An agency key sees the leads and offers of the agency's agents |
stage | stage filter |
page, limit | page; limit up to 50, default 20; limit or page below 1, limit over 50 or page over 1000 - 400 |
GET /match/leads/{id} - one lead, GET /match/leads/{id}/events - its history (your events and offers; no money or service events and no client ratings). Someone else's lead - 404.
Until Swipe Match is open for API access on your account, these requests answer 409 with code: not_available.
Lead fields:
| Field | Description |
|---|---|
id, stage | id and stage |
clientType | buyer or seller |
country, objectId, objectIds | country and the listings the request is about |
budget | min, max, currency |
answers | the client's answers: budget, timeline, payment |
qualScore, qualBand | lead quality score |
clientInitial | the first letter of the client's name |
offer | your open offer: id, wave, offeredAt, deadline |
contactDeadline, meetingDeadline | when to contact and to meet by |
deal, reservation, dealObjects | deal and reservation data |
client | the client's name and phone - only after the lead is assigned to you and the contact is revealed |
brokerId | the broker whose view is shown |
fee | the platform's fee on this lead for you: none, percent (that percent of the commission you receive, in percent) or contract (by agreement); never amounts |
Stages (stage): new, offered, intro, match, contact, meeting_scheduled, meeting_held, contract, deal, closed, lost.
Your steps with a lead
POST /match/leads/{id}/events - only for a lead assigned to you. The module checks the step is allowed at the current stage.
event | Fields | Meaning |
|---|---|---|
FIRST_CONTACT | channel: phone (default) or messenger | you reached the client |
RESERVATION | amount, currency (3 letters), date; documentFileId - optional | the client paid a reservation |
STAGE_ROLLBACK | reasonCode: client_withdrew, seller_withdrew, financing_failed, documents, other; text - up to 500 | move the lead back a stage |
LEAD_LOST | reasonCode: client_refused, client_unreachable, bought_elsewhere, not_target, other; text. Another reason - 400 | the lead is lost |
DEAL_CLOSED | objectId, amount, currency, date, documentFileId; commissionReceived, commissionCurrency - optional | the deal is closed |
documentFileId - the id of a file uploaded with POST /uploads (Files). A reasonCode outside its list is 400; for LEAD_LOST with other the text is required (400 without it); for STAGE_ROLLBACK the text is kept only with other.
curl -X POST https://developers.grem.capital/api/v1/match/leads/LEAD_ID/events \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fc-LEAD_ID-1" \
-d '{"event":"FIRST_CONTACT","channel":"phone"}'
Response: lead - the lead after the transition, replay: true - when it is a retry with the same Idempotency-Key. Client steps are not sent through the API. Idempotency-Key here is 8-128 characters: letters, digits, _ . : -; another format is 400 validation.
Refusals come as 409 with title: business_rule and the reason in code:
| Reason | code |
|---|---|
| the step is not available at the current stage | invalid_transition |
| a client event, brokers do not send it | client_event_rejected |
| the module is not open to the API yet | not_available |
Events
match.lead.offered, match.lead.offer_closed, match.lead.matched, match.lead.updated, match.lead.unassigned - see Webhooks. Events never contain the client's contacts.