> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Dispatch an outbound call > Has the agent's published version phone `to`. The request returns as soon as dialling starts (`status: dialing`); whether the callee answers is not known yet. Follow the call through the returned `conversationId` (`GET .../conversations/{id}`), or pass `on_call_ended_url` to receive the finished call record when it ends. Caller ID: `from`, when given, must be a phone number registered in this project with outbound calling enabled; otherwise the call is refused (422) rather than placed from a different number. Without `from`, the agent's own outbound number is used, then a number routed to the agent, then the platform default. Needs the publish permission, which organization API keys carry. The agent must have been published at least once, and must be a voice agent (a Voice Assist agent cannot place calls). ## OpenAPI ````yaml /api-reference/voice-openapi.json post /v1/projects/{projectId}/agents/{id}/dispatch-call openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: Voice agents, outbound calls, conversations, campaigns, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. paths: /v1/projects/{projectId}/agents/{id}/dispatch-call: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/AgentId' post: tags: - Outbound calls summary: Dispatch an outbound call description: >- Has the agent's published version phone `to`. The request returns as soon as dialling starts (`status: dialing`); whether the callee answers is not known yet. Follow the call through the returned `conversationId` (`GET .../conversations/{id}`), or pass `on_call_ended_url` to receive the finished call record when it ends. Caller ID: `from`, when given, must be a phone number registered in this project with outbound calling enabled; otherwise the call is refused (422) rather than placed from a different number. Without `from`, the agent's own outbound number is used, then a number routed to the agent, then the platform default. Needs the publish permission, which organization API keys carry. The agent must have been published at least once, and must be a voice agent (a Voice Assist agent cannot place calls). operationId: dispatchCall requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DispatchCallRequest' example: to: '+14155550123' from: '+14155550100' on_call_ended_url: https://hooks.example.com/calls/ended responses: '200': description: >- Dialling has started. The outcome of the call is reported asynchronously. content: application/json: schema: $ref: '#/components/schemas/DispatchCallResponse' example: callId: 6f1a2b3c-4d5e-4f60-8172-839405a6b7c8 roomName: dispatch-1a2b3c4d status: dialing conversationId: 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091 '400': description: >- `to` or `from` is not a valid phone number, or the agent's type is no longer supported (`code: AGENT_TYPE_NOT_SUPPORTED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid target phone number '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: publish_capability_required code: PUBLISH_CAPABILITY_REQUIRED '404': description: The project or the agent does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Agent not found '409': description: >- The agent has never been published (`code: AGENT_NOT_PUBLISHED`). Nothing was dialled. Publish the agent first. content: application/json: schema: $ref: '#/components/schemas/AgentNotPublishedError' example: error: >- Agent "Billing assistant" is not published yet — publish it before it can take calls code: AGENT_NOT_PUBLISHED agent_id: 3f0c6a52-8d7e-4b8a-9a43-0f2b5c1e9d11 '422': description: >- The body is malformed (for example `to` is missing, or `on_call_ended_url` is not an `https://` URL; `issues` locates each problem), `from` is not an outbound-enabled number in this project (the body carries the `from` value), or the agent is a Voice Assist agent (`code: AGENT_TYPE_NOT_DISPATCHABLE`). Nothing was dialled. content: application/json: schema: $ref: '#/components/schemas/Error' examples: malformedBody: summary: Malformed body value: error: 'to: Required' issues: - path: to code: invalid_type message: Required fromNotOutbound: summary: Caller id not enabled for outbound calls value: error: >- from number is not an outbound-enabled number in this project from: '+14155550100' '503': description: >- No outbound calling route is configured for the project (no outbound number or trunk, and no platform default caller ID). This response carries only `message`. content: application/json: schema: type: object properties: message: type: string error: type: string example: message: SIP outbound not configured components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id AgentId: name: id in: path required: true schema: type: string description: Agent id schemas: DispatchCallRequest: type: object required: - to properties: to: type: string minLength: 1 description: >- The number to call, in international format (E.164), for example `+14155550123`. from: type: string description: >- Caller ID to present. Must be a number registered in this project with outbound calling enabled, or the call is refused with 422. Omit it to use the agent's outbound number. on_call_ended_url: type: string format: uri description: >- An `https` URL that receives a `POST` with the finished call record (vCon JSON) when the call ends. DispatchCallResponse: type: object required: - callId - roomName - status properties: callId: type: string roomName: type: string description: The media room the call runs in. status: type: string enum: - dialing conversationId: type: string description: >- The conversation that will hold the call's transcript, recording and summary. Read it with `GET .../conversations/{id}`. Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place or take a call; the body carries `agent_type` and `agent_id`), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503) and `REGION_PROFILE_CONFLICT` (503). AgentNotPublishedError: type: object description: >- Refusal: the agent named where an agent is assigned to take or place calls (dispatch rules, campaigns and their items, outbound caller id, dispatch-call) was never published, so no call could run it. Refused before any side effect; an assignment saved earlier stays. Match on `code`. required: - error - code - agent_id properties: error: type: string example: >- Agent "Billing bot" is not published yet — publish it before it can take calls code: type: string enum: - AGENT_NOT_PUBLISHED agent_id: type: string responses: Unauthorized: description: No credential was sent, or the API key is invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.