Skip to main content
GET
https://YOUR_DEPLOYMENT.lupitor.com/api/v1
/
api
/
v1
/
leads
curl "https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "leads": [
      {
        "_id": "jh7abc123xyz",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "phoneNumber": "+15555551234",
        "externalId": "CRM_12345",
        "metadata": {
          "name": "John Doe",
          "company": "Acme Corp"
        },
        "status": "raw",
        "scheduledFor": "2024-12-25T09:00:00Z",
        "priority": 10,
        "attempts": 0,
        "_creationTime": 1703520000000
      },
      {
        "_id": "jh7abc456def",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "phoneNumber": "+15555555678",
        "externalId": "CRM_67890",
        "metadata": {
          "name": "Jane Smith",
          "company": "Tech Inc"
        },
        "status": "raw",
        "priority": 5,
        "attempts": 0,
        "_creationTime": 1703520100000
      }
    ],
    "count": 2
  },
  "error": null
}
Endpoint Alias: You can also use /api/v1/records instead of /api/v1/leads. Both endpoints are functionally identical - use whichever naming convention fits your integration.

​
Authentication

​
x-api-key
string
required
Your API key with read or write scope

​
Query Parameters

​
campaignId
string
required
The ID of the campaign to list leads for
​
status
string
Filter leads by statusOptions:
  • raw - Never been called
  • attempting - Currently being called
  • exhausted - Max attempts reached
  • concluded - Successfully completed

​
Response

​
success
boolean
Whether the request was successful
​
data
object
​
error
string | null
Error message if request failed
curl "https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "leads": [
      {
        "_id": "jh7abc123xyz",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "phoneNumber": "+15555551234",
        "externalId": "CRM_12345",
        "metadata": {
          "name": "John Doe",
          "company": "Acme Corp"
        },
        "status": "raw",
        "scheduledFor": "2024-12-25T09:00:00Z",
        "priority": 10,
        "attempts": 0,
        "_creationTime": 1703520000000
      },
      {
        "_id": "jh7abc456def",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "phoneNumber": "+15555555678",
        "externalId": "CRM_67890",
        "metadata": {
          "name": "Jane Smith",
          "company": "Tech Inc"
        },
        "status": "raw",
        "priority": 5,
        "attempts": 0,
        "_creationTime": 1703520100000
      }
    ],
    "count": 2
  },
  "error": null
}

​
Lead Status Lifecycle

Status Meanings:
  • raw: Lead has never been called
  • attempting: Lead is currently in the calling queue
  • exhausted: Max call attempts reached without success
  • concluded: Call completed successfully

​
Common Errors

ErrorCauseSolution
campaignId query parameter is requiredMissing campaignIdAdd campaignId to query string
Invalid or inactive API keyWrong API keyCheck your API key
Campaign not found or access deniedWrong campaign or no accessVerify campaignId and API key scope

​
Usage Tips

Filtering: Use the status parameter to focus on specific subsets:
  • status=raw - See leads that haven’t been called yet
  • status=attempting - Monitor active calls
  • status=concluded - Review completed calls
Results are returned in creation order (oldest first). Pagination coming soon!