Leads

All requests use a single endpoint: POST /functions/v1/api with resource: "leads".

Access control

Regular users can only access leads from agents they own. Internal admins can access all leads using adminMode: true and optionally scope to a specific user with userId.

Get lead statistics

Retrieves aggregated statistics about leads, including total count and breakdown by status. Aggregation happens at the database level for optimal performance.

resource

string

required

Must be "leads"

action

string

required

Must be "stats"

data

object

Show properties

filters

object

Show properties

agentId

string

Filter by a specific agent ID.

agentIds

string[]

Filter by multiple agent IDs.

priority

string

Filter by priority (exact match).

searchTerm

string

Search in name, email, and phone fields (partial match).

dateRange

string

Filter by creation date. One of "7d", "30d", "90d", or "all".

adminMode

boolean

Internal admins only. Bypass user scoping to see all leads.

userId

string

Internal admins only. View statistics for a specific user.

Response

success

boolean

data

object

Show properties

stats

object

Show properties

total

number

Total number of leads matching the filters.

by_status

object

Show properties

new

number

contacted

number

qualified

number

converted

number

Leads with a null status or a status outside the four standard values are not counted in any by_status category but are included in total.

const response = await ApiService.invoke<{
  stats: {
    total: number;
    by_status: { new: number; contacted: number; qualified: number; converted: number };
  };
}>({
  resource: "leads",
  action: "stats",
  data: {
    filters: {
      agentIds: ["agent-1", "agent-2"],
      dateRange: "30d",
    },
  },
});

List all leads

Retrieves all leads with full field details and relations.

resource

string

required

Must be "leads"

action

string

required

Must be "all"

data

object

Show properties

filters

object

Show properties

agentId

string

Filter by a specific agent ID.

agentIds

string[]

Filter by multiple agent IDs.

status

string

Filter by status (exact match).

priority

string

Filter by priority (exact match).

searchTerm

string

Search in name, email, and phone fields (partial match).

dateRange

string

Filter by creation date. One of "7d", "30d", "90d", or "all".

limit

number

Number of results to return. Default: 50, max: 500.

offset

number

Pagination offset. Default: 0.

adminMode

boolean

Internal admins only. Bypass user scoping.

userId

string

Internal admins only. View leads for a specific user.

Response

success

boolean

data

object

Show properties

leads

Lead[]

Array of lead objects with all fields. See lead object below.

count

number

Total number of leads matching the filters.

limit

number

offset

number

const response = await ApiService.invoke<{
  leads: Lead[];
  count: number;
  limit: number;
  offset: number;
}>({
  resource: "leads",
  action: "all",
  data: {
    filters: {
      agentId: "agent-123",
      status: "qualified",
      dateRange: "90d",
    },
    limit: 25,
    offset: 0,
  },
});

List leads (summary)

Retrieves leads with basic fields only, optimized for table views. Accepts the same parameters as all.

resource

string

required

Must be "leads"

action

string

required

Must be "list"

data

object

Same parameters as all (filters, pagination, admin options).

Response

Same response structure as all, but each lead contains only summary fields:

data

object

Show properties

leads

object[]

Show Lead summary fields

number

agent_id

string

user_id

string

name

string | null

phone

string | null

status

string | null

priority

string | null

budget

string | null

timeline

string | null

assigned_to

string | null

created_at

string

updated_at

string | null

agent

object

Show properties

string

name

string

user_id

string

count

number

limit

number

offset

number

const response = await ApiService.invoke<{
  leads: Lead[];
  count: number;
}>({
  resource: "leads",
  action: "list",
  data: {
    filters: {
      searchTerm: "john",
      priority: "high",
    },
    limit: 25,
  },
});

Get a lead

Retrieves a specific lead by ID with all fields and relations.

resource

string

required

Must be "leads"

action

string

required

Must be "get"

string | number

required

The lead ID.

Response

success

boolean

data

object

Show properties

lead

Lead

Full lead object. See lead object.

const response = await ApiService.invoke<{ lead: Lead }>({
  resource: "leads",
  action: "get",
  id: 42,
});

Create a lead

Creates a new lead associated with an agent.

resource

string

required

Must be "leads"

action

string

required

Must be "create"

data

object

required

Show properties

agent_id

string

required

The agent this lead belongs to. Validated against agent ownership.

name

string

Lead name.

string

Lead email address.

phone

string

Lead phone number.

status

string

Lead status (e.g. "new", "contacted", "qualified", "converted").

priority

string

Lead priority level.

budget

string

Budget information.

timeline

string

Timeline information.

address

object

Address data as a JSON object.

notes

string

Free-text notes.

assigned_to

string

User ID of the assigned team member.

conversation_id

number

Link to a conversation record.

primary_lead_id

number

Link to a primary lead (for grouping related leads).

is_decision_maker

boolean

Whether this lead is a decision maker.

Whether the lead has given email consent.

Whether the lead has given SMS consent.

preferred_contact_method

string

Preferred method of contact.

preferred_contact_time

string

Preferred time for contact.

metadata

object

Arbitrary metadata as a JSON object.

user_id

string

Override user attribution for this lead.

userId

string

Admin only. Create the lead as if this user created it.

Response (status 201)

success

boolean

data

object

Show properties

lead

Lead

The created lead object.

The user_id on the created lead is resolved in this order: (1) provided user_id parameter, (2) agent’s owning user, (3) current authenticated user.

const response = await ApiService.invoke<{ lead: Lead }>(
  {
    resource: "leads",
    action: "create",
    data: {
      agent_id: "agent-123",
      name: "Jane Doe",
      email: "jane@example.com",
      status: "new",
      priority: "high",
    },
  },
  201
);

Update a lead

Updates an existing lead. This is a partial update — only include the fields you want to change.

resource

string

required

Must be "leads"

action

string

required

Must be "update"

string | number

required

The lead ID.

data

object

required

Any combination of lead fields. All fields except id and created_at can be updated. See the create action for the full list of fields.

Response

success

boolean

data

object

Show properties

lead

Lead

The updated lead object.

const response = await ApiService.invoke<{ lead: Lead }>({
  resource: "leads",
  action: "update",
  id: 42,
  data: {
    status: "qualified",
    priority: "high",
    notes: "Spoke with decision maker, very interested",
  },
});

Delete a lead

Permanently deletes a lead. This is a hard delete with no recovery.

resource

string

required

Must be "leads"

action

string

required

Must be "delete"

string | number

required

The lead ID.

Response

success

boolean

data

object

Show properties

success

boolean

message

string

This permanently deletes the lead. The user must have access to the lead’s agent.

const response = await ApiService.invoke<{
  success: boolean;
  message: string;
}>({
  resource: "leads",
  action: "delete",
  id: 42,
});

Lead object

The full lead object returned by all, get, create, and update actions.

number

agent_id

string

user_id

string

name

string | null

phone

string | null

status

string | null

priority

string | null

budget

string | null

timeline

string | null

address

object | null

notes

string | null

assigned_to

string | null

conversation_id

number | null

primary_lead_id

number | null

is_decision_maker

boolean | null

preferred_contact_method

string | null

preferred_contact_time

string | null

metadata

object | null

created_at

string

updated_at

string | null

agent

object

Show properties

string

name

string

user_id

string

Enum values reference

`status`

Value	Description
`"new"`	Lead has been captured but not yet contacted
`"contacted"`	Initial outreach has been made
`"qualified"`	Lead has been vetted and meets criteria
`"converted"`	Lead has been successfully converted

`priority`

Value	Description
`"low"`	Low urgency
`"medium"`	Standard urgency
`"high"`	Requires immediate attention

`preferred_contact_method`

Value	Description
`"email"`	Contact via email
`"phone"`	Contact via phone call
`"sms"`	Contact via text message

Filtering reference

All list-style actions (stats, all, list) accept a filters object with the following fields:

Filter	Type	Description
`agentId`	`string`	Filter by a single agent
`agentIds`	`string[]`	Filter by multiple agents
`status`	`string`	Exact match on lead status (not available on `stats`)
`priority`	`string`	Exact match on lead priority
`searchTerm`	`string`	Partial match across name, email, and phone
`dateRange`	`string`	One of `"7d"`, `"30d"`, `"90d"`, `"all"`

Admin operations

Admin operations require the internal_admin role. Regular users receive a 403 Forbidden response.

View all leads across all users

const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "all",
  data: {
    adminMode: true,
  },
});

View a specific user’s leads

const response = await ApiService.invoke<{ leads: Lead[]; count: number }>({
  resource: "leads",
  action: "list",
  data: {
    adminMode: true,
    userId: "user-456",
  },
});

Create a lead as another user

const response = await ApiService.invoke<{ lead: Lead }>(
  {
    resource: "leads",
    action: "create",
    data: {
      agent_id: "agent-123",
      name: "Jane Doe",
      email: "jane@example.com",
      userId: "user-456",
    },
  },
  201
);

Error responses

Status	Code	Description
400	`VALIDATION_ERROR`	Missing or invalid required parameters
401	`UNAUTHORIZED`	Invalid or missing authentication token
403	`FORBIDDEN`	User does not have access to the agent
404	`NOT_FOUND`	Lead not found
500	`INTERNAL_ERROR`	Server error

Overview

Agents

Knowledge

Voice

CRM

Marketplace

Platform

Access control

Get lead statistics

Response

List all leads

Response

List leads (summary)

Response

Get a lead

Response

Create a lead

Response (status 201)

Update a lead

Response

Delete a lead

Response

Lead object

Enum values reference

`status`

`priority`

`preferred_contact_method`

Filtering reference

Admin operations

View all leads across all users

View a specific user’s leads

Create a lead as another user

Error responses

Overview

Agents

Knowledge

Voice

CRM

Marketplace

Platform

​Access control

​Get lead statistics

​Response

​List all leads

​Response

​List leads (summary)

​Response

​Get a lead

​Response

​Create a lead

​Response (status 201)

​Update a lead

​Response

​Delete a lead

​Response

​Lead object

​Enum values reference

​status

​priority

​preferred_contact_method

​Filtering reference

​Admin operations

​View all leads across all users

​View a specific user’s leads

​Create a lead as another user

​Error responses

Access control

Get lead statistics

Response

List all leads

Response

List leads (summary)

Response

Get a lead

Response

Create a lead

Response (status 201)

Update a lead

Response

Delete a lead

Response

Lead object

Enum values reference

`status`

`priority`

`preferred_contact_method`

Filtering reference

Admin operations

View all leads across all users

View a specific user’s leads

Create a lead as another user

Error responses