---
updatedAt: 2026-06-15T13:35:47.000Z
agentTools:
projectIndex: https://developers.voiso.com/llms.txt
---
# Get list of campaigns
Returns a paginated list of all dialer campaigns.
The **Get list of campaigns** endpoint returns a paginated list of all Dialer campaigns.
Requirements: [Base URL](https://developers.voiso.com/reference/base-url), [Authentication](https://developers.voiso.com/reference/authentication), [Error codes](https://developers.voiso.com/reference/error-codes)
**Scope**: `campaigns.read`
## What this does
When you send a Get list of campaigns request, returns an array of campaign objects plus pagination metadata.
## Endpoint
```
GET /api/v4/campaigns
```
## Query parameters
All query parameters are optional.
* limit\
The number of items to return. Default is 100. Maximum is 100.
* offset\
The number of items to skip before starting to collect the result set. Default is 0.
* name\
The name of the campaign. Typically used as a partial match.
* status\
The campaign status, such as `draft`, `active`, `paused`, `completed`, etc.
* strategy\
The dialing strategy, such as `simple` or `predictive_ai`.
* method\
The campaign dialing method.
* live\
Whether live is enabled for the campaign.
## Example request
```bash
curl -X GET "https://{cluster_id}.voiso.com/api/v4/campaigns?limit=20&offset=40" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json"
```
## Response
If successful, the API returns a `campaigns` array and `metadata`.
`metadata.total` is the total number of campaigns available for the request. The number returned in the current response is `campaigns.length`.
```json
{
"campaigns": [
{
"id": 3,
"name": "Summer Outreach Campaign",
"status": "active",
"strategy": "simple",
"dial_level": 1,
"max_dial_time": 60,
"max_wait_time": 5,
"max_dial_attempts": 3,
"amd_enabled": true,
"amd_voicemail_message": {
"enabled": false,
"voice_message": {
"type": "voice_message",
"name": "Instructions"
}
},
"caller_id_sets": [
{
"phone_numbers": ["18885650001", "18885650002"]
}
],
"follow_up_mode": "timer",
"created_at": "2026-01-15T10:30:00.000Z",
"updated_at": "2026-01-20T14:15:00.000Z"
}
],
"metadata": {
"total": 100
}
}
```
Campaign fields shown above come from the Campaign schema: `id`, `name`, `status`, `strategy`, and `dial_level`.
## Notes
* `status` values include: `draft`, `active`, `paused`, `stopping`, `completed`, `processing`, `stopped`, `auto_paused`, `pausing`, `auto_pausing`, `import_error`.
* `strategy` values include `simple` and `predictive_ai`.
* Each item in `campaigns[]` is a full Campaign object. Some fields can be null depending on which features are enabled and which settings are configured.
## Troubleshooting
### 400 Bad request
Common cause:
* An invalid value was provided for `limit` or `offset`.
### 401 Unauthorized
What to check:
* You are sending `Authorization: Bearer `.
### 403 Forbidden
What to check:
* The API key is valid, but does not have access to campaign resources.
### 429 Too many requests
What to do:
* Reduce request frequency and retry with backoff.
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Voiso API",
"description": "The Voiso APIs follow a conventional REST architecture and are compatible with any programming language.\n\nUse these APIs to securely access data and manage contact center features, settings, and entities.\n",
"version": "4.0.0",
"contact": {
"name": "Support",
"email": "support@voiso.com"
}
},
"servers": [
{
"url": "https://{defaultHost}",
"variables": {
"defaultHost": {
"default": "{cluster_id}.voiso.com"
}
}
}
],
"tags": [
{
"name": "Campaigns"
}
],
"security": [
{
"StaticKey": []
}
],
"paths": {
"/api/v4/campaigns": {
"get": {
"operationId": "getCampaigns",
"tags": [
"Campaigns"
],
"summary": "Get list of campaigns",
"description": "Returns a paginated list of all dialer campaigns.",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Offset"
},
{
"name": "name",
"in": "query",
"description": "A campaign name.",
"schema": {
"type": "string",
"example": "Summer Outreach Campaign",
"minLength": 1
}
},
{
"name": "strategy",
"in": "query",
"description": "Filter by strategy. Accepts a single value or an array.",
"schema": {
"oneOf": [
{
"type": "string",
"enum": [
"advanced",
"simple",
"predictive_ai"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"advanced",
"simple",
"predictive_ai"
]
}
}
]
},
"examples": {
"single": {
"summary": "Single strategy.",
"value": "simple"
},
"multiple": {
"summary": "Multiple strategies.",
"value": [
"simple",
"predictive_ai"
]
}
}
},
{
"name": "status",
"in": "query",
"description": "Filter by status. Accepts a single value or an array.",
"schema": {
"oneOf": [
{
"type": "string",
"enum": [
"draft",
"active",
"paused",
"stopping",
"completed",
"processing",
"stopped",
"auto_paused",
"pausing",
"auto_pausing",
"import_error"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"draft",
"active",
"paused",
"stopping",
"completed",
"processing",
"stopped",
"auto_paused",
"pausing",
"auto_pausing",
"import_error"
]
}
}
]
},
"examples": {
"single": {
"summary": "Single status.",
"value": "draft"
},
"multiple": {
"summary": "Multiple statuses.",
"value": [
"draft",
"active"
]
}
}
},
{
"name": "method",
"in": "query",
"description": "Filter by method. Accepts a single value or an array.",
"schema": {
"oneOf": [
{
"type": "string",
"enum": [
"file_import",
"bitrix_crm",
"falcon_crm",
"hubspot_crm",
"panda_crm",
"salesforce_crm",
"zoho_crm",
"zenoti_crm",
"leverate_crm",
"getlogic_crm"
]
},
{
"type": "array",
"items": {
"type": "string",
"enum": [
"file_import",
"bitrix_crm",
"falcon_crm",
"hubspot_crm",
"panda_crm",
"salesforce_crm",
"zoho_crm",
"zenoti_crm",
"leverate_crm",
"getlogic_crm"
]
}
}
]
},
"examples": {
"single": {
"summary": "Single method.",
"value": "file_import"
},
"multiple": {
"summary": "Multiple methods.",
"value": [
"file_import",
"hubspot_crm"
]
}
}
},
{
"name": "live",
"in": "query",
"description": "Whether or not the campaign type is live.",
"schema": {
"type": "boolean",
"example": true
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Campaign"
}
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403"
},
"429": {
"$ref": "#/components/responses/429"
}
}
}
}
},
"components": {
"parameters": {
"Limit": {
"name": "limit",
"in": "query",
"description": "The number of items to return.",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"maximum": 100,
"minimum": 0
},
"example": 100
},
"Offset": {
"name": "offset",
"in": "query",
"description": "The number of items to skip before starting to collect the result set.",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"minimum": 0
},
"example": 100
}
},
"schemas": {
"Campaign": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier of the campaign.",
"type": "integer",
"example": 3
},
"name": {
"description": "The name of the campaign.",
"type": "string",
"example": "Summer Outreach Campaign"
},
"status": {
"description": "Current status of the campaign.",
"type": "string",
"enum": [
"draft",
"active",
"paused",
"stopping",
"completed",
"processing",
"stopped",
"auto_paused",
"pausing",
"auto_pausing",
"import_error"
],
"example": "active"
},
"strategy": {
"description": "Dialing strategy used by the campaign.",
"type": "string",
"enum": [
"simple",
"predictive_ai"
],
"example": "simple"
},
"dial_level": {
"description": "Number of simultaneous calls per agent.",
"type": "number",
"format": "float",
"example": 1
},
"dial_level_override": {
"description": "Override dial level settings based on agent availability.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether the dial level override is enabled.",
"type": "boolean",
"example": true
},
"value": {
"description": "Override dial level value.",
"type": "number",
"format": "float",
"example": 1.5
},
"active_agents_threshold": {
"description": "Minimum number of active agents to trigger override.",
"type": "integer",
"example": 3
}
}
},
"max_dial_time": {
"description": "Maximum dial time in seconds before hanging up.",
"type": "integer",
"example": 60
},
"max_wait_time": {
"description": "Maximum wait time in seconds for agent availability.",
"type": "integer",
"example": 5
},
"max_dial_attempts": {
"description": "Maximum number of dial attempts per lead.",
"type": "integer",
"example": 3
},
"voice_message": {
"description": "Voice message played during the call.",
"allOf": [
{
"$ref": "#/components/schemas/MediaVoiceMessage"
}
],
"nullable": true
},
"amd_voicemail_message": {
"description": "Configuration for voicemail playback when an answering machine is detected.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether voicemail playback is enabled when an answering machine is detected.",
"type": "boolean",
"example": false
},
"voice_message": {
"description": "Voice message played when an answering machine is detected.",
"allOf": [
{
"$ref": "#/components/schemas/MediaVoiceMessage"
}
],
"nullable": true
}
}
},
"amd_enabled": {
"description": "Whether answering machine detection is enabled.",
"type": "boolean",
"example": true
},
"amd_comfort_noise_enabled": {
"description": "Whether comfort noise plays in the background while answering machine detection analyzes the answered call. When disabled, the audio the campaign plays while the contact waits for an agent starts as soon as the contact answers. Available only if answering machine detection is enabled for the campaign.\n",
"type": "boolean",
"example": true,
"nullable": true
},
"live": {
"description": "Whether the campaign uses live dialing mode.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether adding leads to the running campaign is enabled.",
"type": "boolean",
"example": true
},
"dialing_order": {
"description": "The order in which new leads are dialed. Only available when live is enabled and the dialing order feature is enabled for the contact center.\n- `fifo` — oldest contacts are dialed first\n- `lifo` — newest contacts are dialed first\n",
"type": "string",
"enum": [
"fifo",
"lifo"
],
"example": "fifo",
"nullable": true
}
}
},
"calling_list": {
"description": "Configuration for the calling list source.",
"type": "object",
"nullable": true,
"properties": {
"method": {
"description": "Method used to populate the calling list.",
"type": "string",
"enum": [
"file_import",
"bitrix_crm",
"falcon_crm",
"hubspot_crm",
"panda_crm",
"salesforce_crm",
"zoho_crm",
"zenoti_crm",
"leverate_crm",
"getlogic_crm"
],
"example": "file_import"
}
}
},
"caller_id_sets": {
"description": "Sets of caller IDs used for outbound calls.",
"type": "array",
"items": {
"type": "object",
"properties": {
"phone_numbers": {
"description": "List of phone numbers in the caller ID set.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"18885650001",
"18885650002"
]
}
}
},
"nullable": true
},
"use_local_caller_id": {
"description": "Whether to use local caller ID matching the lead's area.",
"type": "boolean",
"example": false
},
"asr_optimization_enabled": {
"description": "Whether ASR (Answer Seizure Ratio) optimization is enabled.",
"type": "boolean",
"example": true
},
"allow_duplicate_numbers": {
"description": "Whether the same phone number can be added to the campaign more than once.",
"type": "boolean",
"example": false
},
"follow_up_mode": {
"description": "Controls how the dialer prioritizes redial attempts within follow-up rules.\n- `timer` — contacts are prioritized strictly by their configured redial delay (default)\n- `lowest_attempts` — contacts with the fewest dial attempts are prioritized first, while still respecting redial delay timers\n",
"type": "string",
"enum": [
"timer",
"lowest_attempts"
],
"default": "timer",
"example": "timer",
"nullable": true
},
"follow_up_rules": {
"description": "Rules for follow-up actions, grouped by trigger. Groups with no rules are omitted.",
"type": "object",
"properties": {
"machine_answered": {
"description": "Actions when call is answered by machine.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"abandoned": {
"description": "Actions when call is abandoned.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"no_answer": {
"description": "Actions when call is not answered.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"rejected": {
"description": "Actions when call is rejected.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"failed": {
"description": "Actions when call fails.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"busy": {
"description": "Actions when line is busy.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleRedial"
}
},
"wrapup_code": {
"description": "Actions when a call is closed with a given wrap-up code.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupRuleWrapup"
}
}
}
},
"post_call_rating": {
"description": "Post-call survey configuration.",
"type": "object",
"properties": {
"enabled": {
"description": "Whether the post-call survey is enabled for contacts.",
"type": "boolean",
"example": true
},
"notification_voice_message": {
"description": "Voice message played as a survey notification.",
"allOf": [
{
"$ref": "#/components/schemas/MediaVoiceMessage"
}
],
"nullable": true
},
"instructions_voice_message": {
"description": "Voice message played as survey instructions (e.g., \"rate from 1 to 5\").",
"allOf": [
{
"$ref": "#/components/schemas/MediaVoiceMessage"
}
],
"nullable": true
},
"complete_voice_message": {
"description": "Voice message played after survey completion.",
"allOf": [
{
"$ref": "#/components/schemas/MediaVoiceMessage"
}
],
"nullable": true
}
}
},
"contact_local_time": {
"description": "Time restrictions for calling contacts based on their local time. Available only if the contact local time feature is enabled for the contact center.\n",
"type": "object",
"nullable": true,
"properties": {
"start_time": {
"description": "Start time for calls (HH:MM format).",
"type": "string",
"example": "07:30"
},
"end_time": {
"description": "End time for calls (HH:MM format).",
"type": "string",
"example": "22:00"
},
"days_of_week": {
"description": "Days of the week when calls are allowed.",
"type": "array",
"items": {
"type": "integer",
"description": "Day of the week: 1 (Monday) through 7 (Sunday).",
"enum": [
1,
2,
3,
4,
5,
6,
7
]
},
"example": [
1,
2,
3,
4,
5
]
}
}
},
"created_at": {
"description": "Timestamp when the campaign was created (ISO 8601).",
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00.123000Z"
},
"updated_at": {
"description": "Timestamp when the campaign was last updated (ISO 8601).",
"type": "string",
"format": "date-time",
"example": "2026-01-20T14:15:00.456000Z"
}
}
},
"ChannelProfileShort": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier of the channel profile.",
"type": "integer",
"example": 12
},
"channel": {
"description": "The channel associated with the profile.",
"type": "string",
"enum": [
"chat",
"facebook",
"instagram",
"telegram",
"viber",
"whatsapp"
],
"example": "whatsapp"
},
"identifier": {
"description": "Channel profile identifier (for WhatsApp, the phone number).",
"type": "string",
"example": "18885658889",
"nullable": true
},
"name": {
"description": "The name of the channel profile.",
"type": "string",
"example": "WhatsApp Main (18885658889)"
}
}
},
"FollowupActionWhatsapp": {
"type": "object",
"properties": {
"type": {
"description": "Type of follow-up action.",
"type": "string",
"enum": [
"whatsapp"
],
"example": "whatsapp"
},
"channel_profile": {
"description": "WhatsApp channel profile to use.",
"allOf": [
{
"$ref": "#/components/schemas/ChannelProfileShort"
}
]
},
"whatsapp_template": {
"description": "WhatsApp message template to send.",
"allOf": [
{
"$ref": "#/components/schemas/WhatsappTemplateShort"
}
]
}
}
},
"FollowupRuleRedial": {
"type": "object",
"properties": {
"type": {
"description": "Type of follow-up rule.",
"type": "string",
"enum": [
"redial"
],
"example": "redial"
},
"wait_time": {
"description": "Time to wait before executing the action.",
"type": "integer",
"example": 20
},
"wait_time_unit": {
"description": "Unit of wait time.",
"type": "string",
"enum": [
"seconds",
"minutes",
"hours"
],
"example": "minutes"
},
"switch_caller_id_set": {
"description": "Whether to switch to a different caller ID set.",
"type": "boolean",
"example": false
},
"actions": {
"description": "Additional actions to perform with this rule.",
"type": "array",
"items": {
"$ref": "#/components/schemas/FollowupActionWhatsapp"
}
}
}
},
"FollowupRuleWrapup": {
"type": "object",
"properties": {
"type": {
"description": "Type of follow-up rule.",
"type": "string",
"enum": [
"redial"
],
"example": "redial"
},
"wrapup_code": {
"description": "Wrap-up code that triggers the redial.",
"allOf": [
{
"$ref": "#/components/schemas/WrapupCodeShort"
}
]
},
"wait_time": {
"description": "Time to wait before redialing the contact.",
"type": "integer",
"example": 20
},
"wait_time_unit": {
"description": "Unit of wait time.",
"type": "string",
"enum": [
"seconds",
"minutes",
"hours"
],
"example": "minutes"
},
"switch_caller_id_set": {
"description": "Whether to switch to a different caller ID set.",
"type": "boolean",
"example": false
}
}
},
"MediaVoiceMessage": {
"description": "Voice message Media object.",
"type": "object",
"properties": {
"type": {
"description": "The type of media.",
"type": "string",
"enum": [
"voice_message"
],
"example": "voice_message"
},
"name": {
"description": "The name of the media.",
"type": "string",
"example": "Instructions"
}
}
},
"Metadata": {
"description": "Pagination metadata for list responses.",
"type": "object",
"properties": {
"total": {
"description": "The total number of items available for the requested resource.",
"type": "integer",
"example": 100
},
"next_cursor": {
"description": "Cursor for fetching the next page of results when cursor-based pagination is supported.",
"type": "string",
"nullable": true
}
}
},
"WhatsappTemplateShort": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier of the WhatsApp template.",
"type": "string",
"format": "uuid",
"example": "3f0a7ce4-1b82-4c38-9e59-1e57dc8e2b52"
},
"name": {
"description": "The name of the WhatsApp template.",
"type": "string",
"example": "Missed Call Follow-up"
}
}
},
"WrapupCodeShort": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier of the wrap-up code.",
"type": "integer",
"example": 1
},
"name": {
"description": "The name of the wrap-up code.",
"type": "string",
"example": "Issue Resolved"
},
"code": {
"description": "The wrap-up code value.",
"type": "string",
"example": "0002"
}
}
}
},
"responses": {
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"description": "Error message.",
"type": "string",
"enum": [
"Bad Request"
],
"example": "Bad Request"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"description": "Error message.",
"type": "string",
"enum": [
"Unauthorized"
],
"example": "Unauthorized"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"description": "Error message.",
"type": "string",
"enum": [
"Forbidden"
],
"example": "Forbidden"
}
}
}
}
}
},
"429": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"description": "Error message.",
"type": "string",
"enum": [
"Too many requests"
],
"example": "Too many requests"
}
}
}
}
}
}
},
"securitySchemes": {
"StaticKey": {
"description": "API key provided as a Bearer token.",
"type": "http",
"scheme": "bearer"
}
}
}
}
```