---
kind: rest
area: leads-customer-centre
tier: free
summary: The route the lead form in the chat posts to, and the routes of the Leads page.
---

# Leads REST routes

The routes live under `/wp-json/kimaai/v1/`. A call from a logged-in browser sends the WordPress REST nonce, as every WordPress REST call does; a script uses an application password. A route that names a feature is registered only while that feature is not hidden (`app/Features/Features.php`).

Each route says its access. Internal: the route serves KimaAI's own admin screens or chat widget and may change or go away in any release without notice, so code outside KimaAI should not call it. Public: the route keeps its path, its arguments and its answer across releases, and changes only after a deprecation.

## POST /kimaai/v1/chatbot/lead

- Access: internal
- Permission: anyone; the visitor's conversation must have started, and one that belongs to another logged-in user is refused (403)
- Tier: free
- Feature: lead-capture

Stores the contact details the visitor left in the lead form of the chat, records that the visitor declined (`dismiss`), or reports a meeting booked in the calendar (`meeting_booked`). Five leads per IP address and day; the consent text must be the one the visitor saw; the `kimaai_lead_validate` filter can refuse a lead.

| Argument         | Type    | Required | Description                                                      |
| ---------------- | ------- | -------- | ---------------------------------------------------------------- |
| `action`         | string  | no       | `submit`, `dismiss` or `meeting_booked`. Default `submit`.       |
| `email`          | string  | no       | The visitor's email address.                                     |
| `name`           | string  | no       | The visitor's name.                                              |
| `phone`          | string  | no       | The visitor's phone number.                                      |
| `company`        | string  | no       | The visitor's company.                                           |
| `consent`        | boolean | no       | True when the visitor agreed to the processing of their details. |
| `marketing`      | boolean | no       | True when the visitor agreed to marketing.                       |
| `consentVersion` | string  | no       | The version of the consent text the form showed.                 |
| `trigger`        | string  | no       | What opened the form.                                            |
| `postId`         | integer | no       | The post the chat ran on. Default `0`.                           |
| `website`        | string  | no       | A hidden field that only bots fill in; a filled one is ignored.  |

Returns: `ok`; or an `error` with 400 (address, consent, refused), 403, 404 (no lead form, no conversation), 429 or 500.

## GET /kimaai/v1/leads

- Access: internal
- Permission: a user with the leads capability, `manage_options` unless the `kimaai_leads_capability` filter changes it
- Tier: free
- Feature: lead-capture

One page of leads for the Leads page, newest first, with their delivery state per destination.

| Argument   | Type    | Required | Description                                                                           |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `page`     | integer | no       | The page, from 1. Default 1.                                                          |
| `per_page` | integer | no       | Leads per page, 1 to 100. Default 25.                                                 |
| `search`   | string  | no       | Text to search for in the leads.                                                      |
| `status`   | string  | no       | `new`, `dismissed`, `erased` or `all`. Default `new`.                                 |
| `from`     | string  | no       | First day, `YYYY-MM-DD`.                                                              |
| `to`       | string  | no       | Last day, `YYYY-MM-DD`.                                                               |
| `failed`   | string  | no       | Only leads whose last delivery to this destination failed; `any` for any destination. |

Returns: `items` and `total`.

## DELETE /kimaai/v1/leads/{id}

- Access: internal
- Permission: a user with the leads capability, `manage_options` unless the `kimaai_leads_capability` filter changes it
- Tier: free
- Feature: lead-capture

Deletes a lead with its delivery state and fires `kimaai_lead_erased`, unless the lead was erased before.

| Argument | Type    | Required | Description |
| -------- | ------- | -------- | ----------- |
| `id`     | integer | yes      | The lead.   |

Returns: `ok`; 404 for an unknown lead.

## GET /kimaai/v1/leads/{id}/conversation

- Access: internal
- Permission: a user with the leads capability, `manage_options` unless the `kimaai_leads_capability` filter changes it
- Tier: free
- Feature: lead-capture

The conversation the lead came from, so a user who may see leads but not the chat history can read it.

| Argument | Type    | Required | Description |
| -------- | ------- | -------- | ----------- |
| `id`     | integer | yes      | The lead.   |

Returns: The conversation's messages; 404 for an unknown lead.
