Create lead

post

https://app.usesocket.com/api/v1/leads

Create a new lead. Requires the leads:write scope.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

stage_id

uuid | null

The pipeline stage to create the lead in - one of the stages with isOpen: true from GET /api/v1/lead-stages. Takes precedence over the deprecated lane field when both are sent; an id that does not resolve to an open stage owned by the practice falls back to the first open stage.

lane

string

enum

Defaults to enquiry

deprecated

Deprecated - use stage_id instead. Maps to the practice's matching pipeline stage; when that stage has been removed the lead lands in the first stage of the pipeline

Allowed:

title

string

length ≤ 255

A descriptive title for this lead

temperature

string

enum

Defaults to warm

How likely this lead is to convert

Allowed:

source

string

Where this lead came from. Omit it and the practice's configured default source is applied; there is no fixed default value, because each firm chooses its own.

source_note

string | null

Detail about the source. Some sources are configured to require it - the 422 names the source and says, in the firm's own words, what it expects here.

deal_size

string

enum

Expected size of this deal

Allowed:

deal_value

float

≥ 0

Expected monetary value of this deal

client

object

required

contact

object

required

owner_id

uuid

ID of the team member who owns this lead

note

object

An optional opening note to record against the new lead - somewhere for a long free-text answer from your intake form to land.

Responses

201Lead created successfully

400Bad Request

401Unauthorized

403Forbidden

422Validation Error