# Lines and numbers

A **Line** is the owned identity; a phone number is its current network
endpoint. Your plan sets how many number-holding Lines your organization
may have, including `provisioning`, `active`, `suspended` and `releasing`
claims.

## Search, reserve, acquire

1. `GET /v1/available-numbers?country=US&area_code=212&capabilities=voice,sms`.
   Listings expose purchase and rental costs separately, as quoted.
2. Authorized owner or project key: `POST /v1/numbers/reserve {org,country,area_code}`.
   The returned `nres_…` carries an `expires_at` — trust the returned
   expiry, not a fixed sleep.
3. `POST /v1/lines {org,number_reservation}`; for delegated execution
   supply `agent`, or use the paired agent's `numbers.provision` grant.
4. Real orders can return `status: provisioning`. Retrieve the **same
   Line** until it is active; do not create a second order to recover a
   lost response.

ORDan records the claim before ordering, attaches the voice and messaging
configuration, and verifies the number on activation. Purchase and first
rental are separate expenses under one cost authorization; rental continues
on suspended numbers (suspension is not carrier deletion). Ported
inventory can be attached with `phone_number: num_…` — see
[ports](api.md).

## Messaging readiness

Voice can be active while outbound SMS approval is still pending. Each
customer's number is assigned to its own approved campaign. Outbound SMS
returns `409 a2p_registration_pending` until registration and assignment
are complete. See [messaging](messaging.md).

## Suspend, restore, release

`POST /v1/lines/{line}/revoke` suspends authority and holds the number for
30 days. `/reactivate` restores a suspended Line if available, within the
organization's Line cap (403 `limit_reached` otherwise). `DELETE
/v1/lines/{line}` requests permanent release; a real Line can remain
`releasing` while calls are hung up and carrier deletion is confirmed.

Use `GET /v1/numbers` for unattached inventory; authorized owners/keys can
release numbers directly. Keep polling through `release_pending` — an API
acknowledgement is not proof the monthly rental stopped. See
[errors](errors.md) for how pending states resolve.