Skip to main content
POST
/
api
/
v1
/
leads
curl -X POST https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "YOUR_CAMPAIGN_ID",
    "phoneNumber": "+15555551234",
    "externalId": "CRM_12345",
    "metadata": {
      "name": "John Doe",
      "company": "Acme Corp"
    },
    "priority": 10
  }'

{
  "success": true,
  "data": {
    "leadId": "jh7abc123xyz"
  },
  "error": null
}

Documentation Index

Fetch the complete documentation index at: https://lupitor-docs.com/llms.txt

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

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.

​
Lead Import Modes

The API supports two lead import patterns depending on your data availability:

Standard Mode

Phone number known at import timeProvide phoneNumber directly. The system will call this number when the lead is processed.Best for: CRM exports, contact lists, manual imports

Prefetch Mode

Phone number fetched just-in-timeProvide externalId only. The phone number is fetched from your CRM via a predial function before each call.Best for: CRM integrations where phone numbers change frequently or require real-time validation
At least one of phoneNumber or externalId is required. You can provide both if you want to track the external reference alongside the phone number.

​
Authentication

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

​
Request Body

​
campaignId
string
required
The ID of the campaign this lead belongs to
​
phoneNumber
string
Lead’s phone number in E.164 format (e.g., +15555551234).Required if externalId is not provided.
​
externalId
string
Your CRM’s internal ID for this lead. Used for deduplication and prefetch lookups.Required if phoneNumber is not provided.
​
metadata
object
Custom data about the lead (name, company, notes, etc.)
​
scheduledFor
string
ISO 8601 timestamp for when to call this lead
​
priority
number
default:"0"
Lead priority (higher = called first). Range: 0-100

​
Response

​
success
boolean
Whether the request was successful
​
data
object
​
error
string | null
Error message if request failed

​
Examples

Phone number provided at import time:
curl -X POST https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "YOUR_CAMPAIGN_ID",
    "phoneNumber": "+15555551234",
    "externalId": "CRM_12345",
    "metadata": {
      "name": "John Doe",
      "company": "Acme Corp"
    },
    "priority": 10
  }'

{
  "success": true,
  "data": {
    "leadId": "jh7abc123xyz"
  },
  "error": null
}

​
Notes

Prefetch Mode Requirements: To use prefetch mode (externalId only), your campaign must have a predial function configured. Contact support to set this up.
Duplicate Prevention: Leads are deduplicated by externalId first, then by phoneNumber. If a lead with the same identifier already exists in the campaign, the request will fail.
Scheduling: If you don’t provide scheduledFor, the lead will be called as soon as possible based on business hours and priority.
Phone Format: When providing a phone number, it must be in E.164 format (+ and country code). Example: +15555551234

​
Common Errors

ErrorCauseSolution
campaignId is requiredMissing campaignIdInclude campaignId in request body
At least one of phoneNumber or externalId is requiredNeither identifier providedInclude at least one of phoneNumber or externalId
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
Lead with externalId X already existsDuplicate externalIdLead already exists in campaign
Lead with phone number X already existsDuplicate phoneLead already exists in campaign