Numbers registry

The registry is the authoritative list of your numbers on the platform — think of it as your HLR: for every number, who owns it, which provider it lives on, its lifecycle status, and its routing configuration.

Lifecycle

Status	Meaning
`porting_in`	An active port-in order exists for this number
`active`	Live, with routing configured
`active_unconfigured`	Live, but no routing configured yet — traffic has nowhere to go
`porting_out`	An approved port-out is in progress
`ported_out`	The number has left the platform
`inactive`	Not in service

Numbers appear in the registry as porting_in the moment an order is created (this also blocks duplicate orders), and flip to active / active_unconfigured when the port completes. If the order is cancelled or rejected, the entry is removed — the number was never yours on the platform.

Querying

curl "https://api.example.com/v2/numbers?status=active&country_code=GB" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

curl "https://api.example.com/v2/numbers?phone_number=%2B447912345678" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Routing configuration

routing_config is applied at the provider when the number activates (SIP connection, forwarding target, messaging profile — whatever your provider setup uses). Set it on the order (applies to all its numbers at activation) or per number afterwards:

curl -X PATCH https://api.example.com/v2/numbers/{number_id} \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing_config": {"sip_connection_id": "conn_123"}}'

Setting routing on an active_unconfigured number promotes it to active.

Also see Port-outs for the port_out_pin field, which protects numbers against unauthorized transfers.