> ## Documentation Index > Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt > Use this file to discover all available pages before exploring further. # Dispatch a call from this assistant > Dial a customer as this assistant. `dispatched` means the carrier accepted the call and it is about to ring, not that anyone picked up. The returned `callId` is also the `sessionId`: [poll the session status](/api-reference/sessions-%26-call-records/get-a-sessions-status) for ringing, answer, and outcome. The response's `externalRef` is the telephony reference to quote in support tickets. Send an `Idempotency-Key` on retries so a timed-out request can't place a second call; the key also makes the `callId` start with `api_` instead of being a fresh UUID. ## OpenAPI ````yaml /voice-agents/api-reference/openapi.yaml post /realtime-assistants/{realtimeAssistantId}/call openapi: 3.1.0 info: title: UpliftAI Voice Agents API version: '1.0' description: >- Build voice assistants, start conversations on the web or the phone, run calling campaigns, and receive outcomes by webhook. All endpoints take a bearer API key unless noted otherwise. servers: - url: https://api.upliftai.org/v1 security: - apiKey: [] tags: - name: Assistants - name: Authoring an assistant - name: Starting a conversation - name: Sessions & call records - name: Campaigns - name: Campaign outcomes - name: Contacts - name: Google Sheet sources - name: Integrations & delivery health paths: /realtime-assistants/{realtimeAssistantId}/call: post: tags: - Starting a conversation summary: Dispatch a call from this assistant description: >- Dial a customer as this assistant. `dispatched` means the carrier accepted the call and it is about to ring, not that anyone picked up. The returned `callId` is also the `sessionId`: [poll the session status](/api-reference/sessions-%26-call-records/get-a-sessions-status) for ringing, answer, and outcome. The response's `externalRef` is the telephony reference to quote in support tickets. Send an `Idempotency-Key` on retries so a timed-out request can't place a second call; the key also makes the `callId` start with `api_` instead of being a fresh UUID. operationId: createAssistantCall parameters: - name: realtimeAssistantId in: path required: true schema: type: string format: uuid example: ee42ac3b-xxxx-xxxx-xxxx-xxxxxxxxxxxx - name: Idempotency-Key in: header required: false description: >- Caller-chosen key that fixes the call id, so a retried request cannot dial twice. Scoped to this assistant. schema: type: string maxLength: 256 example: shifa-reminder-2026-08-18-ayesha-siddiqi requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssistantCallRequest' example: toNumber: '+923001234567' variables: patientName: عائشہ صدیقی doctorName: ڈاکٹر عمران شیخ appointmentTime: کل صبح 11 بجے additionalInstructions: >- مریضہ کا نام عائشہ صدیقی ہے، اپائنٹمنٹ کل صبح 11 بجے ڈاکٹر عمران شیخ کے ساتھ ہے۔ اگر وہ کل نہ آ سکیں تو جمعرات دوپہر 3 بجے کا متبادل وقت پیش کریں۔ responses: '200': description: The call is dialing. content: application/json: schema: $ref: '#/components/schemas/AssistantCallResponse' example: callId: 7c3f9a02-xxxx-xxxx-xxxx-xxxxxxxxxxxx externalRef: AD_xxxxxxxxxxxx status: dispatched '400': description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: badNumber: summary: toNumber is neither E.164 nor a local leading-zero number value: message: - >- toNumber must be E.164 (e.g., +14155551234) or local format (e.g., 03001234567) error: Bad Request statusCode: 400 '401': $ref: '#/components/responses/Unauthorized' '402': description: The organization is out of credits; nothing was dialed. content: application/json: schema: type: object properties: message: type: string statusCode: type: integer example: message: Insufficient credits to start a realtime session statusCode: 402 '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- Nothing was dialed. On `duplicate_in_flight` poll the returned `callId` instead of retrying; on `number_busy` retry once the live call ends. content: application/json: schema: $ref: '#/components/schemas/CallConflict' example: error: duplicate_in_flight callId: 7c3f9a02-xxxx-xxxx-xxxx-xxxxxxxxxxxx '429': description: >- The organization is at its concurrent outbound call limit, every outbound caller ID is at line capacity, or your project exceeded its request rate limit (150 per minute by default). Nothing was dialed. content: application/json: schema: type: object properties: message: type: string statusCode: type: integer example: message: Organization concurrent outbound call limit reached statusCode: 429 '503': $ref: '#/components/responses/VersionNotReady' components: schemas: AssistantCallRequest: type: object properties: toNumber: type: string pattern: ^(\+[1-9]\d{1,14}|0\d{8,14})$ description: >- Number to dial, either E.164 (`+923001234567`) or a local leading-zero number (`03001234567`). example: '+923001234567' fromNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: >- Caller ID to dial from, E.164. Only the format is checked, so a number your organization doesn't own dispatches and then fails at the carrier. Omit to let the platform allocate one. example: '+924232175000' variables: type: object additionalProperties: true propertyNames: maxLength: 64 description: >- Facts about this caller, like `crop: cotton`. They reach the model as a [caller record](/voice-agents/personalization/variables) after the prompt, and come back verbatim on every session read. String, number and boolean values go to the model. A nested object stays on the record only. Keys up to 64 characters, and the serialized object must stay under 3000 characters. additionalInstructions: type: string maxLength: 2000 description: Appended to the assistant's instructions for this call only. assistantVersion: $ref: '#/components/schemas/AssistantVersionSelector' required: - toNumber AssistantCallResponse: type: object properties: callId: type: string format: uuid description: >- Id of this call, and the `sessionId` in every session and call record. externalRef: type: string description: >- Telephony-provider dispatch reference, useful when raising support tickets. status: type: string const: dispatched Error: type: object properties: message: description: >- One message per failed field for validation errors, a single string otherwise. oneOf: - type: string - type: array items: type: string error: type: string statusCode: type: integer CallConflict: type: object properties: error: type: string enum: - duplicate_in_flight - number_busy description: >- `duplicate_in_flight` — this `Idempotency-Key` already placed a call. `number_busy` — another live call already has that callee number, whoever started it. callId: type: string description: >- The id this request resolved to: the existing call on `duplicate_in_flight`, the refused attempt on `number_busy`. AssistantVersionSelector: oneOf: - type: string enum: - prod - draft - type: integer minimum: 1 default: prod description: >- Which version of the assistant runs. `prod` is the published version, or the draft before the first publish. `draft` tries unpublished edits on a real conversation. A number runs that exact published version, and one never published is a 404. Send a number as a JSON number, not a string. example: draft responses: Unauthorized: description: A bearer key was sent but is not recognized. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: invalid authorization error: Unauthorized statusCode: 401 Forbidden: description: No API key sent, or the key lacks permission for this resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Forbidden resource error: Forbidden statusCode: 403 NotFound: description: No such resource in the API key's project. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: 'Realtime assistant not found: 00000000-0000-4000-8000-000000000000' error: Not Found statusCode: 404 VersionNotReady: description: >- The published version hasn't reached this region yet, usually right after a publish. No session or call was started. Retry in a few seconds. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- Published version 14 of assistant 0f4a91d3-xxxx-xxxx-xxxx-xxxxxxxxxxxx is not readable yet statusCode: 503 securitySchemes: apiKey: type: http scheme: bearer description: Project API key (`sk_api_…`). ````