> ## Documentation Index > Fetch the complete documentation index at: https://dev.alpharun.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Call Task > Schedules an outbound call for one of your voice agents to place. Alpharun owns the scheduling and the dialing: the call is placed at the first moment at or after `requested_at` that falls within the agent's calling hours, so the `scheduled_at` on the returned task is often later than the `requested_at` you asked for. If no call can be fitted in before the task expires — including when the agent has no calling hours at all — the request is rejected with a `400 Bad Request` response. The endpoint returns a `201 Created` response with the scheduled task. If you pass an `ext_id` that belongs to a task that is still live, no second call is scheduled and the existing task is returned with a `200 OK` response. A task that has reached a terminal status (`completed`, `canceled` or `failed`) releases its `ext_id`, so submitting the same one again schedules a new call. Outbound calling is enabled per agent; if it is not enabled for the voice agent, the request is rejected with a `403 Forbidden` response. ## OpenAPI ````yaml POST /call-tasks openapi: 3.0.1 info: title: Alpharun API description: Alpharun REST API reference license: name: MIT version: 1.0.0 servers: - url: https://api.alpharun.com/api/v1 security: - bearerAuth: [] paths: /call-tasks: post: description: >- Schedules an outbound call for one of your voice agents to place. Alpharun owns the scheduling and the dialing: the call is placed at the first moment at or after `requested_at` that falls within the agent's calling hours, so the `scheduled_at` on the returned task is often later than the `requested_at` you asked for. If no call can be fitted in before the task expires — including when the agent has no calling hours at all — the request is rejected with a `400 Bad Request` response. The endpoint returns a `201 Created` response with the scheduled task. If you pass an `ext_id` that belongs to a task that is still live, no second call is scheduled and the existing task is returned with a `200 OK` response. A task that has reached a terminal status (`completed`, `canceled` or `failed`) releases its `ext_id`, so submitting the same one again schedules a new call. Outbound calling is enabled per agent; if it is not enabled for the voice agent, the request is rejected with a `403 Forbidden` response. requestBody: required: true content: application/json: schema: type: object required: - agent_id - requested_at - contact properties: agent_id: type: string format: uuid description: The UUID of the voice agent that will place the call. requested_at: type: string format: date-time description: >- The earliest time the call may be placed. Accepts ISO 8601 format with a timezone offset (e.g. '2026-08-03T14:30:00Z' or '2026-08-03T09:30:00-05:00'). A time in the past means as soon as the agent's calling hours allow. May be at most 90 days in the future. expires_at: type: string format: date-time description: >- The time past which the call is no longer worth placing, for example because the appointment it is about has happened. If no call can be placed before it, the task fails instead of calling late. Defaults to five days after `requested_at`, and must be after it. contact: $ref: '#/components/schemas/CallTaskContactPayload' custom_fields: type: array description: >- Custom fields to set on the customer interaction created for this call. Each `key` must match the `field_name` of a **Customer interaction** custom field defined in your Alpharun dashboard; entries whose keys don't match a definition are ignored. items: type: object required: - key - value properties: key: type: string description: >- The `field_name` of the customer interaction custom field to set. value: anyOf: - type: string - type: number - type: boolean nullable: true description: Value to set for the custom field. ext_id: type: string maxLength: 255 description: >- Your own identifier for the call task, for example the ID of the appointment it is about. Submitting it again while the task is still live returns the existing task instead of scheduling a second call. example: agent_id: 660e8400-e29b-41d4-a716-446655440001 requested_at: '2026-08-03T10:00:00.000Z' ext_id: appointment-1234 contact: phone_number: '+14155550123' first_name: Casey last_name: Doe custom_fields: - key: advisor value: Dana responses: '200': description: >- A live call task with the same `ext_id` already exists and is returned unchanged content: application/json: schema: type: object properties: data: type: object properties: call_task: $ref: '#/components/schemas/CallTask' example: data: call_task: id: 550e8400-e29b-41d4-a716-446655440000 ext_id: appointment-1234 agent_id: 660e8400-e29b-41d4-a716-446655440001 contact_id: 770e8400-e29b-41d4-a716-446655440002 status: scheduled requested_at: '2026-08-03T10:00:00.000Z' scheduled_at: '2026-08-03T13:00:00.000Z' expires_at: '2026-08-08T10:00:00.000Z' created_at: '2026-08-01T09:12:44.000Z' completed_at: null canceled_at: null cancel_requested_at: null attempts: [] '201': description: Call task scheduled content: application/json: schema: type: object properties: data: type: object properties: call_task: $ref: '#/components/schemas/CallTask' example: data: call_task: id: 550e8400-e29b-41d4-a716-446655440000 ext_id: appointment-1234 agent_id: 660e8400-e29b-41d4-a716-446655440001 contact_id: 770e8400-e29b-41d4-a716-446655440002 status: scheduled requested_at: '2026-08-03T10:00:00.000Z' scheduled_at: '2026-08-03T13:00:00.000Z' expires_at: '2026-08-08T10:00:00.000Z' created_at: '2026-08-01T09:12:44.000Z' completed_at: null canceled_at: null cancel_requested_at: null attempts: [] '400': description: Invalid payload, or no call can be placed before the task expires content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Outbound calling is not enabled for the voice agent content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CallTaskContactPayload: type: object required: - phone_number description: >- The contact to call. Contacts are matched on `ext_id`, `email` or `phone_number` and created when no existing contact matches, as they are on the Upload Recording endpoint. A phone number is required — there is nothing to dial without one. properties: phone_number: anyOf: - type: string - type: number description: Phone number to call, in E.164 format (e.g. `+14155550123`) email: type: string format: email description: Email address of the contact first_name: type: string description: First name of the contact last_name: type: string description: Last name of the contact ext_id: type: string description: External ID of the contact custom_fields: type: array description: Custom fields associated with the contact items: type: object required: - key - value properties: key: type: string value: anyOf: - type: string - type: number - type: boolean nullable: true CallTask: type: object required: - id - ext_id - agent_id - contact_id - status - requested_at - scheduled_at - expires_at - created_at - completed_at - canceled_at - cancel_requested_at - attempts description: >- An outbound call you asked a voice agent to place, with one entry in `attempts` for each attempt at reaching the contact. properties: id: type: string format: uuid description: Unique identifier of the call task ext_id: type: string nullable: true description: >- Your own identifier for the call task, or `null` if you did not provide one agent_id: type: string format: uuid description: ID of the voice agent placing the call contact_id: type: string format: uuid description: ID of the contact being called status: type: string enum: - scheduled - calling - processing - completed - canceled - failed description: >- Status of the call task: `scheduled` when it is waiting to be called (including while it waits to be retried), `calling` while a call is being placed, `processing` once a call has ended and is being analyzed, and `completed`, `canceled` and `failed` once it is done. A `failed` task will not be called again; the reason is on its last attempt. requested_at: type: string format: date-time description: The earliest time the call may be placed, as you requested it scheduled_at: type: string format: date-time description: >- The time the call is currently scheduled for: the first moment at or after `requested_at` that falls within the agent's calling hours. It moves when the task is rescheduled or is due to be retried. expires_at: type: string format: date-time description: The time past which the call is no longer placed created_at: type: string format: date-time description: When the call task was created completed_at: type: string format: date-time nullable: true description: When the call task completed, or `null` if it has not canceled_at: type: string format: date-time nullable: true description: When the call task was canceled, or `null` if it was not cancel_requested_at: type: string format: date-time nullable: true description: >- When a cancellation was requested while a call was already under way, or `null` attempts: type: array description: One entry per attempt at reaching the contact, oldest first items: $ref: '#/components/schemas/CallTaskAttempt' Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string CallTaskAttempt: type: object required: - attempt_number - started_at - result - error description: >- One attempt at reaching the contact: when it started, how it ended, and why. Attempts where no call was placed at all — for example because the contact has no phone number — are included, with a `not_dialed` result. properties: attempt_number: type: integer description: Position of this attempt in the task's attempts, starting at 1 started_at: type: string format: date-time description: When the attempt started result: type: string nullable: true enum: - contacted - no_contact - unknown - no_answer - busy - failed - not_dialed description: >- How the attempt ended, or `null` while it is still in progress. The call connected on `contacted` (a person was on the line), `no_contact` (nobody engaged, for example voicemail) and `unknown` (what came of it was never established). The call never connected on `no_answer` (the phone rang out), `busy` and `failed` (the call could not be completed). On `not_dialed` no call was placed at all, and `error` says what stopped it. error: type: object nullable: true required: - code - message description: >- Why the attempt produced no conversation, or `null` when there is nothing to report properties: code: type: string enum: - feature_disabled - agent_calling_disabled - no_phone_number - agent_number_missing - agent_unavailable - no_calling_window - dial_failed - call_setup_failed - workflow_lost - retries_exhausted - expired - window_past_expiry description: >- Stable code to group errors by. Nothing was set up to call with on `feature_disabled`, `agent_calling_disabled`, `no_phone_number`, `agent_number_missing`, `agent_unavailable` and `no_calling_window`; the call was placed but did not work out on `dial_failed`, `call_setup_failed` and `workflow_lost`; and the task ran out of retries or time on `retries_exhausted`, `expired` and `window_past_expiry`. message: type: string description: Human-readable detail about what went wrong securitySchemes: bearerAuth: type: http scheme: bearer ````