Skip to main content

Outbound Calls

Endpoint​

POST /v1/calls

Method​

POST

Auth requirement​

Bearer application API key. application_id in the request struct is ignored; the authenticated application is used.

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​

{
  "from": "+15551230001",
  "to": "+15551230002",
  "metadata": {
    "campaign": "dev"
  },
  "record": true
}

from and to are required E.164 strings. metadata is optional. record=true stores metadata.record=true.

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, rate_not_found, or no_active_trunk. 401 unauthorized. 402 insufficient_balance. 403 spend-control rejection. 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.local/v1/calls \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "from": "+15551230001",
  "to": "+15551230002",
  "record": true
}
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.

Integration guidance

Use this page as part of a complete MiniVoice integration, not as an isolated reference. Start by wiring the smallest possible version in a test application, then add business logic after you can reproduce the behaviour reliably. Keep the MiniVoice call ID in your own records, because that ID is the easiest way to connect API responses, webhook events, recordings, AI results, and billing details.

When you build the workflow, separate caller experience from backend processing. The caller should hear short prompts and reach a destination quickly. Longer work, such as updating a CRM or creating a support ticket, should happen after your webhook endpoint has accepted the event. This keeps the voice flow responsive and makes retry handling easier.

For manual testing, use one known DID, one known destination number, and one webhook receiver where you can inspect request headers and bodies. Run the same test at least three times: one normal path, one invalid input path, and one timeout or no-answer path. Save the examples that worked as fixtures for future regression tests.

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'
{
  "from": "+15551230001",
  "to": "+15551230002",
  "record": true
}
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.