API reference
Getting started
The API works with one workspace (project) at a time. A chat is one client in one of your bots or channels: the conversation, the client's card, the funnel step, tags and custom fields.
With the API you can list chats and read conversations, change a client's stage, tags and fields, record events such as a registration or a deposit, and send a message as the bot.
Authentication
Create a key in the workspace: Settings → Webhooks and API. Only the owner and administrators of the company can do it. The key is shown once, so save it right away. A key gives access to one workspace only.
Send the key with every request in the Authorization header:
curl https://crm.lidveriq.com/api/v1/chats \
-H "Authorization: Bearer lvq_your_key"
The header X-API-Key: lvq_your_key works too. Keep the key on your server: never put it into a web page or a mobile app. A key you no longer need is deleted in the same settings section and stops working at once.
Limits and errors
Up to 600 requests per minute per workspace. Answers are JSON. A failed request has an error field with the reason.
| Status | Meaning |
|---|---|
200 | Done |
400 | The request is malformed |
401 | The key is missing or wrong |
402 | The company's balance is negative and access is limited |
403 | The company is blocked or not approved yet |
404 | The chat or the object was not found in this workspace |
429 | Too many requests: wait a minute and repeat |
502 | The messenger refused the message (the text of its answer is in error) |
Chats
The list of chats, newest activity first.
| Parameter | Meaning |
|---|---|
limit | How many to return, 1 to 500. Default 100 |
offset | How many to skip, for paging |
q | Search by name, username, phone or email |
status | Chat statuses, comma-separated: auto, manual, waiting, ignore, blocked, stopped, error, finished |
stage | Sale stage ids, comma-separated |
tag | Tag ids, comma-separated |
channel | The id of a bot or channel |
flow, step | The id of a funnel or of its step |
from, to | Created between these dates, YYYY-MM-DD |
{
"items": [
{
"id": "0b7c1f0e-5a43-4d0f-9c1b-2f6a4f1f2a10",
"external_id": "512345678",
"username": "anna_k",
"name": "Anna K.",
"phone": "",
"email": "",
"status": "auto",
"sale_stage_id": "6f0d…",
"flow_id": "a41c…",
"step_id": "c9e2…",
"assignee_id": null,
"tags": ["3d1e…"],
"fields": {"city": "Berlin"},
"total_deposit": 150,
"source": {"campaign": "Spring promo", "utm_source": "fb"},
"created_at": "2026-11-02T09:14:31Z",
"last_message_at": "2026-11-12T17:40:02Z"
}
]
}
One chat. {id} is the chat's id in Lidveriq or the client's id in the messenger (for Telegram, the numeric user id). The answer has the same fields as a list item plus notes, fd_amount and rd_count.
Update a chat
Changes the client's card and position in the funnel. PATCH works the same way. Send JSON or a form; only the fields you send are changed.
| Field | Meaning |
|---|---|
status | The chat status, for example manual to hand the chat to an operator or auto to return it to the bot. With auto the step the client stands on runs right away: the client gets its messages, an AI step replies |
stage or stage_id | The sale stage, by name or by id |
step_id, flow_id | Move the client to this step or to the start of this funnel |
assign_tags, remove_tags | Tag names or ids to add or remove: a list or a comma-separated string |
fields | Custom fields as an object, for example {"city": "Berlin"} |
name, phone, email | The client's contacts |
assignee | The operator in charge: their email, or none to leave the chat without one |
event, amount | Record an event, for example registration or deposit with its amount. Deposits add up in the client's card and reach your ad pixels |
message | A text to send to the client as the bot |
curl -X POST https://crm.lidveriq.com/api/v1/chats/512345678 \
-H "Authorization: Bearer lvq_your_key" \
-H "Content-Type: application/json" \
-d '{"stage": "Paid", "assign_tags": ["vip"], "event": "deposit", "amount": 150}'
{"ok": true, "applied": ["+tag:vip", "stage", "event:deposit"]}
Messages
The last 500 messages of the chat, newest first. direction is in for the client's messages, out for yours and internal for notes of the team. sender tells who wrote: lead, bot, ai or operator.
{
"items": [
{"id": 90412, "direction": "out", "sender": "ai", "kind": "text", "text": "Hello! How can I help?", "file_id": null, "status": "sent", "created_at": "2026-11-12T17:40:02Z"},
{"id": 90411, "direction": "in", "sender": "lead", "kind": "text", "text": "Hi", "file_id": null, "status": "sent", "created_at": "2026-11-12T17:39:55Z"}
]
}
Sends a text to the client as the bot. Give lead_id (the chat's id in Lidveriq) or chat_id (the client's id in the messenger). Variables such as {{name}} are filled in the same way as in funnels.
curl -X POST https://crm.lidveriq.com/api/v1/messages/send \
-H "Authorization: Bearer lvq_your_key" \
-H "Content-Type: application/json" \
-d '{"chat_id": "512345678", "text": "Your order is on its way, {{name}}!"}'
{"ok": true, "message_id": 90413}
A message can be sent only to a client who has already written to your bot. This is a rule of the messengers, not of the API.
Catalogs
The ids and names you need for the other requests. {kind} is one of:
| Kind | Returns |
|---|---|
tags | Tags: id, name, color |
stages | Sale stages: id, name, kind |
fields | Custom fields: key, name, type, options |
flows | Funnels: id, name |
steps | Funnel steps: id, title, type, flow |
Incoming webhooks
When another system cannot send headers (a tracker's postback, a payment page, a form), use an incoming webhook instead of a key. Create one in Settings → Webhooks and API: you get an address of the form https://crm.lidveriq.com/hook/{id}. Anyone who knows the address can call it, so treat it as a secret.
The webhook accepts GET and POST with the same fields as Update a chat, in the query string, a form or JSON. The client is found by one of:
| Parameter | Meaning |
|---|---|
lead_id | The chat's id in Lidveriq |
chat_id | The client's id in the messenger |
username, phone | The client's username or phone |
click_id | The click id from a Lidveriq tracker link (also subid, clickid, cid) |
https://crm.lidveriq.com/hook/7b0e…?click_id={subid}&event=deposit&amount={payout}
The answer tells whether the client was found and what was changed. The latest calls are listed on the Logs page of the workspace.