---
title: "Create a provider call"
method: POST
path: "/providercalls"
tags: ["ProviderCall"]
---

# Create a provider call

`POST /providercalls`

Admin-triggered outbound call placed through the specified provider. The
handler bypasses normal dialroute selection (via server-side metadata) and
preserves the admin-supplied source number verbatim so provider carrier
allowlists accept it. The created Call(s)/Groupcall(s) are persisted and
their IDs are returned on the `ProviderCall` record. Admin-only
(PermissionProjectSuperAdmin).

## Request body

- object
  - `provider_id` string, uuid, required — The provider to force the call through. Obtained from the `GET /providers` response.
  - `flow_id` string, uuid — Optional flow to execute after the destination answers. Obtained from the `GET /flows` response.
  - `actions` FlowManagerAction[] — Optional inline actions. Used when no `flow_id` is supplied.
    - `id` string, uuid, required — The unique identifier of this action within the flow.
    - `next_id` string, uuid — The identifier of the next action to execute. References an action `id` within the same flow's `actions` array. Null if this is the last action.
    - `type` 'ai_talk' | 'ai_summary' | 'amd' | 'answer' | 'beep' | 'branch' | 'call' | 'condition_call_digits' | 'condition_call_status' | 'condition_datetime' | 'condition_variable' | 'confbridge_join' | 'conference_join' | 'connect' | 'conversation_send' | 'digits_receive' | 'digits_send' | 'echo' | 'email_send' | 'external_media_start' | 'external_media_stop' | 'fetch' | 'fetch_flow' | 'goto' | 'hangup' | 'message_send' | 'mute' | 'play' | 'queue_join' | 'recording_start' | 'recording_stop' | 'sleep' | 'stop' | 'stream_echo' | 'talk' | 'transcribe_start' | 'transcribe_stop' | 'transcribe_recording' | 'variable_set' | 'webhook_send', required — Type of the action.
    - `option` object — Additional options based on the `type` field. - For `FlowManagerActionTypeAISummary`: see `FlowManagerActionOptionAISummary` - For `FlowManagerActionTypeAITalk`: see `FlowManagerActionOptionAITalk` - For `FlowManagerActionTypeAMD`: see `FlowManagerActionOptionAMD` - For `FlowManagerActionTypeAnswer`: see FlowManagerActionOptionAnswer - For `FlowManagerActionTypeBeep`: see FlowManagerActionOptionBeep - For `FlowManagerActionTypeBranch`: see FlowManagerActionOptionBranch - For `FlowManagerActionTypeCall`: see FlowManagerActionOptionCall - For `FlowManagerActionTypeConfbridgeJoin`: see FlowManagerActionOptionConfbridgeJoin - For `FlowManagerActionTypeConferenceJoin`: see FlowManagerActionOptionConferenceJoin - For `FlowManagerActionTypeConnect`: see FlowManagerActionOptionConnect - For `FlowManagerActionTypeConversationSend`: see FlowManagerActionOptionConversationSend - For `FlowManagerActionTypeDigitsReceive`: see FlowManagerActionOptionDigitsReceive - For `FlowManagerActionTypeDigitsSend`: see FlowManagerActionOptionDigitsSend - For `FlowManagerActionTypeEcho`: see FlowManagerActionOptionEcho - For `FlowManagerActionTypeEmailSend`: see FlowManagerActionOptionEmailSend - For `FlowManagerActionTypeExternalMediaStart`: see FlowManagerActionOptionExternalMediaStart - For `FlowManagerActionTypeExternalMediaStop`: see FlowManagerActionOptionExternalMediaStop - For `FlowManagerActionTypeFetch`: see FlowManagerActionOptionFetch - For `FlowManagerActionTypeFetchFlow`: see FlowManagerActionOptionFetchFlow - For `FlowManagerActionTypeGoto`: see FlowManagerActionOptionGoto - For `FlowManagerActionTypeHangup`: see FlowManagerActionOptionHangup - For `FlowManagerActionTypeMessageSend`: see FlowManagerActionOptionMessageSend - For `FlowManagerActionTypePlay`: see FlowManagerActionOptionPlay - For `FlowManagerActionTypeQueueJoin`: see FlowManagerActionOptionQueueJoin - For `FlowManagerActionTypeRecordingStart`: see FlowManagerActionOptionRecordingStart - For `FlowManagerActionTypeRecordingStop`: see FlowManagerActionOptionRecordingStop - For `FlowManagerActionTypeSleep`: see FlowManagerActionOptionSleep - For `FlowManagerActionTypeStreamEcho`: see FlowManagerActionOptionStreamEcho - For `FlowManagerActionTypeTalk`: see FlowManagerActionOptionTalk - For `FlowManagerActionTypeTranscribeStart`: see FlowManagerActionOptionTranscribeStart - For `FlowManagerActionTypeTranscribeStop`: see FlowManagerActionOptionTranscribeStop - For `FlowManagerActionTypeTranscribeRecording`: see FlowManagerActionOptionTranscribeRecording - For `FlowManagerActionTypeVariableSet`: see FlowManagerActionOptionVariableSet - For `FlowManagerActionTypeWebhookSend`: see FlowManagerActionOptionWebhookSend - ...
    - `tm_execute` string, date-time — Timestamp when this action was executed.
  - `source` CommonAddress — Contains source or destination detail info.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `destinations` CommonAddress[], required — Dial targets. One Call/Groupcall is created per destination.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `anonymous` 'yes' | 'no' | 'auto' — Controls the anonymous caller-ID flag. Defaults to `auto`.

## Response `200`

The created providercall record.

- RouteManagerProviderCall — An admin-triggered call placed through a specific provider. Captures the admin's original request info plus the IDs of calls/groupcalls that were created by the underlying call-creation step. Admin polls the referenced call IDs via `GET /calls/{id}` for per-call state.
  - `id` string, uuid — The unique identifier of the providercall. Returned from the `POST /providercalls` response.
  - `customer_id` string, uuid — The customer the record is attributed to. Set server-side from the authenticated admin's own customer.
  - `provider_id` string, uuid — The provider the call was forced through. Returned from the `GET /providers` response.
  - `flow_id` string, uuid — The flow executed after the destination answered. `00000000-0000-0000-0000-000000000000` when no flow was attached.
  - `source` CommonAddress — Contains source or destination detail info.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `destinations` CommonAddress[] — The admin-supplied dial targets. One Call or Groupcall is created per destination, depending on destination type.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session' — Type of address.
    - `target` string — The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string — Address's name.
    - `name` string — Optional label for this address.
    - `detail` string — Additional notes about this address.
  - `anonymous` 'yes' | 'no' | 'auto' — The anonymous caller-ID option requested. `auto` (default) resolves the same as `no` today.
  - `call_ids` string[] — IDs of the Call records that the call-creation step produced. Returned from the `POST /calls` response and retrievable via `GET /calls/{id}`.
  - `groupcall_ids` string[] — IDs of any Groupcall records produced when a destination resolved to a group-type address. Retrievable via `GET /groupcalls/{id}`.
  - `tm_create` string, date-time — The creation timestamp.
  - `tm_update` string, date-time — The last update timestamp.
  - `tm_delete` string, date-time — The deletion timestamp. `null` until soft-deleted.

## Other responses

- `400` — Invalid request (INVALID_ARGUMENT).
- `401` — Authentication required (UNAUTHENTICATED).
- `403` — Insufficient permission (PERMISSION_DENIED).
- `500` — Internal error (INTERNAL).

---

[API](https://skmtc.net/voipbin/apis/voipbin-api.md) · [All operations](https://skmtc.net/voipbin/apis/voipbin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voipbin/voipbin-api/revisions/79e779080bcc/schema)