Leads API — Create and Manage Inbound Prospects

Leads represent inbound prospects before they are converted to pipeline deals or contacts. The leads API uses cursor-based pagination for efficient traversal of large lead lists, and supports custom fields defined in your tenant configuration.

Required scopes

Operation	Required scope
List / retrieve leads	`leads.lead.read`
Create a lead	`leads.lead.write`

Lead statuses

A lead moves through the following statuses:

Status	Meaning
`new`	Just created, not yet actioned.
`contacted`	Initial outreach sent.
`qualifying`	Qualification in progress.
`qualified`	Lead meets your criteria.
`converted`	Converted to a deal or contact.
`disqualified`	Does not meet your criteria.
`lost`	Previously engaged, now lost.

Lead sources

When creating a lead, source tells Novala where it originated: web_form · referral · agent_chat · inbound_call · mcp · import

List leads

GET /api/v1/leads Returns a cursor-paginated list of leads for the authenticated tenant.

Query parameters

integer

default:"25"

Maximum number of results to return.

string

Opaque cursor from the previous response’s nextCursor field. Omit for the first page.

string

Filter by lead status. One of: new, contacted, qualifying, qualified, converted, disqualified, lost.

string

Filter by the UUID of the assigned user.

Response

{
  "data": [
    {
      "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "firstName": "Alex",
      "lastName": "Rivera",
      "email": "alex@example.com",
      "phone": "+15550009876",
      "companyName": "Acme Corp",
      "status": "new",
      "source": "web_form",
      "intent": "Interested in enterprise plan",
      "notes": null,
      "assignedTo": null,
      "customFields": {},
      "createdAt": "2024-06-01T14:22:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6Ii4uLi4iLCJjcmVhdGVkQXQiOiIuLi4ifQ==",
  "hasMore": true
}

curl -X GET "https://app.novala.ai/api/v1/leads?status=new&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/v1/leads?status=new&limit=50',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data, nextCursor, hasMore } = await response.json();

Paginating through all leads

TypeScript

async function* allLeads(apiKey: string, status?: string) {
  let cursor: string | undefined;
  do {
    const params = new URLSearchParams({ limit: '100' });
    if (status) params.set('status', status);
    if (cursor) params.set('cursor', cursor);

    const res = await fetch(`https://app.novala.ai/api/v1/leads?${params}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const { data, nextCursor, hasMore } = await res.json();
    yield* data;
    cursor = hasMore ? nextCursor : undefined;
  } while (cursor);
}

Create a lead

POST /api/v1/leads Creates a new lead. Use this to capture leads from external web forms, CRM integrations, or any channel that produces inbound interest.

Request body

string

required

Lead’s first name. Maximum 255 characters.

string

required

Lead’s last name. Maximum 255 characters.

string

default:"web_form"

Origin of the lead. One of: web_form, referral, agent_chat, inbound_call, mcp, import.

string

Free-text channel descriptor (for example, "instagram" or "trade_show").

string

Lead’s email address.

string

Lead’s phone number. Maximum 50 characters.

string

Name of the lead’s company. Maximum 255 characters.

string

Short description of what the lead is interested in.

string

Internal notes about the lead.

string

UUID of the user to assign this lead to.

object

Free-form attribution metadata, for example UTM parameters or ad campaign IDs.

object

Custom field key-value map. Any required custom fields your tenant has configured must be included.

Response

Returns 201 Created with { "data": { lead object } }.

Example: capturing a web form submission

curl -X POST https://app.novala.ai/api/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Rivera",
    "email": "alex@example.com",
    "phone": "+15550009876",
    "companyName": "Acme Corp",
    "source": "web_form",
    "intent": "Interested in enterprise plan",
    "sourceAttribution": {
      "utm_source": "google",
      "utm_campaign": "spring-launch"
    }
  }'

// Typical Next.js API route handling a form POST
export async function POST(request: Request) {
  const body = await request.json();

  const response = await fetch('https://app.novala.ai/api/v1/leads', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NOVALA_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      firstName: body.firstName,
      lastName: body.lastName,
      email: body.email,
      phone: body.phone,
      source: 'web_form',
      sourceAttribution: { page: body.page, referrer: body.referrer },
    }),
  });

  const { data } = await response.json();
  return Response.json({ leadId: data.id });
}

Get a lead

GET /api/v1/leads/{id} Retrieves a single lead by ID.

Path parameters

string

required

UUID of the lead.

Response fields

object

Show Lead object

string

UUID of the lead.

string

First name.

string

Last name.

string | null

Email address.

string | null

Phone number.

string | null

Company name as entered.

string

Current lead status.

string

Lead source channel.

string | null

Additional channel descriptor.

string | null

Stated interest or intent.

string | null

Internal notes.

string | null

UUID of the assigned user, or null.

object | null

Attribution metadata.

object

Custom field key-value pairs.

string

ISO 8601 creation timestamp.

curl -X GET https://app.novala.ai/api/v1/leads/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/v1/leads/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data } = await response.json();

Overview

Endpoints

Leads API — Create and Manage Inbound Prospects

Required scopes

Lead statuses

Lead sources

List leads

Query parameters

Response

Paginating through all leads

Create a lead

Request body

Response

Example: capturing a web form submission

Get a lead

Path parameters

Response fields

​Required scopes

​Lead statuses

​Lead sources

​List leads

​Query parameters

​Response

​Paginating through all leads

​Create a lead

​Request body

​Response

​Example: capturing a web form submission

​Get a lead

​Path parameters

​Response fields

Required scopes

Lead statuses

Lead sources

List leads

Query parameters

Response

Paginating through all leads

Create a lead

Request body

Response

Example: capturing a web form submission

Get a lead

Path parameters

Response fields