Docs
Leads

Create a lead

Records a lead against a chatbot, optionally linked to a conversation, and emits the `lead.created` webhook.

POST/api/v1/leads

Deduplicated per conversation: when conversation_id is provided and a lead already exists for it, the existing lead is returned with existing: true rather than a duplicate being created.

Request body

Prop

Type

Response 200

Prop

Type

Errors

  • 400 — Invalid request body
  • 401 — Missing or invalid API key
  • 404 — Chatbot or conversation not found
  • 429 — Rate limit exceeded

Every error shares one envelope.

Example

curl -X POST \
  https://www.hey.support/api/v1/leads \
  -H 'Authorization: Bearer hs_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"chatbot_id":"<chatbot_id>"}'

Add an internal note to a conversation

Inserts a `note` message visible only in the operator dashboard.

List leads

Returns contact details captured by the agent — from the lead form, a human handoff, or a booking — newest first.

On this page

Request body
Response 200
Errors
Example