--- title: "Running an API campaign" slug: "running-an-api-campaign" description: "Use the Voiso Campaigns APIs to add contacts to your live outbound Dialer campaign." updated: 2026-06-04T10:16:04Z published: 2026-06-04T10:16:04Z canonical: "docs.voiso.com/running-an-api-campaign" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.voiso.com/llms.txt > Use this file to discover all available pages before exploring further. # Running an API campaign **Who should read this article**: Administrators Use the Voiso Campaigns APIs to add contacts to your live outbound Dialer campaign. ## Introduction Voiso provides a variety of APIs that you can use to automate many processes and manage your active [Live campaign](/v1/docs/outbound-dialer-campaign-dialer-campaigns#live-campaign). Voiso supports Dialer campaign integrations with several common CRMs (refer to [Running a CRM campaign](/v1/docs/outbound-dialer-running-a-crm-campaign)). If you use a CRM, Helpdesk, or other data source for contacts that is not currently supported by an [integration](/v1/docs/integrations), you can easily use the Voiso [Add leads to a campaign](https://developers.voiso.com/reference/addleads) API to submit a list of contacts to your Live Dialer campaign. For details, refer to the **Campaigns** APIs in the [Voiso Developer Portal](https://developers.voiso.com/reference/api-documentation-introduction). ### List campaigns API Use the **[Get list of campaigns](https://developers.voiso.com/reference/getcampaigns)** API to get a list of your current campaigns and to add a list of contacts to an active [Live campaign](/v1/docs/outbound-dialer-campaign-dialer-campaigns#live-campaign). ### Add campaign contacts API The [Add leads to a campaign](https://developers.voiso.com/reference/addleads) API enables you to programmatically add multiple contacts to an active Dialer campaign. For example, you can enable third-party automation to add contacts based on certain conditions, such as adding a contact to a campaign when a new lead is created in your CRM, Helpdesk, or other data source. Limitations - **Maximum contacts**: Each `Leads` API call supports a maximum of 1000 new contacts. The Campaigns API verifies the phone numbers to ensure they are valid and unique. Invalid or duplicate records are rejected. - **Rate limiting**: Voiso recommends not invoking multiple simultaneous `Leads` API calls to the same campaign. Wait at least two seconds after the first request is complete before invoking a second one. If processing is not complete, a new request will be rejected. ### Update campaign contacts Use the [Update campaign leads](https://developers.voiso.com/reference/updateleads) API to update existing contacts/leads in a live Dialer campaign. Contacts are identified by their phone number. You can only update the contact name, source, URL, active state, and priority. ### Change campaign status After you [create a live Dialer campaign](/v1/docs/running-an-api-campaign#create-a-live-dialer-campaign) in your contact center, you can use the [start](https://developers.voiso.com/reference/startcampaign), [stop](https://developers.voiso.com/reference/stopcampaign), or [pause](https://developers.voiso.com/reference/pausecampaign) endpoints to manage your campaign. ### Update campaign agents and teams Use the [Add users to a campaign](https://developers.voiso.com/reference/addcampaignusers) API to manage agents and teams assigned to a campaign programmatically. This endpoint enables external applications to dynamically assign agents and teams from an active Dialer campaign. Use [Remove user from a campaign](https://developers.voiso.com/reference/removecampaignuser) endpoint to remove agents from a campaign. This is useful for automating campaign workforce management, especially in real-time dialing scenarios where campaign membership changes frequently. ## How to run an API campaign ### Create a Live Dialer campaign Live Outbound Dialer campaigns automatically dial a list of contacts that you have added to the campaign. The campaign remains active until you stop it. When all the contacts in the calling list have been called, the Live Dialer campaign waits for more contacts to be added before resuming dialing. Follow these steps to set up a Live Dialer campaign: 1. From the main menu bar, navigate to **Outbound > Dialer campaigns**. 2. In the **Dialer campaigns** page, click **Add Dialer campaign**. 3. Follow the steps in [Adding a new campaign](/v1/docs/outbound-dialer-adding-a-new-campaign) to configure the campaign. 4. Select **Live campaign**. You do not need to specify a **Poll interval** as this will be determined by the application you create to use the **Add contacts** API. 5. In the **Calling list** section, set the **Method** to **File import (CSV, XLSX)**. You do not need to import a calling list file if all of the contacts in the campaign are being provided by the **Add contacts** API. 6. Click **Save**. ![Dialer%20API%20Campaign%20Add%20Campaign](https://cdn.document360.io/44ae307a-3737-4fbf-98e0-9b888deb90dc/Images/Documentation/Dialer%20API%20Campaign%20Add%20Campaign.png) Tip If the Dialing order feature is enabled for your contact center, the **Enable Dialing order** option is available. Refer to [Adding a new campaign](/v1/docs/outbound-dialer-adding-a-new-campaign#live-campaigns) for details. ### Create an application To automatically add contacts to your Live Dialer campaign using the **[Add leads to a campaign](https://developers.voiso.com/reference/addleads)** API, create an application that extracts contact information from your CRM, Helpdesk, or other data source and adds it to the body of an **Add contacts** POST request: ``` https://{{baseUrl}}/api/v4/campaigns/{campaign_id}/leads ``` | Name | Description | | --- | --- | | {{baseUrl}} | The name of the Voiso cluster where your contact center is located. Refer to [Base URL](https://developers.voiso.com/reference/base-url). | | :api_key | The [scoped API key](/v1/docs/api-keys) of the user making the request. Voiso responds with the list of campaigns the requesting user is permitted to access. Refer to [Authentication](https://developers.voiso.com/reference/authentication). | | :campaign_id | The ID of the campaign, which can be obtained by using a [Get list of campaigns](https://developers.voiso.com/reference/getcampaigns) API request or from the **Outbound > Campaigns** page. | The following is the expected format of the body of the request: ``` curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/3/leads" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "phone_number": "15551234567", "name": "John Doe", "priority": 10, "active": true, "source": { "system": "my_crm", "url": "https://example.com/leads/123" }, "context_headers": { "X-Call-Context": "discount_promo_code", "X-Client-Order-Id": "1234" } }, { "phone_number": "15557654321", "active": false } ]' ``` ### Running and monitoring the campaign When you first create a Live Dialer campaign without contacts, its status on the **Dialer campaigns** page is **Draft** (1). The total number of contacts in a live campaign is unknown while the campaign is running, so in the **Campaigns** table, the infinity symbol (∞) is displayed in the **Contacts** column (2) and a dash (-) is displayed in the **Progress** column (3). The controls (4) are not enabled until contacts are added to the campaign. ![Dialer%20API%20Campaign%20Draft%20Status](https://cdn.document360.io/44ae307a-3737-4fbf-98e0-9b888deb90dc/Images/Documentation/Dialer%20API%20Campaign%20Draft%20Status.png) When contacts are added to the campaign by your [application](/v1/docs/running-an-api-campaign#create-an-application), the controls become available. ![Dialer%20API%20Campaign%20Draft%20Status%20Start%20Enabled](https://cdn.document360.io/44ae307a-3737-4fbf-98e0-9b888deb90dc/Images/Documentation/Dialer%20API%20Campaign%20Draft%20Status%20Start%20Enabled.png) Tip While a campaign is running, use the **Ready to dial** column in the **Dialer campaigns** page to monitor how many contacts are currently available for dialing. This value represents the number of contacts Dialer would attempt to call immediately if there were no limits on available agents or concurrent call attempts. ### Start, pause, or stop the campaign via API You can control a campaign’s state programmatically using the Campaigns endpoints. This is useful for integrating campaign control into custom dashboards or automations, such as starting a campaign when agents become available or pausing it when contact quotas are met. Use one of the following endpoints: - Start campaign `POST /api/v4/campaigns/{campaign_id}/start` - Pause campaign `POST /api/v4/campaigns/{campaign_id}/pause` - Stop campaign `POST /api/v4/campaigns/{campaign_id}/stop` #### Example requests Start a campaign: ``` curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/start" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` Pause a campaign: ``` curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/pause" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` Stop a campaign: ``` curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/stop" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` #### Response If successful, each endpoint returns the updated campaign object, including the current `status`. Note Only users with the required campaign permissions can use these endpoints. Live campaigns can pause automatically in these cases: - There are no new contacts available. - There are no contacts available that meet the local time requirement. - There are no signed-in agents available. Live campaigns resume when new contacts are available that meet the local time constraint and there are signed-in agents available to handle the calls. Note Live campaigns run until you stop them. You can stop campaigns in the **Campaigns** page or by using the Stop campaign endpoint. ### Manage agents assigned to a campaign You can manage campaign membership programmatically using the Campaigns endpoints. This is useful for automating campaign staffing from external systems. Use these endpoints: - Get users assigned to a campaign `GET /api/v4/campaigns/{campaign_id}/users` - Add users to a campaign `POST /api/v4/campaigns/{campaign_id}/users` - Remove user from a campaign `DELETE /api/v4/campaigns/{campaign_id}/users/{user_id}` #### Example requests Get current campaign users: ``` curl -X GET "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/users?limit=100&offset=0" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` Add users to a campaign: ``` curl -X POST "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/users" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "user_ids": [42, 128] }' ``` Remove a user from a campaign: ``` curl -X DELETE "https://{cluster_id}.voiso.com/api/v4/campaigns/{campaign_id}/users/{user_id}" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` #### Response - Get users assigned to a campaign returns a paginated `users` array with `metadata.total`. - Add users to a campaign returns the users that were added. - Remove user from a campaign returns the removed user. Note To use these endpoints, the authenticated user must have the required campaign permissions for the specified campaign. ## The Agent experience When a campaign is active, the agents you have assigned to the campaign are notified in the **Agent Panel** that a campaign has started. Agents join the campaign from the **Dialer campaign** page in the **Agent Panel**. If you have specified an audio file in the Notification sound on Dialer connection menu of the System Settings [Contact center tab](/v1/docs/contact-center-tab), the first 2 seconds of the audio is played to the agent when the call connects. Refer to [Outbound campaigns](/v1/docs/agent-panel-outbound-campaigns) for more information about how agents participate in Dialer campaigns. ## Monitoring a campaign While a campaign is active or paused, you can monitor the progress using one or more widgets in the **Real-time dashboard**. To add a widget to the **Real-time dashboard**, from the Voiso navigation bar, navigate to **Reporting > Real-time dashboard**. If you do not already have a dashboard, click **Create dashboard**. To use an existing dashboard, select it from the **Dashboards** menu or select **Add dashboard** to add a new dashboard. There are several widgets you can use to track your campaign progress and performance in real-time: ![Reporting Real-time Dashboard Dialer Monitoring Widgets](https://cdn.document360.io/44ae307a-3737-4fbf-98e0-9b888deb90dc/Images/Documentation/Reporting%20Real-time%20Dashboard%20Dialer%20Monitoring%20Widgets.png) Tip For detailed information about a widget, in the **Add new widget** panel, click the "i" icon next to the widget name. | Widget | Description | | --- | --- | | Campaign – Call Disposition | A pie-chart displaying calls by network response: answered, no answer, busy, rejected, or failed | | Campaign Status | A dashboard summarizing various campaign metrics, such duration of the campaign, the average time an agent waits for the next call, how often customers drop off, the average time spent on calls, and the ratio of calls answered to total calls made | | Campaign – Dial Attempts | A bar graph displaying the number of times that each campaign contact was dialed | | Campaign – Agent Counter | A pie chart displaying the number of agents who have joined the campaign and their status: outbound (on a call), waiting, and wrapping-up | | Campaign – Wrap-up Codes | A pie chart displaying the number of campaign calls by the [wrap-up codes](/v1/docs/administration-wrap-up-codes) (after-call work completions) that you defined | ![Dialer Real-time Dashboard](https://cdn.document360.io/44ae307a-3737-4fbf-98e0-9b888deb90dc/Images/Documentation/Dialer%20Real-time%20Dashboard.png) ## Campaign reports Voiso provides campaign reports for active, paused, stopped, and completed campaigns. Use campaign reports to monitor performance while a campaign is running or to review results after it has finished. - For information about monitoring campaign performance in real time, refer to [Part 5: Real-time Dialer campaign monitoring](/v1/docs/outbound-dialer-campaign-real-time-monitoring). - For information about campaign reports and calling list reports, refer to [Part 6: Reviewing campaign results](/v1/docs/outbound-dialer-campaign-reviewing-campaign-results). Customer Relationship Management. A service for managing all your organization's relationships and interactions with customers (contacts) and potential customers. It that provides real-time agent access to customer data and previous interaction information to further personalize the customer experience. CRM integration in a contact center can lead to more personalized service, increased customer retention, and more revenue. ## Related - [Campaigns page](/outbound-dialer-campaigns-view.md) - [Outbound campaigns](/agent-panel-outbound-campaigns.md) - [Dialer campaigns](/outbound-dialer-campaigns.md) - [Dialer campaigns overview](/outbound-dialer-campaigns-overview.md) - [Running a campaign](/outbound-dialer-running-a-campaign.md)