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

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",
    "type": "scheduled_call"
  }'

Expected Response (Status: 201)

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

Note: is_enabled cannot be set on creation - the request is rejected with a 400 if you send it. New campaigns are always returned with is_enabled: false. direction defaults to outbound when omitted.

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

Step 2: Create a Schedule

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": "96c36c45-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/96c36c45-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"
  }'

Call Creation Details

• Datetime values in custom_parameters must use ISO 8601 with a timezone (e.g. 2025-10-01T08:03:00+09:00 or 2025-10-01T08:03:00Z).

Expected Response (Status: 201)

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "pending",
  "progress": "in_queue",
  "is_test_call": false,
  "cooldown_until": null,
  "delay": null,
  "priority": null,
  "retry_intervals": [300, 300, 300],
  "attempts_remaining": 4,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:10:00Z",
  "outbound_call_info": {
    "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",
    "event_date_time": null,
    "external_id": "CUST-123",
    "custom_parameters": {
      "1024": "A12345",
      "1025": "3:30 PM"
    }
  },
  "outbound_call_attempts": [],
  "call_notifications": []
}

Note the following about this response:

• retry_intervals and attempts_remaining are derived from the schedule: three retry intervals means four attempts in total.
• On this endpoint custom_parameters keys are the numeric IDs of your call flow's custom parameters, not their names. The GET endpoints in Step 5 and Step 6 return the same values keyed by name.

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/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "outbound_calls": [
      {
        "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": {
          "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

Expected Response (Status: 201)

The bulk endpoint returns only the UIDs of the created calls, in the same order as the request:

{
  "data": [
    "d26a3041-1743-413f-9722-04ac1f612960",
    "7f93b218-5c22-476a-9321-e9712fdcb490"
  ]
}

Use GET /api/v1/outbound_calls/{uid} (Step 6) if you need the full representation of any of the created calls.

Partial Failures (Status: 400)

Bulk creation is all-or-nothing: if any entry is invalid, no calls are created and the request fails with a 400. Each error points at the offending entry by its index in the outbound_calls array:

{
  "title": "Invalid request",
  "detail": "One or more of the request parameters is invalid",
  "errors": [
    {
      "title": "Invalid value",
      "source": {
        "pointer": "/outbound_calls/1/phone_number"
      },
      "detail": "The phone number is invalid. Please use the correct format (e.g. 08012345678)"
    }
  ]
}

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/96c36c45-b95c-4ab1-8bb1-6e6e1283c950 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "is_enabled": true
  }'

Expected Response (Status: 200)

{
  "uid": "96c36c45-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/96c36c45-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
status	Filter by call status	status=pending,completed
progress	Filter by call progress	progress=answered,unanswered
source	Filter by how the call was created	source=api,quick_call_api
attempt_status	Filter by call attempt status	attempt_status=no_answer,busy
outcome	Filter by call outcome name	outcome=Transfer%20to%20agent
external_id	Filter by your reference ID	external_id=CUST-123
is_test_call	Include/exclude test calls	is_test_call=true
full_name	Filter by contact's full name	full_name=john%20doe
first_name	Filter by contact's first name	first_name=john
last_name	Filter by contact's last name	last_name=doe
phonetic_full_name	Filter by phonetic full name	phonetic_full_name=john%20doe
phonetic_first_name	Filter by phonetic first name	phonetic_first_name=john
phonetic_last_name	Filter by phonetic last name	phonetic_last_name=doe
email	Filter by contact's email	email=john.doe@example.com
updated_after	Only calls updated at or after a time	updated_after=2026-08-01T00:00:00Z

Notes on how filters match:

• status, progress, source, and attempt_status accept a comma-delimited list of values, and a call matches if it matches any value in the list.
• Name and email filters match on a case-insensitive substring, so last_name=do also matches Doe.
• external_id and outcome must match the stored value exactly.
• updated_after takes an RFC 3339 timestamp and is inclusive (updated_at >= value). Using it switches the result order to updated_at ascending, so a call that changes while you are paging is re-read rather than skipped - which makes it the parameter to use for incremental sync.
• Any query parameter that is not listed here is rejected with a 400 and an Unexpected field: <name> error.

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/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page=2&page_size=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Expected Response (Status: 200)

The calls are returned under data, alongside a pagination object. next and prev are null when there is no such page.

{
  "data": [
    {
      "uid": "d26a3041-1743-413f-9722-04ac1f612960",
      "external_id": "CUST-123",
      "status": "pending",
      "progress": "in_queue",
      "is_test_call": false,
      "cooldown_until": null,
      "delay": null,
      "priority": null,
      "retry_intervals": [300, 300, 300],
      "attempts_remaining": 4,
      "created_at": "2025-04-16T12:10:00Z",
      "updated_at": "2025-04-16T12:10:00Z",
      "outbound_call_info": {
        "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",
        "event_date_time": null,
        "external_id": "CUST-123",
        "custom_parameters": {
          "account_id": "A12345",
          "appointment_time": "3:30 PM"
        }
      },
      "outbound_call_attempts": [],
      "call_notifications": []
    }
  ],
  "pagination": {
    "total_count": 62,
    "total_pages": 3,
    "page_size": 25,
    "current_page": 2,
    "links": {
      "self": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=2",
      "next": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=3",
      "prev": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=1",
      "last": "https://api.micovoice.com/api/v1/schedules/96c36c45-b95c-4ab1-8bb1-6e6e1283c950/outbound_calls?status=pending&page_size=25&page=3"
    }
  }
}

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 of each attempt, plus the outcomes (call_outcomes) and variables collected during it (call_attempts_variables)
   • Transfer details when the call was transferred: transfer_started_at, transfer_answered_at, and the transfer_destination it was transferred to. All three are null when the call was never transferred.
   • Any error details if applicable

4. Notifications (call_notifications)

   • Status of any notifications sent related to this call
   • Message counts and delivery status
   • outbound_calls_notifications is deprecated - use call_notifications.

Expected Response (Status: 200)

{
  "uid": "d26a3041-1743-413f-9722-04ac1f612960",
  "external_id": "CUST-123",
  "status": "completed",
  "progress": "answered",
  "is_test_call": false,
  "cooldown_until": null,
  "delay": null,
  "priority": null,
  "retry_intervals": [300, 300, 300],
  "attempts_remaining": 0,
  "created_at": "2025-04-16T12:10:00Z",
  "updated_at": "2025-04-16T12:15:30Z",
  "outbound_call_info": {
    "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",
    "event_date_time": null,
    "external_id": "CUST-123",
    "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,
      "transfer_started_at": null,
      "transfer_answered_at": null,
      "transfer_destination": null,
      "call_outcomes": [
        {
          "uid": "6a938cdf-9b4b-4e8c-940b-05af78ea8666",
          "name": "APPOINTMENT_CONFIRMED",
          "created_at": "2025-04-16T12:15:00Z"
        }
      ],
      "call_attempts_variables": [
        {
          "uid": "e713afb6-b877-4c28-9809-07c0d93b6b31",
          "name": "Appointment time",
          "value": "3:30 PM",
          "status": "confirmed",
          "created_at": "2025-04-16T12:14:20Z"
        }
      ]
    }
  ],
  "call_notifications": [
    {
      "uid": "3f2a91d4-5c8e-4b17-9a63-0d1e7c45b2aa",
      "status": "delivered",
      "message_count": 1,
      "delivered_at": "2025-04-16T12:15:40Z"
    }
  ]
}