Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

OperationRequired scope
List / retrieve leadsleads.lead.read
Create a leadleads.lead.write

​
Lead statuses

A lead moves through the following statuses:
StatusMeaning
newJust created, not yet actioned.
contactedInitial outreach sent.
qualifyingQualification in progress.
qualifiedLead meets your criteria.
convertedConverted to a deal or contact.
disqualifiedDoes not meet your criteria.
lostPreviously 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

​
limit
integer
default:"25"
Maximum number of results to return.
​
cursor
string
Opaque cursor from the previous response’s nextCursor field. Omit for the first page.
​
status
string
Filter by lead status. One of: new, contacted, qualifying, qualified, converted, disqualified, lost.
​
assignedTo
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"

​
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

​
firstName
string
required
Lead’s first name. Maximum 255 characters.
​
lastName
string
required
Lead’s last name. Maximum 255 characters.
​
source
string
default:"web_form"
Origin of the lead. One of: web_form, referral, agent_chat, inbound_call, mcp, import.
​
channelType
string
Free-text channel descriptor (for example, "instagram" or "trade_show").
​
email
string
Lead’s email address.
​
phone
string
Lead’s phone number. Maximum 50 characters.
​
companyName
string
Name of the lead’s company. Maximum 255 characters.
​
intent
string
Short description of what the lead is interested in.
​
notes
string
Internal notes about the lead.
​
assignedTo
string
UUID of the user to assign this lead to.
​
sourceAttribution
object
Free-form attribution metadata, for example UTM parameters or ad campaign IDs.
​
customFields
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"
    }
  }'

​
Get a lead

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

​
Path parameters

​
id
string
required
UUID of the lead.

​
Response fields

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