Number lifecycle directly affects delivery and reputation.

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

Lifecycle stages

Discover available inventory (available, pricing, countries).
Acquire numbers (purchase or import_owned).
Activate and assign to campaigns/agents.
Monitor health and run periodic sync/resync.
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

Symptom	Likely cause	Action
Purchase fails with validation error	Unsupported region/quantity/connection	Re-check `countries` and `pricing` constraints
Activation fails	Number not correctly bound to connection/tenant	Inspect number detail and connection status
Delivery degrades after launch	Spam flag or reputation issue	Pause high-risk campaigns and rotate numbers
Sync mismatch	Provider-side drift	Run `resync` on affected numbers and review webhook config