Skip to main content
POST
https://lupitor.acrely.ai/api/v1
/
api
/
v1
/
leads
/
bulk
curl -X POST https://lupitor.acrely.ai/api/v1/leads/bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "k978z8ndfnqjnbxmphvf0wd59h6yrd0a",
    "leads": [
      {
        "phoneNumber": "+15555551234",
        "externalId": "CRM_001",
        "metadata": {
          "name": "John Doe",
          "company": "Acme Corp"
        },
        "priority": 10
      },
      {
        "phoneNumber": "+15555555678",
        "externalId": "CRM_002",
        "metadata": {
          "name": "Jane Smith",
          "company": "Tech Inc"
        },
        "scheduledFor": "2024-12-25T09:00:00Z",
        "priority": 5
      },
      {
        "phoneNumber": "+15555559999",
        "metadata": {
          "name": "Bob Johnson"
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "created": 3,
    "skipped": 0,
    "createdIds": [
      "jh7abc123xyz",
      "jh7abc456def",
      "jh7abc789ghi"
    ],
    "skippedPhones": []
  },
  "error": null
}

​
Authentication

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

​
Request Body

​
campaignId
string
required
The ID of the campaign these leads belong to
​
leads
array
required
Array of lead objects (max 1000 per request)

​
Response

​
success
boolean
Whether the request was successful
​
data
object
​
error
string | null
Error message if request failed
curl -X POST https://lupitor.acrely.ai/api/v1/leads/bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "k978z8ndfnqjnbxmphvf0wd59h6yrd0a",
    "leads": [
      {
        "phoneNumber": "+15555551234",
        "externalId": "CRM_001",
        "metadata": {
          "name": "John Doe",
          "company": "Acme Corp"
        },
        "priority": 10
      },
      {
        "phoneNumber": "+15555555678",
        "externalId": "CRM_002",
        "metadata": {
          "name": "Jane Smith",
          "company": "Tech Inc"
        },
        "scheduledFor": "2024-12-25T09:00:00Z",
        "priority": 5
      },
      {
        "phoneNumber": "+15555559999",
        "metadata": {
          "name": "Bob Johnson"
        }
      }
    ]
  }'

{
  "success": true,
  "data": {
    "created": 3,
    "skipped": 0,
    "createdIds": [
      "jh7abc123xyz",
      "jh7abc456def",
      "jh7abc789ghi"
    ],
    "skippedPhones": []
  },
  "error": null
}

​
Limits

Maximum Size: You can create up to 1000 leads per bulk request. For larger imports, make multiple requests.
Rate Limit: Bulk endpoint is limited to 10 requests per minute to prevent abuse.

​
Duplicate Handling

The bulk endpoint automatically handles duplicates:
  1. Checks each phone number against existing leads in the campaign
  2. Skips duplicates without failing the entire request
  3. Returns details about what was created vs skipped
This makes bulk import idempotent - you can safely retry without creating duplicates!

​
Common Errors

ErrorCauseSolution
campaignId is requiredMissing campaignIdInclude campaignId in request body
leads array is requiredMissing or invalid leadsInclude leads array in request body
leads array cannot be emptyEmpty leads arrayAdd at least one lead to the array
Maximum 1000 leads per bulk requestToo many leadsSplit into multiple requests
leads[0].phoneNumber is requiredMissing phone numberEach lead must have a phoneNumber

​
Best Practices

  • Use 100-500 leads per request for optimal performance
  • Don’t max out at 1000 unless necessary
  • Monitor response times and adjust
  • Spread out bulk imports over time
  • Don’t import 10,000 leads at once
  • Respect rate limits (10/min)
  • Validate phone numbers before sending
  • Ensure E.164 format (+15555551234)
  • Remove duplicates in your data first
  • Check the created vs skipped counts
  • Log skippedPhones for investigation
  • Retry failed requests with exponential backoff

​
Example: CSV Import Script

Python
import csv
import requests
import time

def import_leads_from_csv(file_path, campaign_id, api_key):
    """Import leads from CSV file in batches"""

    batch_size = 500
    leads = []

    with open(file_path, 'r') as file:
        reader = csv.DictReader(file)

        for row in reader:
            leads.append({
                'phoneNumber': row['phone'],
                'externalId': row['id'],
                'metadata': {
                    'name': row['name'],
                    'company': row.get('company', '')
                },
                'priority': int(row.get('priority', 0))
            })

            # Send batch when we hit the limit
            if len(leads) >= batch_size:
                send_batch(leads, campaign_id, api_key)
                leads = []
                time.sleep(6)  # Rate limit: 10/min = 1 every 6 sec

        # Send remaining leads
        if leads:
            send_batch(leads, campaign_id, api_key)

def send_batch(leads, campaign_id, api_key):
    """Send a batch of leads to the API"""

    response = requests.post(
        'https://lupitor.acrely.ai/api/v1/leads/bulk',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'campaignId': campaign_id,
            'leads': leads
        }
    )

    result = response.json()
    print(f"Created: {result['data']['created']}, Skipped: {result['data']['skipped']}")

# Usage
import_leads_from_csv(
    'leads.csv',
    'k978z8ndfnqjnbxmphvf0wd59h6yrd0a',
    'YOUR_API_KEY'
)