API reference · CRM

Leads

Create and update studio leads while preserving attribution and deduplicating by normalized email within the studio.

Endpoints4

Primary objectLeadObject

Tenant boundaryCredential studio

GET/leads

List leads

Lists studio leads in stable cursor order.

Required scope: leads:read
Success: 200
Response: Page<LeadObject>

Parameters

cursorquery

uuid

Opaque cursor returned by the previous page. Pass it back unchanged.

limitquery

integer

Number of records to return. Defaults to 50; maximum 200.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/leads" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [{
    "id": "11f9fbae-e7c6-4318-b766-ef41ca2d75a0",
    "object": "lead",
    "email": "randy@example.com",
    "first_name": "Randy",
    "source": "jux_waitlist",
    "status": "new",
    "lifecycle_stage": "lead",
    "metadata": { "campaign": "founding_waitlist" },
    "created_at": "2026-08-02T20:31:12Z"
  }],
  "has_more": false,
  "next_cursor": null
}

POST/leads

Create or identify a lead

Creates a lead or identifies an existing studio lead with the same normalized email.

Required scope: leads:write
Success: 201
Response: MutationResult

Request body

Send a JSON object matching LeadCreate.

application/json

{
  "email": "randy@example.com",
  "first_name": "Randy",
  "source": "jux_waitlist",
  "metadata": { "campaign": "founding_waitlist" },
  "utm_source": "instagram",
  "utm_campaign": "opening_waitlist"
}

Example request

curl -X POST "https://api.getclassflow.com/partner/v1/leads" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "email": "randy@example.com",
  "first_name": "Randy",
  "source": "jux_waitlist",
  "metadata": { "campaign": "founding_waitlist" },
  "utm_source": "instagram",
  "utm_campaign": "opening_waitlist"
}'

Example response

201 · application/json

{
  "id": "11f9fbae-e7c6-4318-b766-ef41ca2d75a0",
  "object": "lead",
  "created": true
}

GET/leads/{lead_id}

Retrieve a lead

Returns one lead from the credential’s studio.

Required scope: leads:read
Success: 200
Response: LeadObject

Parameters

lead_idpathrequired

uuid

The stable ClassFlow identifier for the lead.

Example request

curl -X GET "https://api.getclassflow.com/partner/v1/leads/YOUR_LEAD_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY"

Example response

200 · application/json

{
  "id": "11f9fbae-e7c6-4318-b766-ef41ca2d75a0",
  "object": "lead",
  "email": "randy@example.com",
  "first_name": "Randy",
  "source": "jux_waitlist",
  "status": "new",
  "lifecycle_stage": "lead",
  "metadata": { "campaign": "founding_waitlist" },
  "created_at": "2026-08-02T20:31:12Z"
}

PATCH/leads/{lead_id}

Update a lead

Updates supported contact, status, notes, or metadata fields for one studio lead.

Required scope: leads:write
Success: 200
Response: MutationResult

Parameters

lead_idpathrequired

uuid

The stable ClassFlow identifier for the lead.

Request body

Send a JSON object matching LeadUpdate.

application/json

{
  "status": "qualified",
  "phone": "+13035550199",
  "metadata": { "child_care_interest": "yes" }
}

Example request

curl -X PATCH "https://api.getclassflow.com/partner/v1/leads/YOUR_LEAD_ID" \
  -H "X-ClassFlow-Key: $CLASSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "status": "qualified",
  "phone": "+13035550199",
  "metadata": { "child_care_interest": "yes" }
}'

Example response

200 · application/json

{
  "id": "11f9fbae-e7c6-4318-b766-ef41ca2d75a0",
  "object": "lead",
  "created": true
}

Object schema

LeadObject

Full OpenAPI schema

iduuid

Stable lead identifier.

emailemail

Normalized studio-local lead email.

sourcestring | null

Lead source, such as partner_api or waitlist.

lifecycle_stagestring | null

Current CRM lifecycle stage.

metadataobject

Studio-owned structured metadata, including optional form context.