Skip to main content
POST
/
calls
Create a voice call
curl --request POST \
  --url https://api.pamhq.com/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentSlug": "voice-recall",
  "toNumber": "+15555550199",
  "fromNumber": "+15555550123",
  "welcomeMessage": "Hi Ada, this is PAM Motors following up on your service recall.",
  "dynamicVariables": {
    "contact_first_name": "Ada",
    "contact_last_name": "Lovelace",
    "dealership_name": "PAM Motors",
    "recall_id": "24V-123",
    "service_ids": "RECALL_SERVICE",
    "vin": "1HGBH41JXMN109186",
    "vehicle_year": "2021",
    "vehicle_make": "Honda",
    "vehicle_model": "Accord"
  },
  "metadata": {
    "externalContactId": "contact_123"
  },
  "externalReferenceId": "touchpoint_123",
  "idempotencyKey": "call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC",
  "webhookUrl": "https://partner.example.com/pam/webhooks"
}
'
import requests

url = "https://api.pamhq.com/v1/calls"

payload = {
    "agentSlug": "voice-recall",
    "toNumber": "+15555550199",
    "fromNumber": "+15555550123",
    "welcomeMessage": "Hi Ada, this is PAM Motors following up on your service recall.",
    "dynamicVariables": {
        "contact_first_name": "Ada",
        "contact_last_name": "Lovelace",
        "dealership_name": "PAM Motors",
        "recall_id": "24V-123",
        "service_ids": "RECALL_SERVICE",
        "vin": "1HGBH41JXMN109186",
        "vehicle_year": "2021",
        "vehicle_make": "Honda",
        "vehicle_model": "Accord"
    },
    "metadata": { "externalContactId": "contact_123" },
    "externalReferenceId": "touchpoint_123",
    "idempotencyKey": "call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC",
    "webhookUrl": "https://partner.example.com/pam/webhooks"
}
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({
    agentSlug: 'voice-recall',
    toNumber: '+15555550199',
    fromNumber: '+15555550123',
    welcomeMessage: 'Hi Ada, this is PAM Motors following up on your service recall.',
    dynamicVariables: {
      contact_first_name: 'Ada',
      contact_last_name: 'Lovelace',
      dealership_name: 'PAM Motors',
      recall_id: '24V-123',
      service_ids: 'RECALL_SERVICE',
      vin: '1HGBH41JXMN109186',
      vehicle_year: '2021',
      vehicle_make: 'Honda',
      vehicle_model: 'Accord'
    },
    metadata: {externalContactId: 'contact_123'},
    externalReferenceId: 'touchpoint_123',
    idempotencyKey: 'call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC',
    webhookUrl: 'https://partner.example.com/pam/webhooks'
  })
};

fetch('https://api.pamhq.com/v1/calls', 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.pamhq.com/v1/calls",
  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([
    'agentSlug' => 'voice-recall',
    'toNumber' => '+15555550199',
    'fromNumber' => '+15555550123',
    'welcomeMessage' => 'Hi Ada, this is PAM Motors following up on your service recall.',
    'dynamicVariables' => [
        'contact_first_name' => 'Ada',
        'contact_last_name' => 'Lovelace',
        'dealership_name' => 'PAM Motors',
        'recall_id' => '24V-123',
        'service_ids' => 'RECALL_SERVICE',
        'vin' => '1HGBH41JXMN109186',
        'vehicle_year' => '2021',
        'vehicle_make' => 'Honda',
        'vehicle_model' => 'Accord'
    ],
    'metadata' => [
        'externalContactId' => 'contact_123'
    ],
    'externalReferenceId' => 'touchpoint_123',
    'idempotencyKey' => 'call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC',
    'webhookUrl' => 'https://partner.example.com/pam/webhooks'
  ]),
  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.pamhq.com/v1/calls"

	payload := strings.NewReader("{\n  \"agentSlug\": \"voice-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\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.pamhq.com/v1/calls")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentSlug\": \"voice-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.pamhq.com/v1/calls")

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  \"agentSlug\": \"voice-recall\",\n  \"toNumber\": \"+15555550199\",\n  \"fromNumber\": \"+15555550123\",\n  \"welcomeMessage\": \"Hi Ada, this is PAM Motors following up on your service recall.\",\n  \"dynamicVariables\": {\n    \"contact_first_name\": \"Ada\",\n    \"contact_last_name\": \"Lovelace\",\n    \"dealership_name\": \"PAM Motors\",\n    \"recall_id\": \"24V-123\",\n    \"service_ids\": \"RECALL_SERVICE\",\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"vehicle_year\": \"2021\",\n    \"vehicle_make\": \"Honda\",\n    \"vehicle_model\": \"Accord\"\n  },\n  \"metadata\": {\n    \"externalContactId\": \"contact_123\"\n  },\n  \"externalReferenceId\": \"touchpoint_123\",\n  \"idempotencyKey\": \"call_01HV7K4ZD3Q9X8P1M8Y2K9A0BC\",\n  \"webhookUrl\": \"https://partner.example.com/pam/webhooks\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  },
  "meta": {
    "requestId": "<string>"
  }
}

Authorizations

​
Authorization
string
header
default:pk_live_your_api_key
required

API key provided as Authorization: Bearer <key>.

Headers

​
Idempotency-Key
string

Stable key for safely retrying a create request. For call creation, send either this header or idempotencyKey in the request body.

Required string length: 1 - 255

Body

application/json

Select exactly one agent. Use agentSlug for PAM-managed agents, or agentId for a specific custom agent.

​
agentId
string<uuid>
required

Specific custom agent id.

​
toNumber
string
required

Phone number in E.164 format.

Pattern: ^\+\d{7,15}$
​
agentSlug
string

Stable slug for a PAM-managed agent.

Required string length: 1 - 255
​
fromNumber
string

Required when you use agentSlug. Ignored when the selected agent has a configured phone number.

Pattern: ^\+\d{7,15}$
​
welcomeMessage
string

Opening text used as the Retell begin message. Required when you use a PAM-managed voice agent.

​
dynamicVariables
object

Required when you use a PAM-managed recall or retention voice agent. Send only public variables documented in the Agents guide; generated prompt blocks are internal.

​
metadata
object

Opaque metadata stored with the conversation for reconciliation.

​
externalReferenceId
string

Optional opaque caller-owned reference echoed as top-level externalReferenceId on webhook payloads. PAM does not interpret this value, does not require it to be globally unique, and does not use it as an idempotency key.

Required string length: 1 - 255
​
idempotencyKey
string

Stable key for safely retrying this create request. Use this field if you do not send the Idempotency-Key header.

Required string length: 1 - 255
​
webhookUrl
string<uri>

Optional HTTPS destination for webhook events from this call. The URL overrides only this call's destination; event subscriptions, custom headers, and signing secret still come from the matching webhook registration.

Pattern: ^https://

Response

Call request accepted

​
data
object
​
meta
object