curl --request POST \
--url https://api.talkpilot.io/v1/agents/{agentId}/phone-number \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"source": "pool"
}
'import requests
url = "https://api.talkpilot.io/v1/agents/{agentId}/phone-number"
payload = { "source": "pool" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({source: 'pool'})
};
fetch('https://api.talkpilot.io/v1/agents/{agentId}/phone-number', 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.talkpilot.io/v1/agents/{agentId}/phone-number",
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([
'source' => 'pool'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.talkpilot.io/v1/agents/{agentId}/phone-number"
payload := strings.NewReader("{\n \"source\": \"pool\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.talkpilot.io/v1/agents/{agentId}/phone-number")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"source\": \"pool\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkpilot.io/v1/agents/{agentId}/phone-number")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source\": \"pool\"\n}"
response = http.request(request)
puts response.read_body{
"phone_number": "+4930123456789",
"pool_remaining": 4
}Assign a phone number
Assigns a free number from the TalkPilot number pool to the agent. The numbers in the pool are already fully wired, so the agent answers calls on the new number from the next call on.
Dashboard login only: requires a JWT of a super_admin or dev_admin.
API keys are rejected with 403 FORBIDDEN, even with agents:write.
The only supported source is pool. An agent that already has a phone
number gets 409 AGENT_HAS_NUMBER; if no pool number is free, the
response is 409 POOL_EMPTY.
The number is also written to the agent’s employees and forwarding
slots (agent_phone_number), which is how call routing finds them at
runtime.
When the number is released (DELETE) or the agent is deleted later,
the number goes into a 90-day quarantine and then returns to the pool
automatically.
curl --request POST \
--url https://api.talkpilot.io/v1/agents/{agentId}/phone-number \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"source": "pool"
}
'import requests
url = "https://api.talkpilot.io/v1/agents/{agentId}/phone-number"
payload = { "source": "pool" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({source: 'pool'})
};
fetch('https://api.talkpilot.io/v1/agents/{agentId}/phone-number', 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.talkpilot.io/v1/agents/{agentId}/phone-number",
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([
'source' => 'pool'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$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.talkpilot.io/v1/agents/{agentId}/phone-number"
payload := strings.NewReader("{\n \"source\": \"pool\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
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.talkpilot.io/v1/agents/{agentId}/phone-number")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"source\": \"pool\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.talkpilot.io/v1/agents/{agentId}/phone-number")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source\": \"pool\"\n}"
response = http.request(request)
puts response.read_body{
"phone_number": "+4930123456789",
"pool_remaining": 4
}Authorizations
API key for external access. Format: tp_live_<32-hex-chars>.
Create keys in the TalkPilot Dashboard under Settings > API.
Path Parameters
Agent UUID
Body
Where the number comes from. Only pool is supported.
pool