Leads and deals

Create leads, convert them to Active clients, attach notes, and sync the deals pipeline.

Leads are client entities with lead status. The same entityKey is used after you convert them to Active clients. Deals are a separate pipeline object with their own statuses and sources.

Settings first

Route	Use when creating
GET /api/v1/settings/entity-types	entityType / entityTypeID
GET /api/v1/settings/lead-sources	leadSource name
GET /api/v1/settings/lead-statuses	leadStatus name
GET /api/v1/settings/deal-sources	Deal source names
GET /api/v1/settings/deal-statuses	Deal status names

Create a lead

Write access required. POST /api/v1/leads.

Individuals / sole traders: entityName = given name, entitySurname = family name (not auto-split).

Companies: entityName = legal or trading name; leave surname unset.

{
  "entityType": "Individual",
  "entityName": "Alex",
  "entitySurname": "Morgan",
  "email": "[e-mail]",
  "leadSource": "Website enquiry",
  "leadStatus": "New"
}

Convert to client

POST /api/v1/leads/{entityKey}/convert-to-client

Sets client status from Lead to Active. The entityKey does not change. 400 if the entity is already a client.