Skip to main content
A lead is a client entity whose status is Lead. A deal is a separate pipeline record. Deals attach to an Active client or a group. They do not attach to a lead. Convert first, then open the deal.

​
Look up names before you write

Sources and statuses are the practice’s own lists. Send the name, not an id you invented. Cache these. They change rarely. Refresh when a create returns 400 for an unknown source or status.

​
Create a lead

POST /api/v1/leads needs write access. One call creates the entity, the lead fields, and an optional opening note. Individuals and sole traders: entityName is the given name and entitySurname is the family name. Companies: entityName is the full legal or trading name and entitySurname is omitted. If you omit entityType, the default is Individual.
Store entityKey from the 201. externalSystemID is echoed on later lead and entity reads so you can match your CRM row.

​
Keep the pipeline in sync

GET /api/v1/leads/list supports lastUpdated, pageNumber, and substring filters on name, email, leadSource, and leadStatus. Lost leads are excluded unless includeLostLeads=true. Page until a short page, then switch to lastUpdated. GET /api/v1/leads/{entityKey} is one lead. Notes are separate:
  • GET /api/v1/leads/{entityKey}/notes
  • POST /api/v1/leads/{entityKey}/notes with noteText and noteType

​
Convert to an Active client

This sets client status from Lead to Active. entityKey does not change. After conversion the record leaves the lead list and appears on GET /api/v1/entities/list. Connected practice-management sync runs in the background, the same way it does when someone converts a lead in the app. You can now send proposals, create bills, and open deals for this entityKey.

​
Open a deal

POST /api/v1/deals links the deal to one Active client (entityKey) or one group (groupCode), not both, and not a lead.
The 201 returns dealID. That integer is the deal id for get, update, delete, and notes. It is not an entityKey.
  • GET /api/v1/deals/list for incremental sync (lastUpdated, pageNumber). Lost deals are excluded unless includeLostDeals=true. Filter one client with entityKey, or one group with groupCode.
  • GET /api/v1/deals/{dealId} for one deal.
  • PUT /api/v1/deals/{dealId} to change name, status, source, or value. Use names from the settings lists.
  • DELETE /api/v1/deals/{dealId} to remove it.
  • GET and POST /api/v1/deals/{dealId}/notes for the note thread.
Groups, when you attach a deal to a group instead of one client, come from GET /api/v1/groups/list. Use groupCode.

Endpoint reference

Leads, conversion, deal CRUD, and the settings lists those calls depend on.