cURL

curl --request POST \
  --url https://api.alpharun.com/api/v1/call-tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://api.alpharun.com/api/v1/call-tasks"

payload = {
    "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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://api.alpharun.com/api/v1/call-tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alpharun.com/api/v1/call-tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alpharun.com/api/v1/call-tasks"

	payload := strings.NewReader("{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alpharun.com/api/v1/call-tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alpharun.com/api/v1/call-tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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": []
    }
  }
}

{
  "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": []
    }
  }
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

Outbound calling

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.

POST

call-tasks

cURL

curl --request POST \
  --url https://api.alpharun.com/api/v1/call-tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'

import requests

url = "https://api.alpharun.com/api/v1/call-tasks"

payload = {
    "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"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://api.alpharun.com/api/v1/call-tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alpharun.com/api/v1/call-tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alpharun.com/api/v1/call-tasks"

	payload := strings.NewReader("{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alpharun.com/api/v1/call-tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alpharun.com/api/v1/call-tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"660e8400-e29b-41d4-a716-446655440001\",\n  \"requested_at\": \"2026-08-03T10:00:00.000Z\",\n  \"ext_id\": \"appointment-1234\",\n  \"contact\": {\n    \"phone_number\": \"+14155550123\",\n    \"first_name\": \"Casey\",\n    \"last_name\": \"Doe\"\n  },\n  \"custom_fields\": [\n    {\n      \"key\": \"advisor\",\n      \"value\": \"Dana\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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": []
    }
  }
}

{
  "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": []
    }
  }
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

{
  "error": 123,
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

agent_id

string<uuid>

required

The UUID of the voice agent that will place the call.

requested_at

string<date-time>

required

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.

contact

object

required

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.

Show child attributes

expires_at

string<date-time>

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.

custom_fields

object[]

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.

Show child attributes

ext_id

string

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.

Maximum string length: 255

Response

A live call task with the same ext_id already exists and is returned unchanged

data

object

Show child attributes

API Documentation

Call monitoring

Outbound calling

Contacts

Teammates

Hiring

Create Call Task

Authorizations

Body

Response