> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialtu.com/llms.txt > Use this file to discover all available pages before exploring further. # Schedule a call > Queue an outbound AI call to a phone number, either right away or at `start_time`. The call is placed by the voice agent identified by `agent_id`; the engine (Aurora or Solara) is detected from the agent, so the same request works for both. The response confirms the queued call — the call itself runs asynchronously. Pass `client_id` to attach the call to an existing contact, or use `request_data` / `dynamic_data` to inject values the agent's prompt refers to. Retries on no-answer are configured with the `max_retries` / `retry_*` fields. ## OpenAPI ````yaml POST /api/v2/public/calls/schedule openapi: 3.1.0 info: title: Dialtu Public API version: '2.0' description: >- Programmatic access to your Dialtu account: schedule AI voice calls, create contacts, push leads into Salesflow pipelines, book calendar appointments and read WhatsApp conversation history. Every request is authenticated with an API key created in the dashboard under **Settings → API Keys**, sent as `Authorization: Bearer pk_...`. servers: - url: https://api.dialtu.com description: Production - url: https://api.stg.dialtu.com description: Staging security: - ApiKeyBearer: [] tags: - name: Calls description: Schedule outbound AI voice calls. - name: Clients description: Create contacts in your account. - name: Salesflow description: Push leads into a pipeline through an API input node. - name: Salesflow pipelines description: Read a pipeline's stages and add, move or remove clients. - name: Calendar description: Check bookable capacity, book appointments and manage waiting lists. - name: WhatsApp description: Read-only conversation history and transcripts. paths: /api/v2/public/calls/schedule: post: tags: - Calls summary: Schedule a call description: >- Queue an outbound AI call to a phone number, either right away or at `start_time`. The call is placed by the voice agent identified by `agent_id`; the engine (Aurora or Solara) is detected from the agent, so the same request works for both. The response confirms the queued call — the call itself runs asynchronously. Pass `client_id` to attach the call to an existing contact, or use `request_data` / `dynamic_data` to inject values the agent's prompt refers to. Retries on no-answer are configured with the `max_retries` / `retry_*` fields. operationId: scheduleCall parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SendCallInputSchemaV2' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicScheduleCallResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/PublicCallErrorResponse' '401': description: Missing, malformed or revoked API key. content: application/json: schema: $ref: '#/components/schemas/DetailErrorResponse' examples: missing_header: summary: No Authorization header value: detail: Unauthorized invalid_key: summary: Unknown or revoked key value: detail: Invalid or expired API key. Please check your credentials. '422': description: The request did not match the documented schema. content: application/json: schema: $ref: '#/components/schemas/RequestValidationError' example: detail: - type: missing loc: - body - payload - phone_number msg: Field required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/PublicCallErrorResponse' security: - ApiKeyBearer: [] components: schemas: SendCallInputSchemaV2: description: |- Request schema for sending a call (v2 with multi-provider support). Shared by the dashboard's send-call endpoint and the public API, so the descriptions below are what integrators read on docs.dialtu.com. examples: - agent_id: 123 client_id: 456 max_duration: 300 phone_number: '+15551234567' request_data: appointment_date: '2026-10-02' timezone: America/Bogota properties: phone_number: description: >- Destination phone number in E.164 format (for example `+15551234567`). A number without a leading `+` is combined with `country_code`. title: Phone Number type: string agent_id: description: >- ID of the voice agent that places the call, as shown in the dashboard. title: Agent Id type: integer max_duration: description: >- Maximum call length in seconds; the call is ended when it is reached. title: Max Duration type: integer from: anyOf: - type: string - type: 'null' description: >- Caller ID to dial from, as one of the account's phone numbers. Defaults to the agent's configured number. title: From first_sentence: anyOf: - type: string - type: 'null' description: Overrides the agent's opening line for this call. title: First Sentence wait_for_greeting: anyOf: - type: boolean - type: 'null' default: false description: >- Wait for the recipient to speak before the agent says its first sentence. title: Wait For Greeting request_data: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Arbitrary key/value pairs made available to the agent's prompt as variables (for example `{{appointment_date}}`). title: Request Data dynamic_data: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Values the agent may update during the call; returned with the call record. title: Dynamic Data start_time: anyOf: - format: date-time type: string - type: 'null' description: >- When to place the call, ISO 8601. Omit to queue it immediately. Interpreted in `timezone` when no offset is given. title: Start Time voicemail_message: anyOf: - type: string - type: 'null' description: Message the agent leaves when the call reaches voicemail. title: Voicemail Message voicemail_action: anyOf: - $ref: '#/components/schemas/VoicemailAction' - type: 'null' default: hangup description: >- What to do on voicemail: `hangup`, `leave_message` (uses `voicemail_message`), or `ignore` (continue as if answered). record: anyOf: - type: boolean - type: 'null' description: Record the call. Defaults to the agent's setting. title: Record analysis_schema: anyOf: - additionalProperties: true type: object - type: 'null' description: >- JSON Schema of fields to extract from the transcript after the call; results are stored on the call record. title: Analysis Schema answered_by_enabled: anyOf: - type: boolean - type: 'null' default: false description: >- Detect whether a human or a machine answered before the agent starts talking. title: Answered By Enabled timezone: anyOf: - type: string - type: 'null' default: UTC description: >- IANA timezone (for example `America/Mexico_City`) used to interpret `start_time` and retry time slots. title: Timezone country_code: anyOf: - type: string - type: 'null' default: '1' description: >- Country calling code prepended when `phone_number` has no `+` prefix. title: Country Code disposition_tags: anyOf: - items: $ref: '#/components/schemas/DispositionTagDTO' type: array - type: 'null' description: >- Disposition tags the agent may apply to this call. Tags that do not exist yet are created. title: Disposition Tags client_id: anyOf: - type: integer - type: 'null' description: >- ID of an existing client to attach the call to (see *Create a client*). title: Client Id max_retries: anyOf: - type: integer - type: 'null' default: 0 description: How many times to retry the call. `0` disables retries. title: Max Retries retry_delay_days: anyOf: - type: integer - type: 'null' default: 0 description: >- Days to wait before a retry: `0` retries the same day, `1`–`30` on a later day. title: Retry Delay Days retry_time_slot: anyOf: - type: string - type: 'null' default: morning description: >- Time of day for retries: `morning`, `midday`, `afternoon`, `evening`, or `custom` (then set `retry_specific_time`). title: Retry Time Slot retry_specific_time: anyOf: - format: time type: string - type: 'null' description: Clock time (`HH:MM`) for retries when `retry_time_slot` is `custom`. title: Retry Specific Time retry_on_not_connected: anyOf: - type: boolean - type: 'null' description: Retry when the call is not answered or reaches voicemail. title: Retry On Not Connected retry_on_disposition_tags: anyOf: - type: boolean - type: 'null' description: Retry when the agent applies a disposition tag of type `retry`. title: Retry On Disposition Tags required: - phone_number - agent_id - max_duration title: SendCallInputSchemaV2 type: object PublicScheduleCallResponse: description: Public API response schema for scheduled calls. properties: status: const: success description: Response status title: Status type: string call_id: description: Unique identifier for the scheduled call title: Call Id type: integer message: description: Human-readable success message title: Message type: string scheduled_at: anyOf: - type: string - type: 'null' description: When the call is scheduled to execute (ISO 8601 format) title: Scheduled At queue_status: description: Current status of the call in the queue enum: - queued - processing title: Queue Status type: string required: - status - call_id - message - queue_status title: PublicScheduleCallResponse type: object PublicCallErrorResponse: description: Public API error response schema. properties: status: const: error description: Error status title: Status type: string error_code: description: >- Machine-readable error code (e.g., 'TENANT_NOT_FOUND', 'AGENT_NOT_FOUND') title: Error Code type: string message: description: Human-readable error message title: Message type: string details: anyOf: - additionalProperties: true type: object - type: 'null' description: Additional error details (optional) title: Details required: - status - error_code - message title: PublicCallErrorResponse type: object DetailErrorResponse: description: 'Plain error body: `{"detail": "..."}`. No `error_code` is included.' properties: detail: description: Human-readable reason for the failure. title: Detail type: string required: - detail title: DetailErrorResponse type: object RequestValidationError: title: RequestValidationError type: object description: >- Returned when the request body, query string or path could not be parsed against the documented schema. Fix the listed fields and retry. properties: detail: type: array title: Detail description: One entry per invalid field. items: $ref: '#/components/schemas/RequestValidationErrorItem' required: - detail VoicemailAction: enum: - hangup - leave_message - ignore title: VoicemailAction type: string DispositionTagDTO: properties: id: anyOf: - type: integer - type: 'null' description: The ID of the disposition tag title: Id name: description: The name of the disposition tag title: Name type: string color: default: '#7B61FF' description: The color of the disposition tag title: Color type: string type: anyOf: - type: string - type: 'null' default: standard description: The type of the disposition tag title: Type description: anyOf: - type: string - type: 'null' default: '' description: The description of the disposition tag title: Description analysis_prompt: anyOf: - type: string - type: 'null' description: AI prompt used to analyze if this tag applies to a call title: Analysis Prompt default_not_connected: anyOf: - type: boolean - type: 'null' default: false description: >- Whether this tag should be automatically selected for not connected calls title: Default Not Connected required: - name title: DispositionTagDTO type: object RequestValidationErrorItem: title: RequestValidationErrorItem type: object properties: loc: type: array title: Loc description: >- Where the problem is: the first element is `body`, `query` or `path`, followed by the field path. items: anyOf: - type: string - type: integer msg: type: string title: Msg description: What is wrong with the value. type: type: string title: Type description: >- Machine-readable validation error type, e.g. `missing` or `int_parsing`. required: - loc - msg - type securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: pk_... description: >- API key created in the dashboard under **Settings → API Keys**. Send it as `Authorization: Bearer pk_...`. ````