Create a lead

POST https://api.vflo.app/api/public/lead/create If the workspace already has an open lead with the same email, that lead is updated instead of duplicated (see Updating an existing lead). Retrying the same call is therefore safe.

Field	Required	Description
`firstName`	Yes	Lead first name.
`email`	Yes	Lead email address.
`lastName`, `countryOfResidence`	No	Optional lead details.
`phone`	No	E.164 format, for example `+16135550100`. A number in another format is dropped; the lead is still created.
`address`	No	Free-text postal address, up to 500 characters. Saved to the lead’s contact; an address already on file for the same email is kept, and the submitted one is recorded in the lead’s creation note.
`customFields`	No	Up to 50 extra key/value pairs, such as a booking’s duration and fee. Keys start with a letter and use letters, digits or underscores. Values are strings (up to 2000 characters), numbers or booleans, 50KB in total. `consultationBooking` and `calendly` are reserved. They are stored on the lead, listed in its creation note, and echoed back in `data.customFields`.
`stage`	No	Pipeline stage, by stage id or label (for example `"Consultation Booked"`). Unknown values return `400`. Defaults to New. Moving into Closed-Won stamps `wonDate`.
`source`	No	Lead source, by id or label. An unknown label creates that source. Defaults to `api`.
`caseType`	No	Case type, by id or label. Unknown values return `400`.
`primaryInterest`, `languagePreference`	No	Free text, up to 200 characters.
`quotedProfessionalFee`	No	Quoted fee, a number or numeric string such as `"$1,500"`, from 0 to 1,000,000,000.
`consultationTime`	No	`YYYY-MM-DD` or `YYYY-MM-DD HH:mm` (24-hour, firm local time).
`estimatedCloseDate`, `wonDate`	No	`YYYY-MM-DD`.
`assigneeIds`	No	Up to 20 user ids of team members in this workspace. Anyone else returns `400`.

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "address": "123 Main St, Ottawa, ON K1A 0A1",
  "stage": "Consultation Booked",
  "source": "SavvyCal",
  "quotedProfessionalFee": 150,
  "consultationTime": "2026-10-01 14:30",
  "customFields": { "consultationDuration": "60 minutes" }
}

An invalid value in any field returns 400 with a message naming the field, and nothing is written. Returns 201 with data.id for a new lead. Its Inbounded and Last activity are both set to the time of the call. Store the ID to create tasks or notes for this lead.

Updating an existing lead

When the email matches an open lead in the workspace, the call updates that lead and returns 200 with data.id, data.updated: true and data.updatedFields. Leads converted to a client and leads in Closed-Won or Closed-Lost are not matched, so a new booking from them creates a new lead. With several open leads, the most recently active one is updated. Clients are never matched.

Stage, case type, primary interest, fee, consultation time and dates are replaced with the values you send. Resending a stage also re-applies its status and, for Closed-Won, the won date.
Source, assignees and country of residence only fill blanks, so first-touch attribution and staff assignments are kept. An empty assigneeIds list counts as not sent.
Name, phone, address and preferred language only fill blanks on the lead’s contact.
customFields are merged into the lead’s existing ones.
Last activity moves to now. Inbounded (the lead’s creation time) is unchanged.
A note on the lead lists what was updated, including the address and custom values you sent.

Stage, source and case-type labels are matched as labels even when they contain / (for example "Spousal/Common-law"). “Closed Won” matches the Closed-Won stage. Labels are limited to 100 characters.

Start here

Leads

Clients

Cases

Files and forms

Tasks

Notes

Workflows

Updating an existing lead

​Updating an existing lead

Updating an existing lead