Leads

Import leads into a campaign through the platform's own list-upload validation

POST /v1/leads/import

Scope

leads:write

Tier

Tier 1

Data

Personal data

Idempotency

Idempotency-Key: required

Limit

Up to 200 leads per request

Runs the real campaign list-upload path: sanctioned destinations, phone validation, duplicates in the request and in the campaign, the account's field rules and the Do-Not-Call screen.

Refused with 409 campaign_not_importable unless the campaign is paused, draft or ready: an import into a running campaign would place real calls.

If the Do-Not-Call screen cannot run, the WHOLE import is refused with 503 dnc_screen_unavailable; nothing was written and a retry with the same Idempotency-Key is safe. If the platform cannot confirm the write, the answer is 409 outcome_unknown on every retry of that key until DialerBee has reconciled it.

Exactly one result per input lead, by index (0-based). external_id is stored per API client (two integrations may both use 12345). At most 200 leads per request.

Parameters

Request body

The leads to import.

JSON: LeadImportRequest

Response

200: Every input lead has exactly one result.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/leads/import?campaign_id=cmp_0f8fad5b-d9cb-469f-a165-70867728950e" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "leads": [
    {
      "external_id": "CRM-1001",
      "phone": "+12125550101",
      "full_name": "Ann Lee",
      "email": "[email protected]",
      "custom_fields": {
        "tier": "gold"
      }
    },
    {
      "external_id": "CRM-1002",
      "phone": "+12125550102",
      "full_name": "Omar Haddad"
    }
  ]
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.leads.import_(
    campaign_id="cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
    leads=[
        {
            "external_id": "CRM-1001",
            "phone": "+12125550101",
            "full_name": "Ann Lee",
            "email": "[email protected]",
            "custom_fields": {
                "tier": "gold"
            }
        },
        {
            "external_id": "CRM-1002",
            "phone": "+12125550102",
            "full_name": "Omar Haddad"
        }
    ],
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

200

{
  "campaign_id": "cmp_0f8fad5b-d9cb-469f-a165-70867728950e",
  "data": [
    {
      "index": 0,
      "external_id": "CRM-1001",
      "status": "accepted",
      "reason": null,
      "field": null,
      "lead_id": "lead_0f8fad5b-d9cb-469f-a165-70867728950e"
    },
    {
      "index": 1,
      "external_id": "CRM-1002",
      "status": "duplicate",
      "reason": "duplicate_in_campaign",
      "field": null,
      "lead_id": null
    }
  ],
  "summary": {
    "received": 2,
    "accepted": 1,
    "rejected": 1
  }
}

Error examples

400 batch_too_large

{
  "type": "https://docs.dialerbee.com/errors/batch-too-large",
  "title": "Batch too large",
  "status": 400,
  "detail": "Too many items in one request.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "batch_too_large",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

409 campaign_not_importable

{
  "type": "https://docs.dialerbee.com/errors/campaign-not-importable",
  "title": "Campaign not importable",
  "status": 409,
  "detail": "Leads can only be imported into a campaign that is paused, draft or ready (importing into a running campaign would place real calls; pause it first).",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "campaign_not_importable",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

503 dnc_screen_unavailable

{
  "type": "https://docs.dialerbee.com/errors/dnc-screen-unavailable",
  "title": "Do-Not-Call screen unavailable",
  "status": 503,
  "detail": "The Do-Not-Call screen could not run, so nothing was accepted.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "dnc_screen_unavailable",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

LeadImportRequest

LeadImportResponse

LeadImportSummary

LeadImportItem

LeadResult