Skip to main content

Outbound Calls

Endpoint​

POST /v1/calls

Method​

POST

Auth requirement​

Bearer application API key.

Business example: send an appointment confirmation or payment reminder call, then track the call through call.created, call.answered, and call.completed webhooks.

Request body​

{
  "application_id": "app_123",
  "from": "+15551230001",
  "to": "+15551230002",
  "record": true,
  "metadata": {
    "campaign": "appointment-confirmation"
  }
}

application_id, from, and to are required. from and to must be E.164 strings. record is optional and controls whether the call should be recorded. metadata is optional and can be used to store campaign, CRM, or workflow context.

Application validation​

MiniVoice validates the requested application before creating the outbound call:

ValidationFailure behavior
application_id must be present and use a valid application ID format.Invalid format returns 400 invalid_request.
The application must exist.Unknown application returns 404 not_found.
The application must belong to the authenticated customer.Cross-customer application IDs return 403 forbidden.
The application must be active.Inactive applications return 400 invalid_request.

The API key authenticates the customer request. The application_id selects which MiniVoice application owns the call flow, including the answer_url, webhook_url, webhook_secret, and related routing behavior for this outbound call.

Response body​

{
  "id": "call_20260529T120000.000000000",
  "status": "dialing",
  "direction": "outbound",
  "from": "+15551230001",
  "to": "+15551230002",
  "application_id": "app_123",
  "customer_id": "cust_123",
  "provider_call_id": "uuid",
  "answer_url": "https://example.test/answer",
  "metadata": {
    "record": true
  },
  "created_at": "2026-05-29T12:00:00Z",
  "route_mode": "webhook",
  "routing_target": "app_123",
  "dialing_at": "2026-05-29T12:00:01Z"
}

Errors​

400 invalid_json, invalid_request, invalid application_id format, inactive application, rate_not_found, or no_active_trunk. 401 unauthorized. 402 insufficient_balance. 403 forbidden application or spend-control rejection. 404 application not found. 429 cps_limit_reached or concurrent_call_limit_reached. 500 reservation/rate/trunk errors. 502 originate_failed.

Common Error Example​

{
  "error": {
    "code": "insufficient_balance",
    "message": "balance is too low to create call"
  }
}

Example curl​

curl -sS -X POST https://api.minivoice.eu/v1/calls \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "application_id": "app_123",
  "from": "+15551230001",
  "to": "+15551230002",
  "record": true,
  "metadata": {
    "campaign": "appointment-confirmation"
  }
}
JSON

Test procedure​

Ensure the customer has balance, an active outbound trunk, and a matching active rate. Create the call and verify call.created, call.answered or call.failed, and terminal call webhooks.

Copy/Paste Examples​

Real Request​

curl -sS -X POST https://api.minivoice.eu/v1/calls \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "application_id": "app_123",
  "from": "+15551230001",
  "to": "+15551230002",
  "record": true,
  "metadata": {
    "campaign": "appointment-confirmation"
  }
}
JSON

Real Response​

{
  "id": "call_123",
  "status": "dialing",
  "direction": "outbound",
  "from": "+15551230001",
  "to": "+15551230002",
  "application_id": "app_123",
  "customer_id": "cust_123",
  "created_at": "2026-05-29T12:00:00Z"
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Create appointment confirmation, payment reminder, or sales follow-up calls and correlate each accepted call with webhooks.

Common Failure Case​

{
  "error": {
    "code": "insufficient_balance",
    "message": "balance is too low to create call"
  }
}

Use the error code for branching and log the full response body while testing.