Create Lead - AI CSR API

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
  }'

const response = await fetch('https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaignId: 'YOUR_CAMPAIGN_ID',
    phoneNumber: '+15555551234',
    externalId: 'CRM_12345',
    metadata: {
      name: 'John Doe',
      company: 'Acme Corp'
    },
    priority: 10
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'campaignId': 'YOUR_CAMPAIGN_ID',
        'phoneNumber': '+15555551234',
        'externalId': 'CRM_12345',
        'metadata': {
            'name': 'John Doe',
            'company': 'Acme Corp'
        },
        'priority': 10
    }
)

print(response.json())

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

{
  "success": false,
  "data": null,
  "error": "At least one of phoneNumber or externalId is required"
}

POST

api

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
  }'

const response = await fetch('https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaignId: 'YOUR_CAMPAIGN_ID',
    phoneNumber: '+15555551234',
    externalId: 'CRM_12345',
    metadata: {
      name: 'John Doe',
      company: 'Acme Corp'
    },
    priority: 10
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'campaignId': 'YOUR_CAMPAIGN_ID',
        'phoneNumber': '+15555551234',
        'externalId': 'CRM_12345',
        'metadata': {
            'name': 'John Doe',
            'company': 'Acme Corp'
        },
        'priority': 10
    }
)

print(response.json())

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

{
  "success": false,
  "data": null,
  "error": "At least one of phoneNumber or externalId is required"
}

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

string

required

Your API key with write scope

Request Body

string

required

The ID of the campaign this lead belongs to

string

Lead’s phone number in E.164 format (e.g., +15555551234).Required if externalId is not provided.

string

Your CRM’s internal ID for this lead. Used for deduplication and prefetch lookups.Required if phoneNumber is not provided.

object

Custom data about the lead (name, company, notes, etc.)

string

ISO 8601 timestamp for when to call this lead

number

default:"0"

Lead priority (higher = called first). Range: 0-100

Response

boolean

Whether the request was successful

object

Show properties

string

The unique ID of the created lead

string | null

Error message if request failed

Examples

Standard Mode
Prefetch Mode

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
  }'

const response = await fetch('https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaignId: 'YOUR_CAMPAIGN_ID',
    phoneNumber: '+15555551234',
    externalId: 'CRM_12345',
    metadata: {
      name: 'John Doe',
      company: 'Acme Corp'
    },
    priority: 10
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'campaignId': 'YOUR_CAMPAIGN_ID',
        'phoneNumber': '+15555551234',
        'externalId': 'CRM_12345',
        'metadata': {
            'name': 'John Doe',
            'company': 'Acme Corp'
        },
        'priority': 10
    }
)

print(response.json())

External ID only - phone number fetched via predial function:

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",
    "externalId": "SF_LEAD_12345",
    "metadata": {
      "customer_type": "SF_LEAD",
      "lead_id": "00Q5g00000ABC123"
    },
    "priority": 5
  }'

const response = await fetch('https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaignId: 'YOUR_CAMPAIGN_ID',
    externalId: 'SF_LEAD_12345',
    metadata: {
      customer_type: 'SF_LEAD',
      lead_id: '00Q5g00000ABC123'
    },
    priority: 5
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'campaignId': 'YOUR_CAMPAIGN_ID',
        'externalId': 'SF_LEAD_12345',
        'metadata': {
            'customer_type': 'SF_LEAD',
            'lead_id': '00Q5g00000ABC123'
        },
        'priority': 5
    }
)

print(response.json())

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

{
  "success": false,
  "data": null,
  "error": "At least one of phoneNumber or externalId is required"
}

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

Error	Cause	Solution
`campaignId is required`	Missing campaignId	Include campaignId in request body
`At least one of phoneNumber or externalId is required`	Neither identifier provided	Include at least one of phoneNumber or externalId
`Invalid or inactive API key`	Wrong API key	Check your API key
`Campaign not found or access denied`	Wrong campaign or no access	Verify campaignId and API key scope
`Lead with externalId X already exists`	Duplicate externalId	Lead already exists in campaign
`Lead with phone number X already exists`	Duplicate phone	Lead already exists in campaign

​Lead Import Modes

Standard Mode

Prefetch Mode

​Authentication

​Request Body

​Response

​Examples

​Notes

​Common Errors

Lead Import Modes

Authentication

Request Body

Response

Examples

Notes

Common Errors