Skip to main content

​
Number lifecycle directly affects delivery and reputation.

The Phone Numbers API covers discovery, ownership sync, assignment, and operational state changes.

​
Lifecycle stages

  1. Discover available inventory (available, pricing, countries).
  2. Acquire numbers (purchase or import_owned).
  3. Activate and assign to campaigns/agents.
  4. Monitor health and run periodic sync/resync.
  5. Release numbers when no longer needed.

​
Inventory and acquisition

curl "https://api.callaro.ai/api/v1/phone_numbers?page=1&per_page=20" -H "X-Api-Key: $CALLARO_API_KEY"
curl "https://api.callaro.ai/api/v1/phone_numbers/available?country=IN" -H "X-Api-Key: $CALLARO_API_KEY"
curl "https://api.callaro.ai/api/v1/phone_numbers/pricing?country=IN" -H "X-Api-Key: $CALLARO_API_KEY"
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/purchase" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"country":"IN","quantity":2,"telephony_connection_id":9}'
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/import_owned" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"numbers":[{"e164":"+14155550100","label":"US Outbound Pool A"}],"telephony_connection_id":9}'

await fetch('https://api.callaro.ai/api/v1/phone_numbers?page=1&per_page=20', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } });
await fetch('https://api.callaro.ai/api/v1/phone_numbers/available?country=IN', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } });
await fetch('https://api.callaro.ai/api/v1/phone_numbers/purchase', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.CALLARO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ country: 'IN', quantity: 2, telephony_connection_id: 9 })
});

​
Activation, sync, and release

curl "https://api.callaro.ai/api/v1/phone_numbers/101" -H "X-Api-Key: $CALLARO_API_KEY"
curl -X PATCH "https://api.callaro.ai/api/v1/phone_numbers/101" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"label":"India Pool B"}'
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/activate" -H "X-Api-Key: $CALLARO_API_KEY"
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/sync" -H "X-Api-Key: $CALLARO_API_KEY"
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/resync" -H "X-Api-Key: $CALLARO_API_KEY"
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/configure_webhooks" -H "X-Api-Key: $CALLARO_API_KEY" -H "Content-Type: application/json" -d '{"status_callback_url":"https://example.com/provider/status"}'
curl -X POST "https://api.callaro.ai/api/v1/phone_numbers/101/release" -H "X-Api-Key: $CALLARO_API_KEY"

await Promise.all([
  fetch('https://api.callaro.ai/api/v1/phone_numbers/101', { headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
  fetch('https://api.callaro.ai/api/v1/phone_numbers/101', { method: 'PATCH', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ label: 'India Pool B' }) }),
  fetch('https://api.callaro.ai/api/v1/phone_numbers/101/activate', { method: 'POST', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } }),
  fetch('https://api.callaro.ai/api/v1/phone_numbers/sync', { method: 'POST', headers: { 'X-Api-Key': process.env.CALLARO_API_KEY } })
]);

​
Number-health operating rules

  • Keep rotating pools per campaign to reduce repeated-caller fatigue.
  • Monitor spam-flag indicators and remove affected numbers quickly.
  • Use region/timezone-aligned numbers for better answer rates.
  • Reconcile provider inventory with periodic sync.

​
Failure modes

SymptomLikely causeAction
Purchase fails with validation errorUnsupported region/quantity/connectionRe-check countries and pricing constraints
Activation failsNumber not correctly bound to connection/tenantInspect number detail and connection status
Delivery degrades after launchSpam flag or reputation issuePause high-risk campaigns and rotate numbers
Sync mismatchProvider-side driftRun resync on affected numbers and review webhook config