---
title: "Add leads to a campaign for automated outbound calling"
method: POST
path: "/api/v1/agentic/campaign-leads"
tags: ["Agentic - Campaign Leads"]
---

# Add leads to a campaign for automated outbound calling

`POST /api/v1/agentic/campaign-leads`

## Request

- Base URL: `https://api.voicelogica.ai`
- URL: `https://api.voicelogica.ai/api/v1/agentic/campaign-leads`
- Auth: API key in header `x-api-key`

Upload one or more leads to a campaign. Each lead represents a contact that will be called by the AI agent. You can upload leads in bulk by providing an array of lead objects.

**Required Fields:**
- `campaignId`: ID of the campaign to add leads to
- `phoneNumber` OR `email`: At least one contact method is required

**Optional Fields:**
- `sipTrunkId`: SIP trunk for this lead (get from POST /phones/sip-trunks/query). Falls back to the campaign `sipTrunkIds` when omitted.
- `status`: Initial status (default: "pending")
- `dynamicVariables`: Merge tags for personalization (e.g., firstName, lastName, company)
- `contextForAi`: Additional context to help the AI agent during the call
- `preferredChannel`: Preferred communication channel (phone, email, sms)
- `timeZone`: Timezone for scheduling calls at appropriate times
- `nextActionAt`: Schedule the first call attempt for a specific time

**Dynamic Variables:**
Dynamic variables are used for personalization in AI conversations. Common examples:
- `firstName`, `lastName`: For addressing the lead by name
- `company`: Company name for context
- `productInterest`: Specific product or service they're interested in
- `lastInteraction`: Notes from previous interactions

**Example:** send an array of leads, then activate the campaign so it starts dialing during its schedule.

**Bulk Upload:**
Send the full list in one request. The server drops duplicate phones in the list, matches against existing campaign numbers (including additional numbers), then writes in batches.

## Headers

- `x-api-key` string, required
- `x-company-id` string

## Request body

- object[]: Array of campaign leads to upload
  - `campaignId` string, required: ID of the campaign this lead belongs to
  - `phoneNumber` string: Phone number for the lead contact
  - `additionalPhoneNumbers` union, required: Additional phone numbers for multi-number calling. Accepts a number, a string, or an array. Values may be comma- or space-separated; non-digit characters are stripped automatically.
    - string
    - number
    - union[]
      - union
        - string
        - number
  - `email` string: Email address for the lead contact (will be set to null if invalid)
  - `sipTrunkId` string: SIP trunk to use for this lead. Get IDs from POST /phones/sip-trunks/query. Falls back to the campaign sipTrunkIds when omitted.
  - `callerId` string: Caller ID (e.g. phone number or SIP identity) displayed to the lead when outbound calls are placed — overrides the SIP trunk default
  - `prefix` string: Prefix to use for the lead
  - `status` 'pending' | 'running' | 'successful' | 'cancelled' | 'scheduled' | 'paused' | 'reachedMaxRetries' | 'failed' | 'askedToCallBackLater' | 'askedToNeverCallAgain', required: Current status of the campaign lead
  - `statusUpdatedAt` string, date-time: ISO 8601 date string
  - `nextActionAt` string, date-time: ISO 8601 date string
  - `currentFollowUpCount` number: Number of follow-up attempts made
  - `currentStage` string: Last campaign stage assigned after an attempt
  - `preferredChannel` 'email' | 'phone' | 'sms': Preferred communication channel for this lead
  - `timeZone` string: IANA time zone, e.g. Europe/Athens
  - `dynamicVariables` object: Merge tags and dynamic variables for this lead
  - `analysisResults` object: Analysis results - AI-generated analysis data from call processing
  - `contextForAi` string: Free-text prompt booster for AI interactions
  - `viewUrl` string: URL to view the lead in the campaign
  - `assignedUserId` string: Company user who last took this lead — later campaign dials and post-call work stay with this user

## Response `200`

Leads added successfully

- object
  - `success` boolean, required
  - `count` number, required
  - `message` string, required

## Other responses

- `400`: Bad request - Invalid lead data
- `401`: Unauthorized
- `403`: Invalid CSRF
- `429`: Rate limit exceeded
- `500`: Internal Server Error

---

[API](https://skmtc.dev/voicelogica/apis/voice-logica-api.md) · [All operations](https://skmtc.dev/voicelogica/apis/voice-logica-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voicelogica/apis/voice-logica-api/revisions/30f76840084e?raw)