# Numbers (/docs/reseller/your-clients/numbers)

> Search, buy, and attach a phone number for a client. Buying is the normal number API with the client's user_id added.

Once a client is verified on a carrier, buying a number is not a separate reseller
endpoint. It is the ordinary number API with the client's `user_id` added. The number
lands on the client's account and its rental comes out of the client's balance, not
yours.

## Search [#search]

```http
GET /api/v1/phone_number/search?region=IN&carrier=carrier-1&user_id=CLIENT_ID
```

Search with the client's `user_id`, and read the `carrier` the results come from.

## Buy [#buy]

```http
POST /api/v1/phone_number/purchase

{ "region": "IN", "carrier": "carrier-1", "phone_number": "+91...", "user_id": CLIENT_ID }
```

Buy on the carrier the client verified on. Verification does not carry across carriers,
so a client verified on one still has to verify on another before it can buy there.

The purchase checks the client's verification state and returns `409 kyc_incomplete` when
it is not done yet. A client who completed verification in the dashboard instead passes
the same gate, so there is nothing to repeat.

## Attach [#attach]

Once the client has an agent, attach the number to it:

```http
POST /api/v1/phone_number/attach

{ "phone_number_id": 321, "agent_id": 42, "user_id": CLIENT_ID }
```

  Pass the `carrier` on search, purchase, release, and every verification call, in every
  region, however few carriers it holds. Call without one and the refusal lists that
  region's carriers, which is how you pick up a carrier we add later without shipping
  anything.

## Release [#release]

```http
POST /api/v1/phone_number/release

{ "phone_number_id": 321, "user_id": CLIENT_ID }
```

Releasing a client's number returns it to the carrier. If you instead want to take the
number back to yourself when you release the whole client, see
[Release a client](/docs/reseller/your-clients/clients).

The same flow, call by call with the money and reservation details, is in
[Buy a number over the API](/docs/buy-a-number-api).