Phone Numbers

Each agent can have one active phone number. Numbers are US or Canada and use your included number allowance first; additional numbers cost $3.00/month each, deducted from your wallet.

Free trial

An account that has never recharged or picked a plan gets its first local US or Canada number free. That buy returns the number with cost 0, trial true and trial_ends_at, and starts a 7-day trial with 10 call minutes and 10 SMS. Recharge or pick a plan before the trial ends and the number stays on your account. Otherwise it is detached from your account when the trial ends, and calls and texts on it stop for you. GET /v1/billing/balance returns the trial’s status, ends_at, call_seconds_remaining and sms_remaining. JavaScript examples call https://api.agentline.cloud with fetch and a Bearer al_live_... key. The Node package is not on npm.

Buy a number

number = client.numbers.buy(
    agent_id=agent.id,
    country="US",
    number_type="local",
    area_code="415",
)

const number = await fetch("https://api.agentline.cloud/v1/numbers", {
  method: "POST",
  headers: {
    Authorization: "Bearer al_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: agent.id,
    country: "US",
    number_type: "local",
    area_code: "415",
  }),
}).then((res) => res.json());

Field	Notes
`agent_id`	Agent to assign the number to (required)
`country`	`US` or `CA`
`number_type`	`local`; toll-free availability depends on the number service
`area_code`	Preferred 3-digit US or Canadian area code (e.g. `212`, `415`, `310`)

List and reassign

client.numbers.list()
client.numbers.get(number.id)
client.numbers.reassign(number.id, agent_id=other_agent.id)

const headers = { Authorization: "Bearer al_live_..." };

await fetch("https://api.agentline.cloud/v1/numbers", { headers });
await fetch(`https://api.agentline.cloud/v1/numbers/${number.id}`, { headers });
await fetch(
  `https://api.agentline.cloud/v1/numbers/${number.id}/reassign?agent_id=${otherAgent.id}`,
  { method: "PATCH", headers },
);

Reassigning moves the number to another agent. The target agent must not already have an active number. Deleting an agent detaches (but does not release) its number.

Release a number

POST /v1/numbers/{number_id}/release

Destructive. This unrents the number from the carrier. It cannot be recovered, and calls and texts to it stop. The request is refused while a call is in progress or a lease is still active, and for a free-trial number.

Get Started

Guides

SDKs

Phone Numbers

Phone Numbers

Free trial

Buy a number

List and reassign

Release a number

​Phone Numbers

​Free trial

​Buy a number

​List and reassign

​Release a number

Phone Numbers

Free trial

Buy a number

List and reassign

Release a number