Creating and Managing Outbound Calls

This guide walks through the step-by-step process of using the API to manage outbound calls.

Note: Authentication details are covered in the "Getting Started > Authentication" section. Please refer to that guide for information on obtaining and using OAuth2 tokens.

Step 1: Create a Campaign

⚠️ Note: This entity is currently not visible in the Mico Voice AI UI, but can be created and managed via the API. It will become available in the interface as part of a major platform update planned for later in 2025.

A campaign is the top-level entity that contains schedules and outbound calls.

Note: If you're working with an existing CallFlow, you can skip this step and retrieve the associated Campaign UID using the Get CallFlow endpoint:

curl -X GET https://api.micovoice.com/api/v1/call_flows/YOUR_CALLFLOW_UID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response will include a campaign_uid field that you can use for the next steps.

If you don't have an existing campaign yet, here's how to create one:

curl -X POST https://api.micovoice.com/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "My First Campaign",
    "is_enabled": true,
    "type": "scheduled_call"
  }'

Expected Response (Status: 201)

{
  "uid": "09c83f1c-3489-4ac2-876c-bb6d7f3321bf",
  "name": "My First Campaign",
  "is_enabled": true,
  "created_at": "2025-04-16T12:00:00Z",
  "updated_at": "2025-04-16T12:00:00Z"
}

Save the uid from the response - you'll need it to create a schedule.

Step 2: Create a Schedule

⚠️ Note: This entity is currently not visible in the Mico Voice AI UI, but can be created and managed via the API. It will become available in the interface as part of a major platform update planned for later in 2025.

A schedule defines when outbound calls will be made and how retries are handled.

curl -X POST https://api.micovoice.com/api/v1/campaigns/09c83f1c-3489-4ac2-876c-bb6d7f3321bf/schedules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "Morning Calls",
    "starts_at": "2025-04-17T09:00:00Z",
    "ends_at": "2025-04-17T12:00:00Z",
    "retry_type": "consistent",
    "retry_intervals": [300, 300, 300]
  }'

Expected Response (Status: 201)

{
  "uid": "096c36c45-b95c-4ab1-8bb1-6e6e1283c950",
  "name": "Morning Calls",
  "starts_at": "2025-04-17T09:00:00Z",
  "ends_at": "2025-04-17T12:00:00Z",
  "retry_type": "consistent",
  "retry_intervals": [300, 300, 300],
  "is_enabled": false,
  "is_auto": false,
  "created_at": "2025-04-16T12:05:00Z",
  "updated_at": "2025-04-16T12:05:00Z"
}

Save the schedule uid - you'll need it to create outbound calls.

Step 3: Create Outbound Calls

Now that you have a campaign and schedule set up, you can create outbound calls either individually or in bulk.

Important Note: Creating calls will only work if the Schedule is not enabled. By default, a schedule is created in disabled state. Alternatively, you can use the force=true query parameter when creating calls to bypass this restriction.

Step 3A: Create a Single Outbound Call

You can create individual outbound calls with detailed contact information and custom parameters.

curl -X POST https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "phone_number": "+818012345678",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    },
    "external_id": "CUST-123"
  }'

Single Call Creation Details

• Required Fields:

  • phone_number: Contact phone number
  • first_name: Contact's first name
  • last_name: Contact's last name
  • phonetic_first_name: Phonetic spelling of first name
  • phonetic_last_name: Phonetic spelling of last name

• Optional Fields:

  • full_name: Contact's full name
  • phonetic_full_name: Phonetic spelling of full name
  • email: Contact's email address
  • event_date_time: Timestamp for related event
  • custom_parameters: Object containing any custom key-value pairs
  • external_id: Your system's identifier for this call

• Force Parameter: Optional query parameter force=true can be used to bypass schedule enabled status checks

Expected Response (Status: 201)

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "pending",
  "progress": "in_queue",
  "is_test_call": false,
  "number_call_retries": 3,
  "cooldown_until": null,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:10:00Z",
  "outbound_call_info": {
    "phone_number": "5551234567",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    }
  },
  "outbound_call_attempts": [],
  "outbound_calls_notifications": []
}

Save the outbound call uid for later reference.

Step 3B: Bulk Create Outbound Calls

For efficiency, you can create multiple outbound calls at once. The bulk endpoint allows you to create up to 1,000 calls in a single request.

curl -X POST https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "outbound_calls": [
      {
        "phone_number": "5551234567",
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "phonetic_full_name": "John Doe",
        "phonetic_first_name": "John",
        "phonetic_last_name": "Doe",
        "email": "john.doe@example.com",
        "custom_parameters": {
          "appointment_id": "APT-789"
        },
        "external_id": "CUST-123"
      },
      {
        "phone_number": "+818098765432",
        "full_name": "Jane Smith",
        "first_name": "Jane",
        "last_name": "Smith",
        "phonetic_full_name": "Jane Smith",
        "phonetic_first_name": "Jane",
        "phonetic_last_name": "Smith",
        "email": "jane.smith@example.com",
        "custom_parameters": {
          "appointment_id": "APT-456"
        },
        "external_id": "CUST-456"
      }
    ]
  }'

Bulk Creation Details

• Maximum Batch Size: You can include up to 1,000 outbound calls in a single bulk request
• Minimum Batch Size: At least 1 outbound call is required
• Required Fields: Each outbound call requires the same fields as in the single creation endpoint
• Force Parameter: Optional query parameter force=true can be used to bypass schedule enabled status checks

Expected Response (Status: 201)

{
  "outbound_calls": [
    {
      "uid": "d26a3041-1743-413f-9722-04ac1f612960",
      "external_id": "CUST-123",
      "status": "pending",
      "progress": "in_queue"
    },
    {
      "uid": "7f93b218-5c22-476a-9321-e9712fdcb490",
      "external_id": "CUST-456",
      "status": "pending",
      "progress": "in_queue"
    }
  ],
  "total_count": 2,
  "successful_count": 2,
  "failed_count": 0,
  "failures": []
}

If any calls fail during bulk creation, the response will include details in the failures array:

{
  "outbound_calls": [...],
  "total_count": 3,
  "successful_count": 2,
  "failed_count": 1,
  "failures": [
    {
      "index": 2,
      "reason": "Invalid phone number format",
      "details": {
        "phone_number": "Invalid format"
      }
    }
  ]
}

This bulk operation returns a summary of the created calls, including UIDs for each successful call and details about any failures.

Step 4: Enable the schedule

Once the calls are placed, one needs to enable the corresponding schedule to make the calls eligible to be made:

curl -X PATCH https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "is_enabled": true,
  }'

Expected Response (Status: 200)

{
  "uid": "096c36c45-b95c-4ab1-8bb1-6e6e1283c950",
  "name": "Morning Calls",
  "starts_at": "2025-04-17T09:00:00Z",
  "ends_at": "2025-04-17T12:00:00Z",
  "retry_type": "consistent",
  "retry_intervals": [300, 300, 300],
  "is_enabled": true,
  "is_auto": false,
  "created_at": "2025-04-16T12:05:00Z",
  "updated_at": "2025-04-16T12:05:00Z"
}

Step 5: List Outbound Calls

To retrieve all outbound calls associated with a schedule:

curl -X GET https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filtering Options

The API provides extensive filtering capabilities to help you find specific calls:

Parameter	Description	Example
outcome	Filter by call outcome	outcome=Transfer%20to%20agent
attempt_status	Filter by call attempt status	attempt_status=hangup
external_id	Filter by your reference ID	external_id=CUST-123
is_test_call	Include/exclude test calls	is_test_call=true
first_name	Filter by contact's first name	first_name=John
last_name	Filter by contact's last name	last_name=Doe
phonetic_first_name	Filter by phonetic first name	phonetic_first_name=John
phone_number	Filter by contact's phone number	phone_number=%2B818012345678
email	Filter by contact's email	email=john.doe@example.com

Pagination

The response is paginated to manage large datasets:

• page: Which page to return (default: 1)
• page_size: Number of results per page (default: 50, max: 100)

Example with filtering and pagination:

curl -X GET "https://api.micovoice.com/api/v1/schedules/096c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?attempt_status=hangup&page=2&page_size=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Expected Response (Status: 200)

[
  {
    "uid": "d26a3041-1743-413f-9722-04ac1f612960",
    "external_id": "CUST-123",
    "status": "pending",
    "progress": "in_queue",
    "is_test_call": false,
    "number_call_retries": 3,
    "cooldown_until": null,
    "created_at": "2025-04-16T12:10:00Z",
    "updated_at": "2025-04-16T12:10:00Z",
    "outbound_call_info": {
      "phone_number": "5551234567",
      "full_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "phonetic_full_name": "John Doe",
      "phonetic_first_name": "John",
      "phonetic_last_name": "Doe",
      "email": "john.doe@example.com",
      "custom_parameters": {
        "account_id": "A12345",
        "appointment_time": "3:30 PM"
      }
    },
    "outbound_call_attempts": [],
    "outbound_calls_notifications": []
  }
  // Additional outbound calls would be listed here
]

Step 6: Get Detailed Outbound Call

To retrieve comprehensive information about a specific outbound call, including all attempts and outcomes:

curl -X GET https://api.micovoice.com/api/v1/outbound_calls/d26a3041-1743-413f-9722-04ac1f612960 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

What's Included in the Response

The detailed response contains complete information about the call:

1. Basic Information

   • UID, external ID, creation and update timestamps
   • Current status and progress
   • Test call flag and retry information

2. Contact Information (outbound_call_info)

   • All contact details (name, phone, email)
   • Any custom parameters provided when creating the call

3. Call Attempts (outbound_call_attempts)

   • History of each attempt to reach the contact
   • Start, answer, and end timestamps
   • Duration of connected calls
   • Status and outcome of each attempt
   • Any error details if applicable

4. Notifications (outbound_calls_notifications)

   • Status of any notifications sent related to this call
   • Message counts and delivery status

Expected Response (Status: 200)

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "completed",
  "progress": "answered",
  "is_test_call": false,
  "number_call_retries": 0,
  "cooldown_until": null,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:15:30Z",
  "outbound_call_info": {
    "phone_number": "5551234567",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "phonetic_full_name": "John Doe",
    "phonetic_first_name": "John",
    "phonetic_last_name": "Doe",
    "email": "john.doe@example.com",
    "custom_parameters": {
      "account_id": "A12345",
      "appointment_time": "3:30 PM"
    }
  },
  "outbound_call_attempts": [
    {
      "uid": "8ae20b12-ebaa-47f4-822f-2b7e3f388f49",
      "status": "hangup",
      "started_at": "2025-04-16T12:12:00Z",
      "answered_at": "2025-04-16T12:12:15Z",
      "ended_at": "2025-04-16T12:15:30Z",
      "duration": 195,
      "created_at": "2025-04-16T12:11:00Z",
      "updated_at": "2025-04-16T12:15:30Z",
      "error_details": null,
      "outbound_call_attempts_outcomes": [
        {
          "call_outcome": {
            "uid": "6a938cdf-9b4b-4e8c-940b-05af78ea8666",
            "name": "APPOINTMENT_CONFIRMED"
          },
          "created_at": "2025-04-16T12:15:00Z"
        }
      ]
    }
  ],
  "outbound_calls_notifications": [
    {
      "uid": "8ae20b12-ebaa-47f4-822f-2b7e3f388f49",
      "status": "delivered",
      "message_count": 1
    }
  ]
}