API reference
Leads
A lead is a deal: an opportunity with an amount that moves through the stages of a pipeline until it is won or lost.
The lead object
{
"id": "lead_01j8z7c2d4f6g8h0j2k4m6n8p0",
"number": 1042,
"name": "Website order #1042",
"amount": 150000000,
"currency": "UZS",
"pipeline_id": "pipeline_01j8z5y1b3c5d7e9f1g3h5j7k9",
"stage_id": "stage_01j8z5z0a2b4c6d8e0f2g4h6j8",
"owner_id": "member_01j8z5x7y9z1a3b5c7d9e1f3g5",
"owner": { "id": "member_01j8z5x7y9z1a3b5c7d9e1f3g5", "name": "Aziz Rahimov" },
"contact_id": "contact_01j8z7c1a3b5c7d9e1f3g5h7j9",
"contact": { "id": "contact_01j8z7c1a3b5c7d9e1f3g5h7j9", "name": "Dilnoza Karimova", "phones": ["+998901234567"] },
"company_id": null,
"company": null,
"source": "website",
"utm": { "utm_source": "google", "utm_campaign": "autumn" },
"referrer": "https://www.google.com/",
"landing_page": "https://shop.uz/autumn",
"tags": ["vip"],
"custom": { "delivery_date": "2026-10-02" },
"position": 3,
"stage_entered_at": "2026-09-27T09:41:12.482913Z",
"closed_at": null,
"loss_reason": "",
"created_at": "2026-09-25T14:03:11.52Z",
"updated_at": "2026-09-27T09:41:12.482913Z"
}| Field | Type | Description |
|---|---|---|
id | string | lead_… |
number | integer | Human number, unique in the workspace (#1042) |
name | string | Up to 255 characters. Kweko names a lead without a name after its number. |
amount | integer | In the smallest currency unit (tiyin for UZS), zero or more. See Money. |
currency | string | Three letters; the workspace's currency by default |
pipeline_id, stage_id | string | Where the lead is. See Pipelines. |
owner_id, owner | string, object or null | The responsible member |
contact_id, contact | string, object or null | The main contact. More contacts: lead contacts. |
company_id, company | string, object or null | The company |
source | string | Where the lead came from, up to 64 characters (website, instagram, …) |
utm | object | utm_source, utm_medium, utm_campaign, utm_content, utm_term |
referrer, landing_page | string or null | The website the client came from and the first page of that visit (website forms, web chat), absolute http(s) URLs |
tags | array of strings | Up to 10 tag names from the workspace catalog. New names join the catalog with an automatic color. |
custom | object | Custom field values by field key |
position | number | Order inside the stage on the board |
stage_entered_at | time | When the lead entered its current stage |
closed_at | time or null | When it was won or lost |
loss_reason | string | Why it was lost |
created_at, updated_at | time |
List leads
/v1/leadsleads:readNewest first. Query parameters (all optional):
| Parameter | Description |
|---|---|
pipeline, stage, contact, company | Only leads with this pipeline, stage, contact or company id |
owner | A member id, me or unassigned |
status | open, closed or all (default) |
q | Text search in the name, the contact and the number (1042 finds #1042) |
sort | Leave out for newest first, or position for board order |
limit, cursor | See Pagination |
{
"data": [ { "id": "lead_01j8z7c2d4f6g8h0j2k4m6n8p0", "number": 1042, "name": "Website order #1042", "amount": 150000000 } ],
"next_cursor": "eyJpZCI6…",
"summary": { "count": 318, "sum": 48150000000 }
}summary (count and sum of amount of all matching leads) is on the first page only. For complex filters use the query endpoint.
/v1/leads/boardleads:readThe pipeline board: for each stage, its stage_id, count, sum and first leads. Takes the list filters above.
Create a lead
/v1/leadsleads:write| Field | Description |
|---|---|
name | Optional |
amount, currency | Optional; amount defaults to 0 |
pipeline_id, stage_id | Optional. Without them the lead goes to the first stage of the first pipeline; with only pipeline_id, to that pipeline's first stage. A stage must belong to the given pipeline. |
owner_id | Optional member id. Leads created with an API key have no owner unless you set one. |
contact_id | An existing contact, or |
contact | a new contact to create with the lead: name, phone or phones, email or emails (needs contacts:write too) |
company_id | An existing company |
source, utm, referrer, landing_page, tags, custom, position | Optional |
curl https://api.kweko.uz/v1/leads \
-H "Authorization: Bearer $KWEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Website order #1042", "amount": 150000000, "source": "website",
"utm": {"utm_source": "google"},
"contact": {"name": "Dilnoza Karimova", "phone": "+998 90 123 45 67"}}'Answers 201 with the lead. Errors: validation_failed (for example stage_id: "This stage belongs to another pipeline."), no_pipeline when the workspace has no pipeline. Sends lead.created.
Read a lead
/v1/leads/{id}leads:readA deleted lead answers 410 gone with deleted_at.
Update a lead
/v1/leads/{id}leads:writeSend only the fields to change: name, amount, currency, pipeline_id, stage_id, owner_id, contact_id, company_id, source, utm, tags, custom, position, loss_reason. Send null to clear owner_id, contact_id or company_id.
To move a lead, send its new stage_id (and pipeline_id when it changes pipeline). Moving it to a won or lost stage closes it (closed_at) and sends lead.won or lead.lost; set loss_reason in the same request.
curl -X PATCH https://api.kweko.uz/v1/leads/lead_01j8z7c2d4f6g8h0j2k4m6n8p0 \
-H "Authorization: Bearer $KWEKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage_id": "stage_01j8z5z0a2b4c6d8e0f2g4h6k1", "amount": 175000000}'Delete and restore
/v1/leads/{id}leads:writeMoves the lead to the trash and answers {"ok": true, "id": "lead_…"}.
/v1/leads/{id}/restoreleads:writeLead contacts
A lead has one main contact (contact_id) and can list more people, up to 50.
/v1/leads/{id}/contactsleads:read/v1/leads/{id}/contactsleads:write/v1/leads/{id}/contacts/{contactID}leads:writeLead products
Products on a lead, up to 200 lines. See Products.
/v1/leads/{id}/productsleads:read/v1/leads/{id}/productsleads:write/v1/leads/{id}/products/{itemID}leads:write/v1/leads/{id}/products/{itemID}leads:write