Outdial

An outdial defines a set of outbound dialing targets (phone numbers or destinations) used by campaigns to place automated outbound calls.

API Reference: Outdial endpoints

Overview

Note

AI Context

Complexity: Low-Medium
Cost: Free. Creating outdials and targets is free. Costs are incurred when a campaign dials the targets.
Async: No. POST /outdials and POST /outdials/{id}/targets return immediately with the created resource.

VoIPBIN’s Outdial API provides a scalable solution for managing outbound call destinations. An outdial is a collection of targets (phone numbers, SIP URIs, email addresses) that campaigns or flows dial sequentially. With built-in retry tracking and status management, the Outdial API handles large-scale outbound operations efficiently.

With the Outdial API you can:

Create and manage dial target lists
Track dial attempts and outcomes
Configure per-target retry counts
Monitor target status in real-time
Import targets in bulk

How Outdials Work

Outdials serve as the “who to contact” component of campaigns and outbound flows.

Outdial Architecture

+-----------------------------------------------------------------------+
|                         Outdial System                                |
+-----------------------------------------------------------------------+

+-------------------+
|      Outdial      |
|  (target list)    |
+--------+----------+
         |
         | contains
         v
+--------+----------+--------+----------+--------+----------+
|                   |                   |                   |
v                   v                   v                   v
+----------+   +----------+   +----------+   +----------+
| Target 1 |   | Target 2 |   | Target 3 |   | Target N |
| +1555... |   | +1666... |   | +1777... |   |   ...    |
+----+-----+   +----+-----+   +----+-----+   +----+-----+
     |              |              |              |
     v              v              v              v
+---------+    +---------+    +---------+    +---------+
| Status  |    | Status  |    | Status  |    | Status  |
| Retries |    | Retries |    | Retries |    | Retries |
+---------+    +---------+    +---------+    +---------+

Key Components

Outdial: A container that groups multiple dial targets together
Outdial Target: An individual destination with its address and retry count
Address: The destination (phone number, SIP URI, email)
Try Count: Number of dial attempts remaining for this target

Note

AI Implementation Hint

Outdialtargets support up to 5 destination addresses (destination_0 through destination_4). Each destination has its own independent try count. The campaign dials destination_0 first, and if all retries are exhausted, moves to destination_1, and so on. Do not modify targets while the parent campaign is in running status.

Target Lifecycle

Each outdial target progresses through states as dial attempts occur.

Target States

POST /outdials/{id}/targets
       |
       v
+------------+
|   idle     |<-----------------+
+-----+------+                  |
      |                         |
      | dial attempt            | retry scheduled
      v                         |
+------------+                  |
|  dialing   |------------------+
+-----+------+
      |
      +---------+---------+
      |         |         |
      v         v         v
+--------+ +--------+ +--------+
|answered| |  busy  | |no answer|
+--------+ +--------+ +--------+
      |         |         |
      v         v         v
+------------+ +-------------------+
|  finished  | | retry or failed   |
+------------+ +-------------------+

State Descriptions

Managing Outdials

Create outdials and add targets via the API.

Create an Outdial

$ curl -X POST 'https://api.voipbin.net/v1.0/outdials?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "January Leads",
        "detail": "Sales leads for Q1 campaign"
    }'

Add Targets to Outdial

$ curl -X POST 'https://api.voipbin.net/v1.0/outdials/<outdial-id>/targets?token=<token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "targets": [
            {
                "destination": {
                    "type": "tel",
                    "target": "+15551234567"
                },
                "try_count_max": 3
            },
            {
                "destination": {
                    "type": "tel",
                    "target": "+15559876543"
                },
                "try_count_max": 3
            }
        ]
    }'

Get Outdial Targets

$ curl -X GET 'https://api.voipbin.net/v1.0/outdials/<outdial-id>/targets?token=<token>'

Retry Mechanism

Outdial targets track retry attempts automatically.

Retry Flow

Target dialed
     |
     v
+-------------------+     Answered     +-------------------+
| Dial attempt      |----------------->| Mark as finished  |
|                   |                  |                   |
+--------+----------+                  +-------------------+
         |
         | Not answered (busy, no answer, failed)
         v
+-------------------+
| try_count_current |
| += 1              |
+--------+----------+
         |
         v
+-------------------+     Yes          +-------------------+
| try_count_current |----------------->| Schedule retry    |
| < try_count_max?  |                  | (per outplan)     |
+--------+----------+                  +-------------------+
         |
         | No (max reached)
         v
+-------------------+
| Mark as failed    |
+-------------------+

Retry Configuration

Field	Description
try_count_max	Maximum number of dial attempts allowed
try_count_current	Current number of attempts made (read-only)

The retry timing and intervals are controlled by the Outplan.

Target Types

Outdial targets support various destination types.

Type	Description
tel	Phone number in E.164 format (+15551234567)
sip	SIP URI (sip:user@domain.com)
email	Email address (for email campaigns)

Tel Target Example

{
    "destination": {
        "type": "tel",
        "target": "+15551234567"
    },
    "try_count_max": 3
}

SIP Target Example

{
    "destination": {
        "type": "sip",
        "target": "sip:[email protected]"
    },
    "try_count_max": 2
}

Common Scenarios

Scenario 1: Sales Lead List

Import and manage a sales prospect list.

1. Create outdial: "Q1 Sales Leads"

2. Bulk import targets:
   +--------------------------------------------+
   | +15551234567 | John Smith   | 3 retries   |
   | +15552345678 | Jane Doe     | 3 retries   |
   | +15553456789 | Bob Johnson  | 3 retries   |
   | ... (1000 more targets)                   |
   +--------------------------------------------+

3. Attach to campaign with sales outplan

4. Monitor progress:
   - 800 answered (finished)
   - 150 failed (max retries)
   - 50 pending (scheduled retry)

Scenario 2: Appointment Confirmations

Daily appointment reminder targets.

Daily Process:
+--------------------------------------------+
| 1. Create new outdial for tomorrow's date  |
|    "Appointments 2024-01-16"               |
|                                            |
| 2. Add patients with appointments:         |
|    - Each target gets 2 retry attempts     |
|    - Include appointment time in metadata  |
|                                            |
| 3. Attach to reminder campaign             |
|                                            |
| 4. Campaign runs, marks confirmed targets  |
+--------------------------------------------+

Scenario 3: Emergency Contact List

Critical notifications requiring high delivery.

Setup:
+--------------------------------------------+
| Outdial: "Emergency Contacts"              |
| - All employees/customers                  |
| - High retry count (5)                     |
| - Multiple contact methods per person      |
+--------------------------------------------+

Target Priority:
1. Primary mobile: +15551234567 (5 retries)
2. Secondary mobile: +15559876543 (5 retries)
3. Office phone: +15551111111 (3 retries)

Best Practices

1. Target Quality

Validate phone numbers before import
Use E.164 format for all phone numbers
Remove duplicates within the same outdial
Keep target lists focused and segmented

2. Retry Configuration

Set try_count_max based on campaign urgency
Sales: 3-5 retries over multiple days
Reminders: 1-2 retries within hours
Emergencies: 5+ retries with short intervals

3. List Management

Archive completed outdials for reporting
Don’t modify active outdials during campaign
Create new outdials for recurring campaigns
Use descriptive names with dates

4. Performance

Break large lists into multiple outdials
Monitor target status during campaigns
Remove invalid targets proactively
Track delivery rates for optimization

Troubleshooting

Target Issues

Symptom	Solution
Target not being dialed	Check target status is “idle”; verify outdial is attached to running campaign
All targets failing	Validate phone number format; check carrier routing; verify source number
Retries not happening	Check try_count_max > try_count_current; verify outplan retry settings

Outdial Issues

Symptom	Solution
Can’t add targets	Check outdial exists; verify API permissions
Targets missing	Check pagination in GET request; verify targets were created successfully
Wrong target count	Duplicates may have been filtered; check for import errors

Outdial

{
    "id": "<string>",
    "campaign_id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "data": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The outdial’s unique identifier. Returned when creating via POST /outdials or listing via GET /outdials.
campaign_id (UUID): The campaign this outdial is attached to. Obtained from the id field of GET /campaigns. Set to 00000000-0000-0000-0000-000000000000 if not attached to any campaign.
name (String): Human-readable name for the outdial.
detail (String): Detailed description of the outdial’s purpose.
data (String): Arbitrary data associated with the outdial. Can be used for custom metadata.
tm_create (string, ISO 8601): Timestamp when the outdial was created.
tm_update (string, ISO 8601): Timestamp of the last update to any outdial property.
tm_delete (string, ISO 8601): Timestamp when the outdial was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

AI Implementation Hint

A tm_delete value of 9999-01-01 00:00:00.000000 means the resource has not been deleted. This is a sentinel value, not a real timestamp.

Example

{
    "id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "campaign_id": "00000000-0000-0000-0000-000000000000",
    "name": "test outdial",
    "detail": "outdial for test use.",
    "data": "",
    "tm_create": "2022-04-28 01:41:40.503790",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Outdialtarget

{
    "id": "<string>",
    "outdial_id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "data": "<string>",
    "status": "<string>",
    "destination_0": {
        ...
    },
    "destination_1": {
        ...
    },
    "destination_2": {
        ...
    },
    "destination_3": {
        ...
    },
    "destination_4": {
        ...
    },
    "try_count_0": <number>,
    "try_count_1": <number>,
    "try_count_2": <number>,
    "try_count_3": <number>,
    "try_count_4": <number>,
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The outdialtarget’s unique identifier. Returned when creating via POST /outdials/{id}/targets or listing via GET /outdials/{id}/targets.
outdial_id (UUID): The parent outdial this target belongs to. Obtained from the id field of GET /outdials.
name (String): Human-readable name for the target (e.g., contact name).
detail (String): Detailed description of the target.
data (String): Arbitrary data associated with the target. Can be used for custom metadata.
status (enum string): The outdialtarget’s current status. See Status.
destination_0 (Object or null): Primary destination address. See Address. Set to null if not configured.
destination_1 (Object or null): Secondary destination address. See Address. Set to null if not configured.
destination_2 (Object or null): Third destination address. See Address. Set to null if not configured.
destination_3 (Object or null): Fourth destination address. See Address. Set to null if not configured.
destination_4 (Object or null): Fifth destination address. See Address. Set to null if not configured.
try_count_0 (Integer): Current number of dial attempts made to destination_0. Read-only, incremented by the system.
try_count_1 (Integer): Current number of dial attempts made to destination_1. Read-only.
try_count_2 (Integer): Current number of dial attempts made to destination_2. Read-only.
try_count_3 (Integer): Current number of dial attempts made to destination_3. Read-only.
try_count_4 (Integer): Current number of dial attempts made to destination_4. Read-only.
tm_create (string, ISO 8601): Timestamp when the outdialtarget was created.
tm_update (string, ISO 8601): Timestamp of the last update to any outdialtarget property.
tm_delete (string, ISO 8601): Timestamp when the outdialtarget was deleted. Set to 9999-01-01 00:00:00.000000 if not deleted.

Note

AI Implementation Hint

Each outdialtarget supports up to 5 destinations (destination_0 through destination_4). The campaign dials destinations in order, starting with destination_0. When all retries for a destination are exhausted (try_count_N reaches the outplan’s max_try_count_N), it moves to the next destination. A tm_delete value of 9999-01-01 00:00:00.000000 is a sentinel meaning the resource has not been deleted.

Example

{
    "id": "1b3d7a92-7146-466d-90f5-4bc701ada4c0",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "name": "test destination 0",
    "detail": "test detatination 0 detail",
    "data": "test data",
    "status": "done",
    "destination_0": {
        "type": "tel",
        "target": "+821100000001",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destination_1": null,
    "destination_2": null,
    "destination_3": null,
    "destination_4": null,
    "try_count_0": 1,
    "try_count_1": 0,
    "try_count_2": 0,
    "try_count_3": 0,
    "try_count_4": 0,
    "tm_create": "2022-04-30 17:52:16.484341",
    "tm_update": "2022-04-30 17:53:51.183345",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Status

The outdialtarget’s current processing status. This is a read-only field managed by the system.

Type	Description
idle	The outdialtarget is idle and available to be dialed. This is the initial state after creation and the state it returns to between retry attempts.
progressing	The outdialtarget is currently being dialed. A campaigncall is active for this target.
done	The outdialtarget has completed processing. Either the call was answered successfully or all retry attempts have been exhausted.

state diagram

_images/outdial_struct_outdialtarget_status.png

Tutorial

Before working with outdials, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
Target phone numbers in E.164 format (e.g., +15551234567) for telephone destinations.
(Optional) SIP URIs for SIP destinations or email addresses for email campaigns.

Note

AI Implementation Hint

Outdialtargets support up to 5 destinations per target (destination_0 through destination_4). The campaign dials destinations in order, moving to the next only when all retries on the current destination are exhausted. Phone numbers must be in E.164 format with the + prefix.

Get list of outdials

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/outdials?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "40bea034-1d17-474d-a5de-da00d0861c69",
            "campaign_id": "00000000-0000-0000-0000-000000000000",
            "name": "test outdial",
            "detail": "outdial for test use.",
            "data": "",
            "tm_create": "2022-04-28 01:41:40.503790",
            "tm_update": "9999-01-01 00:00:00.000000",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2022-04-28 01:41:40.503790"
}

Get a detail of outdial

curl --location --request GET 'https://api.voipbin.net/v1.0/outdials/40bea034-1d17-474d-a5de-da00d0861c69?token=<YOUR_AUTH_TOKEN>'

{
    "id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "campaign_id": "00000000-0000-0000-0000-000000000000",
    "name": "test outdial",
    "detail": "outdial for test use.",
    "data": "",
    "tm_create": "2022-04-28 01:41:40.503790",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Create a new outdial

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/outdials?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --header 'Cookie: token=<YOUR_AUTH_TOKEN>' \
    --data-raw '{
        "name": "test outdial",
        "detail": "outdial for test use.",
        "data": "test data"
    }'

Create a new outdialtarget

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/outdials/40bea034-1d17-474d-a5de-da00d0861c69/targets?token=<YOUR_AUTH_TOKEN>' \
    --header 'Content-Type: application/json' \
    --header 'Cookie: token=<YOUR_AUTH_TOKEN>' \
    --data-raw '{
        "name": "test destination 0",
        "detail": "test detatination 0 detail",
        "data": "test data",
        "destination_0": {
            "type": "tel",
            "target": "+15559876543"
        }
    }'

{
    "id": "1b3d7a92-7146-466d-90f5-4bc701ada4c0",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "name": "test destination 0",
    "detail": "test detatination 0 detail",
    "data": "test data",
    "status": "idle",
    "destination_0": {
        "type": "tel",
        "target": "+15559876543",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destination_1": null,
    "destination_2": null,
    "destination_3": null,
    "destination_4": null,
    "try_count_0": 0,
    "try_count_1": 0,
    "try_count_2": 0,
    "try_count_3": 0,
    "try_count_4": 0,
    "tm_create": "2022-04-30 17:52:16.484341",
    "tm_update": "2022-04-30 17:52:16.484341",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Get list of outdialtargets

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/outdials/40bea034-1d17-474d-a5de-da00d0861c69/targets?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "1b3d7a92-7146-466d-90f5-4bc701ada4c0",
            "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
            "name": "test destination 0",
            "detail": "test detatination 0 detail",
            "data": "test data",
            "status": "done",
            "destination_0": {
                "type": "tel",
                "target": "+15559876543",
                "target_name": "",
                "name": "",
                "detail": ""
            },
            "destination_1": null,
            "destination_2": null,
            "destination_3": null,
            "destination_4": null,
            "try_count_0": 1,
            "try_count_1": 0,
            "try_count_2": 0,
            "try_count_3": 0,
            "try_count_4": 0,
            "tm_create": "2022-04-30 17:52:16.484341",
            "tm_update": "2022-04-30 17:53:51.183345",
            "tm_delete": "9999-01-01 00:00:00.000000"
        },
        ...
    ],
    "next_page_token": "2022-04-28 01:44:07.212667"
}

Outdial

Overview

How Outdials Work

Target Lifecycle

Managing Outdials

Retry Mechanism

Target Types

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Outdial

Outdial

Example

Outdialtarget

Outdialtarget

Example

Status

Tutorial

Get list of outdials

Get a detail of outdial

Create a new outdial

Create a new outdialtarget

Get list of outdialtargets