curl --request POST \
--url https://api.agentline.cloud/v1/numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"country": "US",
"number_type": "local",
"area_code": "<string>",
"pattern": "<string>"
}
'import requests
url = "https://api.agentline.cloud/v1/numbers"
payload = {
"agent_id": "<string>",
"country": "US",
"number_type": "local",
"area_code": "<string>",
"pattern": "<string>"
}
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: '<string>',
country: 'US',
number_type: 'local',
area_code: '<string>',
pattern: '<string>'
})
};
fetch('https://api.agentline.cloud/v1/numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Provision
Buy a US or Canadian phone number for your AI agent.
Buys a real +1 number from the carrier, attaches it to the agent and uses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make outbound calls and answers inbound calls on this number. Not idempotent: every successful call buys and charges for another number.
Prerequisites: an agent from create_agent with no active number (each agent has at most one; a second purchase returns HTTP 409), plus a remaining subscription number allowance or $3.00 in the wallet (HTTP 402 otherwise; see get_account_balance).
Returns the number’s id (num_…, used by release_phone_number and as from_number_id), phone_number, country, number_type, status, cost, balance_remaining and a private number card link (card_url, card_image_url, card_url_expires_at). If the account has an owner email, the card link is also emailed there.
curl --request POST \
--url https://api.agentline.cloud/v1/numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"country": "US",
"number_type": "local",
"area_code": "<string>",
"pattern": "<string>"
}
'import requests
url = "https://api.agentline.cloud/v1/numbers"
payload = {
"agent_id": "<string>",
"country": "US",
"number_type": "local",
"area_code": "<string>",
"pattern": "<string>"
}
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: '<string>',
country: 'US',
number_type: 'local',
area_code: '<string>',
pattern: '<string>'
})
};
fetch('https://api.agentline.cloud/v1/numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).
Body
ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')
Country code for the phone number ('US' or 'CA')
Type of phone number: 'local' or 'tollfree'
Preferred 3-digit US area code (e.g. '212' for NYC, '415' for SF, '310' for LA)
Legacy digit pattern match (prefer area_code instead)
Response
Successful Response