Prospects API

This guide covers the API endpoints for managing prospects in the Revenue Recognition System. Prospects represent potential customers who have been identified but haven't yet been qualified. They typically require research and evaluation before becoming qualified leads.

Prospects can be converted to either leads (for further qualification) or directly to customers if they meet the criteria. The API provides dedicated endpoints for both conversion paths.

Schema

Field	Type	Description	Required
id	UUID	Unique identifier (system-generated)	Read-only
organizationId	UUID	Organization this prospect belongs to	Read-only
name	String	Name of the prospect (company or individual)	Yes
email	String	Email address of the prospect	No
phone	String	Phone number of the prospect	No
company	String	Company name if prospect is associated with one	No
industry	String	Industry of the prospect	No
estimatedRevenue	Number	Estimated annual revenue of the prospect	No
employeeCount	Integer	Number of employees at the prospect's company	No
status	String	Status: 'researching', 'contacted', 'evaluating', 'qualified', 'unqualified', 'converted'	Yes
assignedTo	UUID	ID of the user this prospect is assigned to	No
lastContactedAt	DateTime	When the prospect was last contacted	No
notes	String	Additional notes about the prospect	No
customFields	Object	Custom fields for additional prospect-specific data	No
isActive	Boolean	Whether the prospect 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 prospect 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 Prospect

Create a new prospect within your organization.

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

Request Body

Name
name
Type
string
Required
Description
Name of the prospect (company or individual)
Name
email
Type
string
Description
Email address of the prospect
Name
phone
Type
string
Description
Phone number of the prospect
Name
company
Type
string
Description
Company name if the prospect is associated with a company
Name
industry
Type
string
Description
Industry of the prospect
Name
estimatedRevenue
Type
number
Description
Estimated annual revenue
Name
employeeCount
Type
integer
Description
Number of employees
Name
status
Type
string
Description
Initial status: 'researching', 'contacted', or 'evaluating'
Name
assignedTo
Type
string (UUID)
Description
ID of the user to assign this prospect to
Name
notes
Type
string
Description
Initial notes about the prospect
Name
customFields
Type
object
Description
Custom fields for additional prospect-specific data

Request

curl -X POST https://api.example.com/prospects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "name": "TechCorp Industries",
    "email": "info@techcorp.com",
    "phone": "555-987-6543",
    "company": "TechCorp Industries",
    "industry": "Technology",
    "estimatedRevenue": 5000000,
    "employeeCount": 250,
    "status": "researching",
    "notes": "Large tech company, potential for enterprise solution",
    "customFields": {
      "region": "North America",
      "productInterest": "Enterprise Suite"
    }
  }'

Response

{
  "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "TechCorp Industries",
  "email": "info@techcorp.com",
  "phone": "555-987-6543",
  "company": "TechCorp Industries",
  "industry": "Technology",
  "estimatedRevenue": 5000000,
  "employeeCount": 250,
  "status": "researching",
  "assignedTo": null,
  "lastContactedAt": null,
  "notes": "Large tech company, potential for enterprise solution",
  "customFields": {
    "region": "North America",
    "productInterest": "Enterprise Suite"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

List Prospects

Retrieve a paginated list of prospects in your organization.

Name
Endpoint
Type
GET /prospects
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/prospects?page=1&limit=10" \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
      "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
      "name": "TechCorp Industries",
      "email": "info@techcorp.com",
      "phone": "555-987-6543",
      "company": "TechCorp Industries",
      "industry": "Technology",
      "estimatedRevenue": 5000000,
      "employeeCount": 250,
      "status": "researching",
      "assignedTo": null,
      "lastContactedAt": null,
      "notes": "Large tech company, potential for enterprise solution",
      "customFields": {
        "region": "North America",
        "productInterest": "Enterprise Suite"
      },
      "isActive": true,
      "createdAt": "2025-05-11T12:33:59.048Z",
      "updatedAt": "2025-05-11T12:33:59.048Z"
    }
  ],
  "total": 32,
  "page": 1,
  "limit": 10,
  "totalPages": 4
}

Get Prospect

Retrieve a specific prospect by ID.

Name
Endpoint
Type
GET /prospects/{id}
Description

Path Parameters

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

Request

curl -X GET https://api.example.com/prospects/a23c7de4-9821-4f56-9ab3-0c245b88e129 \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "TechCorp Industries",
  "email": "info@techcorp.com",
  "phone": "555-987-6543",
  "company": "TechCorp Industries",
  "industry": "Technology",
  "estimatedRevenue": 5000000,
  "employeeCount": 250,
  "status": "researching",
  "assignedTo": null,
  "lastContactedAt": null,
  "notes": "Large tech company, potential for enterprise solution",
  "customFields": {
    "region": "North America",
    "productInterest": "Enterprise Suite"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T12:33:59.048Z"
}

Update Prospect

Update an existing prospect.

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

Path Parameters

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

Request Body

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

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

Request

curl -X PUT https://api.example.com/prospects/a23c7de4-9821-4f56-9ab3-0c245b88e129 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "status": "evaluating",
    "assignedTo": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
    "lastContactedAt": "2025-05-11T14:00:00.000Z",
    "notes": "Had discovery call, they have budget and timeline for Q3"
  }'

Response

{
  "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
  "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
  "name": "TechCorp Industries",
  "email": "info@techcorp.com",
  "phone": "555-987-6543",
  "company": "TechCorp Industries",
  "industry": "Technology",
  "estimatedRevenue": 5000000,
  "employeeCount": 250,
  "status": "evaluating",
  "assignedTo": "f47f0ea2-77bd-4578-8c76-0116d473cc27",
  "lastContactedAt": "2025-05-11T14:00:00.000Z",
  "notes": "Had discovery call, they have budget and timeline for Q3",
  "customFields": {
    "region": "North America",
    "productInterest": "Enterprise Suite"
  },
  "isActive": true,
  "createdAt": "2025-05-11T12:33:59.048Z",
  "updatedAt": "2025-05-11T14:45:22.183Z"
}

Delete Prospect

Delete a prospect.

Name
Endpoint
Type
DELETE /prospects/{id}
Description

Path Parameters

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

Request

curl -X DELETE https://api.example.com/prospects/a23c7de4-9821-4f56-9ab3-0c245b88e129 \
  -H "Authorization: Bearer your_jwt_token"

Response

204 No Content

Convert Prospect to Lead

Convert a prospect to a lead for further qualification.

Name
Endpoint
Type
POST /prospects/{id}/convert-to-lead
Description

Path Parameters

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

Request

curl -X POST https://api.example.com/prospects/a23c7de4-9821-4f56-9ab3-0c245b88e129/convert-to-lead \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "leadId": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
  "lead": {
    "id": "d45f8e21-3ab2-4389-9e0d-9c12654b8e7a",
    "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "name": "TechCorp Industries",
    "email": "info@techcorp.com",
    "phone": "555-987-6543",
    "company": "TechCorp Industries",
    "source": "prospect",
    "status": "new",
    "score": 60,
    "createdAt": "2025-05-11T15:00:00.000Z",
    "updatedAt": "2025-05-11T15:00:00.000Z"
  }
}

Convert Prospect to Customer

Convert a qualified prospect directly to a customer.

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

Path Parameters

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

Request

curl -X POST https://api.example.com/prospects/a23c7de4-9821-4f56-9ab3-0c245b88e129/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": "TechCorp Industries",
    "customerId": "CUST-002",
    "contactEmail": "info@techcorp.com",
    "contactPhone": "555-987-6543",
    "status": "active",
    "createdAt": "2025-05-11T15:00:00.000Z",
    "updatedAt": "2025-05-11T15:00:00.000Z"
  }
}

Find Prospects by Industry

Retrieve all prospects in a specific industry.

Name
Endpoint
Type
GET /prospects/by-industry/{industry}
Description

Path Parameters

Name
industry
Type
string
Required
Description
Industry to filter prospects by

Request

curl -X GET https://api.example.com/prospects/by-industry/Technology \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
      "name": "TechCorp Industries",
      "email": "info@techcorp.com",
      "industry": "Technology",
      "estimatedRevenue": 5000000,
      "employeeCount": 250,
      "status": "evaluating"
    }
  ]
}

Find High-Value Prospects

Retrieve prospects with estimated revenue above a specified threshold.

Name
Endpoint
Type
GET /prospects/high-value
Description

Query Parameters

Name
minRevenue
Type
number
Description
Minimum revenue threshold for high-value prospects

Request

curl -X GET "https://api.example.com/prospects/high-value?minRevenue=2000000" \
  -H "Authorization: Bearer your_jwt_token"

Response

{
  "data": [
    {
      "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
      "name": "TechCorp Industries",
      "email": "info@techcorp.com",
      "industry": "Technology",
      "estimatedRevenue": 5000000,
      "employeeCount": 250,
      "status": "evaluating"
    }
  ]
}

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	Prospect with the specified ID not found
409	Conflict	Prospect has already been converted
500	Internal Server Error	Server error occurred

Prospect Lifecycle

Prospect Status Progression

The typical prospect status progression is:

researching - Initial research phase, gathering information
contacted - Initial contact has been made
evaluating - Actively evaluating the prospect's potential
qualified - Prospect meets criteria to become a lead/customer
unqualified - Prospect does not meet criteria
converted - Prospect has been converted to lead or customer

Prospect Evaluation Criteria

When evaluating prospects, consider:

Company Size: Employee count and organizational structure
Revenue Potential: Estimated annual revenue and budget
Industry Fit: How well they match your target industries
Geographic Location: Whether they're in your service areas
Business Need: Whether they have a clear need for your solution

Industry Categories

Common industry categories include:

Technology - Software, hardware, IT services
Healthcare - Medical, pharmaceutical, biotech
Financial Services - Banking, insurance, fintech
Manufacturing - Industrial, consumer goods
Retail - E-commerce, brick-and-mortar
Education - Schools, universities, e-learning
Government - Federal, state, local agencies
Non-profit - Charitable organizations

Best Practices

Prospect Research

Data Enrichment: Use the custom fields to store additional research data
Revenue Estimation: Keep estimated revenue updated as you learn more
Industry Classification: Properly categorize prospects for better targeting
Regular Updates: Update status as the evaluation progresses

Conversion Strategy

Qualification Criteria: Define clear criteria for qualifying prospects
Lead vs Customer: Convert to lead if further nurturing needed, to customer if ready to buy
Assignment: Assign prospects to appropriate team members based on expertise
Timeline Tracking: Use lastContactedAt to ensure timely follow-ups

Code Example

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

// Create a new prospect
async function createProspect(prospectData) {
  const response = await fetch('https://api.example.com/prospects', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${getAuthToken()}`
    },
    body: JSON.stringify({
      name: prospectData.name,
      email: prospectData.email,
      company: prospectData.company,
      industry: prospectData.industry,
      estimatedRevenue: prospectData.revenue,
      employeeCount: prospectData.employees,
      status: 'researching',
      notes: prospectData.notes
    })
  });

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

  return await response.json();
}

// Find high-value prospects
async function getHighValueProspects(minRevenue = 1000000) {
  const response = await fetch(
    `https://api.example.com/prospects/high-value?minRevenue=${minRevenue}`,
    {
      headers: {
        'Authorization': `Bearer ${getAuthToken()}`
      }
    }
  );

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

  return await response.json();
}

// Convert prospect based on qualification
async function convertProspect(prospectId, isQualified) {
  const endpoint = isQualified 
    ? `prospects/${prospectId}/convert-to-customer`
    : `prospects/${prospectId}/convert-to-lead`;
    
  const response = await fetch(`https://api.example.com/${endpoint}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${getAuthToken()}`
    }
  });

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

  return await response.json();
}