---
title: "Outbound"
method: POST
path: "/v1/voice/outbound"
tags: ["voice"]
---

# Outbound

`POST /v1/voice/outbound`

## Request body

- OutboundRequest
  - `from_phone_number_id` string, uuid, required — Org-scoped phone number id to dial FROM. Must have an outbound_call agent attached so a SIP outbound trunk has been provisioned.
  - `to_phone_number` string, required — E.164 phone number to dial, e.g. +15555550123
  - `agent_id` string, uuid, nullable — Optional: dial AS this specific agent. Must already be attached to the from-number as an outbound_call binding. Provide this XOR `team_id`; omit both to let the backend pick a bound dialer at random (load-balanced across the fleet).
  - `team_id` string, uuid, nullable — Optional: dial AS this specific team (its default member answers). Must already be attached to the from-number as an outbound_call binding. Provide this XOR `agent_id`; omit both for random pick.
  - `agent_revision_id` string, uuid, nullable — Optional: run THIS call on a specific published revision of `agent_id` instead of the revision pinned on the number's binding (pin-at-bind). Use to canary a newly published revision on live traffic before re-binding the number. Only valid alongside `agent_id`; the revision must belong to that agent and be published — drafts stay undialerable on live numbers (use /web-call for draft testing). Omitted → the binding's pinned revision, exactly as before. The call's context_variables are validated against the SAME revision that runs.
  - `context_variables` object, nullable — Optional seed values for the bound agent's typed context variables, applied once at session bootstrap. Each key must be a variable declared on the agent or one of its bound workflows; values are coerced against the variable's type/enum. An unknown key or an uncoercible value is rejected (422). System vars are frozen on-file; derived seeds satisfy the collection gate. Only honored for single-agent bindings in v1 (ignored for team-bound dialers).
  - `idempotency_key` string, nullable — Client-supplied dedup key; a retry of a still-queued call returns the same queued envelope (no second dial). Alphanumeric + dash/underscore, 1-120 chars.
  - `instant` boolean — Test/instant dispatch: bypass the calling-hours window and dispatch immediately. Rate-limited separately; concurrency limits still apply.
  - `expires_in_seconds` integer, nullable — Override the org's queued-call expiry for THIS call. Seconds from enqueue after which the call is expired if still waiting in the queue (never dialed). `0` disables expiry for this call even if the org has a default; omit (null) to use the org's `call_expiry` setting. Max 30 days.
  - `override_pause` boolean — Bypass the outbound pause gate and dispatch inline. Valid ONLY with `instant=True` (enforced by the schema validator). Requires the `communication:manage` permission — enforced in the router, not here. No effect on the queued (non-instant) path.

## Response `200`

Successful Response

- OutboundResponse
  - `queued` boolean
  - `room_name` string, nullable
  - `dispatch_id` string, nullable
  - `agent_name` string, required
  - `session_id` string, uuid, required
  - `agent_revision_id` string, uuid, nullable
  - `agent_revision_name` string, nullable
  - `revision_source` 'override' | 'pin' | 'active_fallback', nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/revisions/5a5597ebb2d6/schema)