> ## Documentation Index > Fetch the complete documentation index at: https://docs.valuez.ai/llms.txt > Use this file to discover all available pages before exploring further. # Developer Campaign APIs > End-to-end guide to creating, scheduling, running, and inspecting outbound call campaigns The **Campaign APIs** allow you to automate outbound voice outreach at scale. You can create campaigns, configure telephony dialing parameters, import contacts via CSV, trigger auto-dialing, and fetch call recordings and lead qualifications. All endpoints require the `x-api-key` header containing the API key provided by your workspace admin. See [API Authentication](/dev-authentication). *** ## The Outbound Campaign Lifecycle Executing an automated campaign requires following this 5-step sequence: ```mermaid theme={null} graph TD A[1. Add Campaign Info] --> B[2. Configure Call Rules & Telephony] B --> C[3. Import or Add Contacts] C --> D[4. Map Contacts to Campaign] D --> E[5. Start or Reschedule Campaign] E --> F[6. Inspect Call Logs, Transcripts & Leads] ``` *** ## Step 1: Create Base Campaign Info Initializes the campaign record, assigns the AI agent, and associates products/services. * **Endpoint**: `POST /api/v1/external/campaign/add-update-CampaignInfo` ```json theme={null} { "CampaignKeyID": null, "TenantID": 1, "AgentID": 1, "CampaignName": "Q4 Loan Renewal Outreach", "CampaignType": "Outbound", "CampaignBehaviour": "Single Batch Campaign", "CampaignDescription": "Outreach campaign to existing customers regarding pre-approved loan renewals.", "ProductList": [1], "ServiceList": [1], "IsCompleted": false } ``` | Field | Type | Description | | - | - | - | | `CampaignKeyID` | UUID string | Pass `null` for a new campaign. Returns a new UUID to use in subsequent steps. | | `AgentID` | Integer | The internal integer ID of the AI agent handling the calls. | | `CampaignType` | String | Set to `"Outbound"`. | | `CampaignBehaviour` | String | `"Single Batch Campaign"` or `"Recurring Campaign"`. | | `ProductList` / `ServiceList` | Array of Integers | Product/service IDs from [KB Catalog Lookups](/dev-lookups). | *** ## Step 2: Configure Dialing Rules & Telephony Defines calling hours, retry intervals, virtual numbers, and transfer rules. * **Endpoint**: `POST /api/v1/external/campaign/add-update-outCampaign` ```json theme={null} { "OutboundCampignKeyID": null, "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "PhoneNumberKeyID": "c3723e9d-9fa0-11f1-9559-345a60d76a0d", "LanguageID": "1", "TimeZoneID": "1", "CallingHours": { "start": "10:00", "end": "18:00" }, "MaxConcurrentCalls": 2, "DailyCallLimit": 100, "RetryUnansweredCalls": true, "maxRetries": 2, "RetryInterval": 15, "VoiceMailDetection": true, "TransferToHuman": true, "TransferCallTo": "+919876543210", "LaunchStartDate": "2026-11-01 10:00:00", "LaunchEndDate": "2026-11-05 18:00:00", "LaunchStartTime": "10:00:00", "StopRuleID": 1, "IsCompleted": false } ``` | Field | Type | Description | | - | - | - | | `CampaignKeyID` | UUID string | The UUID generated in Step 1. | | `PhoneNumberKeyID` | UUID string | Virtual number ID for outbound Caller ID (from [Campaign Phone Numbers Lookup](/dev-lookups)). | | `CallingHours` | Object | Permitted calling window (`start` and `end` times). The dialer will not place calls outside this range. | | `MaxConcurrentCalls` | Integer | Parallel active lines to dial simultaneously. | | `DailyCallLimit` | Integer | Maximum numbers dialed per day. | | `RetryUnansweredCalls` | Boolean | Whether to re-dial contacts who did not pick up. | | `maxRetries` | Integer | Maximum retry attempts per contact. | | `RetryInterval` | Integer | Waiting time in minutes before retrying an unanswered call. | | `VoiceMailDetection` | Boolean | Automatically disconnect or hang up when answering machines are detected. | | `TransferToHuman` | Boolean | Allow the agent to transfer interested callers to a human team. | | `TransferCallTo` | String | Target phone number with country code for human transfer. | | `StopRuleID` | Integer | Stop condition ID (from [Stop Rule Lookup](/dev-lookups)). | *** ## Step 3 & 4: Upload & Map Contacts ### Option A: Bulk Upload CSV * **Endpoint**: `POST /api/v1/external/campaign/upload` * **Content-Type**: `multipart/form-data` | Form Field | Type | Description | | - | - | - | | `file` | File | CSV or Excel file containing contact names, phone numbers, and custom variables. | | `CampaignKeyID` | Text | The campaign UUID. | | `OutboundCampignKeyID` | Text | The outbound campaign setup UUID from Step 2. | ### Option B: Add Contacts Manually via JSON * **Endpoint**: `POST /api/v1/external/campaign/add-update-Contacts` ```json theme={null} { "ContactKeyID": null, "CustomerName": "Ramesh Sharma", "ContactNumber": "9876543210", "Email": "ramesh@example.com", "Address": "MG Road", "City": "Mumbai", "State": "Maharashtra", "Country": "India", "Pincode": "400001", "SourceID": 5, "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "OutboundCampignKeyID": "528a3ba9-c2d8-11f1-b170-00090ffe0001" } ``` ### Map Contacts to Campaign After contacts are added, associate their IDs to the dialer queue: * **Endpoint**: `POST /api/v1/external/campaign/map-CampaignContacts` ```json theme={null} { "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "OutboundCampignKeyID": "71b36c1d-c2d9-11f1-b170-00090ffe0001", "ContactID": [153, 154, 155] } ``` *** ## Step 5: Start, Stop, or Schedule the Campaign Control the automated dialer execution: ### Start Campaign * **Endpoint**: `POST /api/v1/external/campaign/start` ```json theme={null} { "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "exotel_app_id": "46335", "exotel_virtual_number": "02240611251" } ``` ### Stop Campaign Immediately halts the auto-dialer: * **Endpoint**: `POST /api/v1/external/campaign/stop` ```json theme={null} { "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001" } ``` ### Restart Campaign Resume a stopped or completed campaign: * **Endpoint**: `POST /api/v1/external/campaign/restart` *** ## Step 6: Monitor Call Logs & Lead Qualification ### 1. Fetch Call Logs Retrieve detailed call records including duration, outcome, and status: * **Endpoint**: `POST /api/v1/external/CallLog/Campaign-log-list` ```json theme={null} { "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "direction": null, "outcome": null, "pageSize": 10, "pageNo": 1, "searchName": "", "fromDate": null, "toDate": null, "sortColumn": "CreatedOn", "sortOrder": "DESC" } ``` ### 2. Download Call Audio Recording * **Endpoint**: `GET /api/v1/external/CallLog/recording/{CallLogID}` * Streams the raw `.wav` or `.mp3` audio recording of the conversation. ### 3. Qualified Leads List Review contacts that expressed positive intent or qualified through agent criteria: * **Endpoint**: `POST /api/v1/external/lead/lead-list` ```json theme={null} { "campaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001", "callOutcome": "Interested", "pageSize": 15, "pageNo": 1, "sortColumn": "CreatedAt", "sortOrder": "DESC" } ``` * **Get Lead Details**: `GET /api/v1/external/lead/GetCampaignLeadDetails?LeadKeyID={uuid}` * **Get Lead Conversation Transcript**: `GET /api/v1/external/lead/get-conversation?LeadKeyID={uuid}` Query live call counts and aggregate metrics. Look up virtual numbers and stop rule IDs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.