Lidveriq

API reference

Version 1. Base address: https://crm.lidveriq.com

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.

StatusMeaning
200Done
400The request is malformed
401The key is missing or wrong
402The company's balance is negative and access is limited
403The company is blocked or not approved yet
404The chat or the object was not found in this workspace
429Too many requests: wait a minute and repeat
502The messenger refused the message (the text of its answer is in error)

Chats

GET/api/v1/chats

The list of chats, newest activity first.

ParameterMeaning
limitHow many to return, 1 to 500. Default 100
offsetHow many to skip, for paging
qSearch by name, username, phone or email
statusChat statuses, comma-separated: auto, manual, waiting, ignore, blocked, stopped, error, finished
stageSale stage ids, comma-separated
tagTag ids, comma-separated
channelThe id of a bot or channel
flow, stepThe id of a funnel or of its step
from, toCreated 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"
    }
  ]
}
GET/api/v1/chats/{id}

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

POST/api/v1/chats/{id}

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.

FieldMeaning
statusThe 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_idThe sale stage, by name or by id
step_id, flow_idMove the client to this step or to the start of this funnel
assign_tags, remove_tagsTag names or ids to add or remove: a list or a comma-separated string
fieldsCustom fields as an object, for example {"city": "Berlin"}
name, phone, emailThe client's contacts
assigneeThe operator in charge: their email, or none to leave the chat without one
event, amountRecord an event, for example registration or deposit with its amount. Deposits add up in the client's card and reach your ad pixels
messageA 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

GET/api/v1/chats/{id}/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"}
  ]
}
POST/api/v1/messages/send

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

GET/api/v1/{kind}

The ids and names you need for the other requests. {kind} is one of:

KindReturns
tagsTags: id, name, color
stagesSale stages: id, name, kind
fieldsCustom fields: key, name, type, options
flowsFunnels: id, name
stepsFunnel 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:

ParameterMeaning
lead_idThe chat's id in Lidveriq
chat_idThe client's id in the messenger
username, phoneThe client's username or phone
click_idThe 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.

Lidveriq · Status · Terms · Privacy