Leads API

This guide covers the API endpoints for managing leads in the Revenue Recognition System. Leads represent potential customers who have shown interest in your products or services but haven't yet made a purchase. They are a crucial part of the sales pipeline.

Leads can be converted to customers once they make their first purchase or sign a contract. The API provides a dedicated endpoint for this conversion process.

Schema

Field	Type	Description	Required
id	UUID	Unique identifier (system-generated)	Read-only
organizationId	UUID	Organization this lead belongs to	Read-only
name	String	Name of the lead (company or individual)	Yes
email	String	Email address of the lead	No
phone	String	Phone number of the lead	No
company	String	Company name if lead is associated with a company	No
source	String	Source of the lead (e.g., website, referral)	No
status	String	Status: 'new', 'contacted', 'qualified', 'unqualified', 'converted'	Yes
score	Integer	Lead score indicating quality/likelihood to convert	No
assignedTo	UUID	ID of the user this lead is assigned to	No
lastContactedAt	DateTime	When the lead was last contacted	No
notes	String	Additional notes about the lead	No
customFields	Object	Custom fields for additional lead-specific data	No
isActive	Boolean	Whether the lead is active (default: true)	Yes
createdAt	DateTime	When the record was created	Read-only
updatedAt	DateTime	When the record was last updated	Read-only

Authentication

All lead API endpoints require authentication with a valid JWT token. The token should be included in the Authorization header as a Bearer token. Organization context is automatically determined from the authenticated session.

Endpoints

Create Lead

Create a new lead within your organization.

Name
Endpoint
Type
POST /leads
Description
Name
Content-Type
Type
application/json
Description

Request Body

Name
name
Type
string
Required
Description
Name of the lead (company or individual)
Name
email
Type
string
Description
Email address of the lead
Name
phone
Type
string
Description
Phone number of the lead
Name
company
Type
string
Description
Company name if the lead is associated with a company
Name
source
Type
string
Description
Source of the lead
Name
status
Type
string
Description
Initial status: 'new', 'contacted', 'qualified', or 'unqualified'
Name
score
Type
integer
Description
Initial lead score (0-100)
Name
assignedTo
Type
string (UUID)
Description
ID of the user to assign this lead to
Name
notes
Type
string
Description
Initial notes about the lead
Name
customFields
Type
object
Description
Custom fields for additional lead-specific data

Request

curl -X POST https://api.example.com/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "555-123-4567",
    "company": "Acme Corporation",
    "source": "website",
    "status": "new",
    "score": 75,
    "notes": "Interested in enterprise plan",
    "customFields": {
      "industry": "Technology",
      "companySize": "100-500"
    }
  }'

Response

{
  "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-123-4567",
  "company": "Acme Corporation",
  "source": "website",
  "status": "new",
  "score": 75,
  "assignedTo": null,
  "lastContactedAt": null,
  "notes": "Interested in enterprise plan",
  "customFields": {
    "industry": "Technology",
    "companySize": "100-500"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

List Leads

Retrieve a paginated list of leads in your organization.

Name
Endpoint
Type
GET /leads
Description

Query Parameters

Name
page
Type
number
Description
Page number for pagination
Name
limit
Type
number
Description
Number of items per page
Name
sortField
Type
string
Description
Field to sort by
Name
sortOrder
Type
string
Description
Sort order (asc, desc)

Request

curl -X GET "https://api.example.com/leads?page=1&limit=10" \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
      "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
      "name": "Acme Corporation",
      "email": "contact@acme.com",
      "phone": "555-123-4567",
      "company": "Acme Corporation",
      "source": "website",
      "status": "new",
      "score": 75,
      "assignedTo": null,
      "lastContactedAt": null,
      "notes": "Interested in enterprise plan",
      "customFields": {
        "industry": "Technology",
        "companySize": "100-500"
      },
      "isActive": true,
      "createdAt": "2025-05-11T12:33:59.048Z",
      "updatedAt": "2025-05-11T12:33:59.048Z"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}

Get Lead

Retrieve a specific lead by ID.

Name
Endpoint
Type
GET /leads/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the lead to retrieve

Request

curl -X GET https://api.example.com/leads/d45f8e21-3ab2-4389-9e0d-9c12654b8e7a \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-123-4567",
  "company": "Acme Corporation",
  "source": "website",
  "status": "new",
  "score": 75,
  "assignedTo": null,
  "lastContactedAt": null,
  "notes": "Interested in enterprise plan",
  "customFields": {
    "industry": "Technology",
    "companySize": "100-500"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

Update Lead

Update an existing lead.

Name
Endpoint
Type
PUT /leads/{id}
Description
Name
Content-Type
Type
application/json
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the lead to update

Request Body

All fields from the create endpoint can be updated, plus:

Name
status
Type
string
Description
Status can now also be 'converted'
Name
lastContactedAt
Type
string (DateTime)
Description
When the lead was last contacted
Name
isActive
Type
boolean
Description
Whether the lead is active

Request

curl -X PUT https://api.example.com/leads/d45f8e21-3ab2-4389-9e0d-9c12654b8e7a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "status": "contacted",
    "score": 85,
    "assignedTo": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
    "lastContactedAt": "2025-05-11T14:00:00.000Z",
    "notes": "Had initial call, very interested in enterprise features"
  }'

Response

{
  "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "555-123-4567",
  "company": "Acme Corporation",
  "source": "website",
  "status": "contacted",
  "score": 85,
  "assignedTo": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "lastContactedAt": "2025-05-11T14:00:00.000Z",
  "notes": "Had initial call, very interested in enterprise features",
  "customFields": {
    "industry": "Technology",
    "companySize": "100-500"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T14:45:22.183Z"
}

Delete Lead

Delete a lead.

Name
Endpoint
Type
DELETE /leads/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the lead to delete

Request

curl -X DELETE https://api.example.com/leads/d45f8e21-3ab2-4389-9e0d-9c12654b8e7a \
  -H "Authorization: Bearer your_jwt_token"

Response

204 No Content

Convert Lead to Customer

Convert a qualified lead to a customer. This creates a new customer record and updates the lead status to 'converted'.

Name
Endpoint
Type
POST /leads/{id}/convert-to-customer
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the lead to convert

Request

curl -X POST https://api.example.com/leads/d45f8e21-3ab2-4389-9e0d-9c12654b8e7a/convert-to-customer \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "customerId": "b72e9d34-2b14-4c5a-9fb2-e8a713b42c65",
  "customer": {
    "id": "b72e9d34-2b14-4c5a-9fb2-e8a713b42c65",
    "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "companyName": "Acme Corporation",
    "customerId": "CUST-001",
    "contactEmail": "contact@acme.com",
    "contactPhone": "555-123-4567",
    "status": "active",
    "createdAt": "2025-05-11T15:00:00.000Z",
    "updatedAt": "2025-05-11T15:00:00.000Z"
  }
}

Find Leads by Source

Retrieve all leads from a specific source.

Name
Endpoint
Type
GET /leads/by-source/{source}
Description

Path Parameters

Name
source
Type
string
Required
Description
Lead source to filter by

Request

curl -X GET https://api.example.com/leads/by-source/website \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
      "name": "Acme Corporation",
      "email": "contact@acme.com",
      "source": "website",
      "status": "new",
      "score": 75,
      "createdAt": "2025-05-11T12:33:59.048Z"
    }
  ]
}

Find Leads by Assignee

Retrieve all leads assigned to a specific user.

Name
Endpoint
Type
GET /leads/assigned-to/{assigneeId}
Description

Path Parameters

Name
assigneeId
Type
string (UUID)
Required
Description
ID of the user to filter leads by

Request

curl -X GET https://api.example.com/leads/assigned-to/f47f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
      "name": "Acme Corporation",
      "assignedTo": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
      "status": "contacted",
      "score": 85,
      "lastContactedAt": "2025-05-11T14:00:00.000Z"
    }
  ]
}

Get Lead Scoring Statistics

Retrieve aggregate statistics about lead scores.

Name
Endpoint
Type
GET /leads/stats/scoring
Description

Request

curl -X GET https://api.example.com/leads/stats/scoring \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "averageScore": 68.5,
  "scoreDistribution": {
    "low": 12,
    "medium": 28,
    "high": 15
  },
  "topScorers": [
    {
      "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
      "name": "Acme Corporation",
      "score": 85,
      "status": "contacted"
    }
  ]
}

Error Responses

The API returns standard HTTP status codes and error messages in a consistent format.

{
  "error": "Error description",
  "details": [
    {
      "message": "Specific error detail"
    }
  ]
}

Common errors include:

Status Code	Error	Description
400	Bad Request	Invalid input data or validation error
401	Unauthorized	Missing or invalid authentication token
404	Not Found	Lead with the specified ID not found
409	Conflict	Lead has already been converted
500	Internal Server Error	Server error occurred

Lead Lifecycle

Lead Status Progression

The typical lead status progression is:

new - Initial status when lead is created
contacted - Lead has been contacted by sales
qualified - Lead has been qualified as a potential customer
converted - Lead has been converted to a customer
unqualified - Lead does not meet criteria for conversion

Lead Scoring

Lead scores range from 0 to 100 and indicate the quality and likelihood of conversion:

0-33 (Low): Low quality lead, unlikely to convert
34-66 (Medium): Average quality lead, may convert with nurturing
67-100 (High): High quality lead, likely to convert

Lead Sources

Common lead sources include:

website - Direct from company website
referral - Referred by existing customer
trade_show - Met at trade show or event
cold_call - Outbound sales effort
social_media - Social media channels
content_marketing - Blog, whitepaper, etc.
paid_advertising - PPC, display ads, etc.

Best Practices

Lead Management

Regular Updates: Keep lead status and scores updated as interactions occur
Assignment: Assign leads to sales representatives promptly for follow-up
Notes: Use the notes field to track important interactions and context
Custom Fields: Leverage custom fields to track industry-specific data

Lead Nurturing

Track last contact date to ensure timely follow-ups
Use lead scoring to prioritize high-value leads
Update lead status as they progress through the sales funnel
Convert leads promptly when they're ready to become customers

Code Example

Here's an example of how to use the leads API with JavaScript:

// Create a new lead
async function createLead(leadData) {
  const response = await fetch('https://api.example.com/leads', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getAuthToken()}`
    },
    body: JSON.stringify({
      name: leadData.name,
      email: leadData.email,
      phone: leadData.phone,
      company: leadData.company,
      source: leadData.source || 'website',
      status: 'new',
      score: leadData.score || 50,
      notes: leadData.notes
    })
  });

  if (!response.ok) {
    throw new Error('Failed to create lead');
  }

  return await response.json();
}

// Convert lead to customer
async function convertLeadToCustomer(leadId) {
  const response = await fetch(
    `https://api.example.com/leads/${leadId}/convert-to-customer`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${getAuthToken()}`
      }
    }
  );

  if (!response.ok) {
    throw new Error('Failed to convert lead');
  }

  return await response.json();
}

// Get high-scoring leads
async function getHighScoringLeads() {
  const response = await fetch('https://api.example.com/leads?sortField=score&sortOrder=desc&limit=10', {
    headers: {
      'Authorization': `Bearer ${getAuthToken()}`
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch leads');
  }

  const result = await response.json();
  return result.data.filter(lead => lead.score >= 67);
}