Leads

A lead is a prospective client captured from any source: a web form, an ad, a referral, an imported list, or the push endpoint.

EndpointsCopy Anchor Link

The lead objectCopy Anchor Link

{
  "id": "3f8c1e2a-1b2c-4d5e-8f90-abcdef012345",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+15551234567",
  "source": "web_form",
  "status": { "key": "new", "name": "New" },
  "assignee_id": null,
  "archived": false,
  "created_at": "2026-06-23T10:00:00.000Z",
  "last_activity_at": "2026-06-23T10:00:00.000Z",
  "data": { "city": "London", "qualification": "qualified" }
}

Fields in dataCopy Anchor Link

data holds the lead's contact fields, keyed by each field's key. Your firm defines its fields in Settings → Contact fields (a field's key is made from the name it was first given and never changes). When you create or update a lead, each key is handled one of three ways.

The default keys keep this API version's rules, whatever kind the firm's field now has: caseType, hierarchy, preferredLanguage, countryOfOrigin, city, state, zip, gender, dob, referralSource and message. caseType and hierarchy must be one of the firm's case types or hierarchies (a 422, for example "Invalid case type."); the others are stored as trimmed text. A value that isn't text, or is blank, is ignored. Stricter checks for these keys will come with a new dated API version.

qualification and contactType are lists the app manages. A text value must be one of the firm's qualifications or contact types (a 422: "Invalid qualification." or "Invalid contact type."); a value that isn't text, or is blank, is ignored.

Every other field your firm defines is checked by its kind, with the app's own rules:

• Short text, long text, choice, country, language and US state take text; a date takes text as YYYY-MM-DD; a number takes a number or its digits as text (42 or "42"); yes or no takes true or false, or the text "Yes" or "No"; multiple choice takes an array of option labels (at most 100).
• A choice must be one of the options your firm has defined. A date must be real, from 1900 to 2199. Text is at most 20,000 characters.
• An invalid value is a 422 invalid_request whose message names the key, for example "data.passportNumber must be text." or "data.visaStatus must be one of your firm's visa status options."
• null or a blank value is ignored: the API doesn't clear a field.

The default keys are stored even when your firm has retired their field. Any other key (an unknown key, or a field your firm added and then retired) is ignored and isn't stored.

Reads return everything stored in data, including keys a lead source sent and fields your firm has since retired.