API: agent phone numbers on a single carrier, and deleting an agent a live number routes to is refused
API: agent phone numbers on a single carrier, and deleting an agent a live number routes to is refused
POST /v1/agents/phone-numbers/purchase now places every new number on the same carrier (Telnyx), and the available-number search returns that carrier’s inventory only. Omit provider and the platform picks it for you — the recommended call, and what the console does.
provider: "twilio_purchased" is retired for new purchases and now returns 400 validation_failed, naming the provider to send instead. The value stays in the PhoneNumberProvider enum, and nothing changes for numbers already bought on it: they are listed, released, dialled and billed exactly as before.
Only an integration that hardcodes the provider on the purchase request is affected. One that omits provider, or echoes back the value the available-number search returned, needs no change.
No version pin is involved — the response shape is unchanged, and telnyx_purchased has been a valid type on returned numbers since 2026-06-25, so a tolerant reader already handles it. See Phone numbers.
Deleting an agent is refused while a phone number still routes to it
DELETE /v1/agents/{agent_id} now returns 409 agent_in_use while a live phone number still routes to the agent — including the agent a webhook binding provisioned for its number. The blocking numbers ride the standard error envelope’s error.details.used_by, so the caller knows exactly what to unbind:
409 agent_in_use— a live phone number still routes to the agent. Release or re-point each number named inused_by, then retry the delete.
The alternative would leave a number pointing at nothing. An agent with no number bound deletes exactly as before.