Leads API

All endpoints require a valid Bearer token. See Authentication.

Lead schema

Field	Type	Description
`id`	UUID	Unique lead identifier
`name`	string	Customer name
`phone`	string	Phone number
`email`	string	Email address
`company`	string	Company name (optional)
`channel`	string	Source channel: `whatsapp`, `telegram`, `web`, `email`, `voice`
`channel_id`	string	Channel-specific identifier (phone number, telegram user ID, etc.)
`status`	string	Lead status (see below)
`preferred_services`	string[]	Services the customer is interested in
`appointment_notes`	string	Notes about the appointment request
`metadata`	object	Additional data (notes, tags, custom fields)
`created_at`	datetime	When the lead was created
`updated_at`	datetime	When the lead was last updated

Lead statuses

Status	Meaning
`new`	Just captured, not yet contacted
`contacted`	Agent has collected some contact info
`booking_offered`	Available slots have been presented
`booked`	Appointment confirmed
`confirmed`	Booking double-confirmed
`completed`	Appointment took place
`no_show`	Customer didn't show up
`cancelled`	Appointment cancelled
`lost`	Lead is no longer active

List leads

GET /api/v1/leads

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`size`	integer	20	Results per page (max: 100)
`status`	string	—	Filter by status
`channel`	string	—	Filter by channel
`search`	string	—	Search by name, email, company, or phone

Response:

{
  "leads": [
    {
      "id": "550e8400-...",
      "name": "Jane Smith",
      "phone": "+49123456789",
      "email": "jane@example.com",
      "company": null,
      "channel": "whatsapp",
      "status": "booked",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 20
}

Get a lead

GET /api/v1/leads/{lead_id}

Returns the full lead record including all fields, metadata, and timestamps.

Create a lead

POST /api/v1/leads
Content-Type: application/json

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+49123456789",
  "channel": "web",
  "channel_id": "manual-abc123"
}

Response (201 Created): Full lead object.

Use this to manually create leads for phone or walk-in inquiries.

Update a lead

PATCH /api/v1/leads/{lead_id}
Content-Type: application/json

{
  "status": "contacted",
  "name": "Jane Smith-Updated",
  "appointment_notes": "Interested in premium package"
}

All fields are optional — only include the fields you want to change.

Updatable field	Type
`name`	string
`phone`	string
`email`	string
`company`	string
`status`	string
`preferred_services`	string[]
`appointment_notes`	string
`metadata`	object

Delete a lead

DELETE /api/v1/leads/{lead_id}

Soft-deletes the lead by setting its status to lost. Returns 204 No Content.

Add a note

POST /api/v1/leads/{lead_id}/notes
Content-Type: application/json

{
  "content": "Called back, interested in the premium package"
}

Response (201 Created):

{
  "notes": [
    {
      "content": "Called back, interested in the premium package",
      "author": "you@example.com",
      "created_at": "2026-03-07T14:30:00Z"
    }
  ]
}

Notes are stored in the lead's metadata and attributed to the authenticated user.

Leads API

On this page