# Search and Buy

> Search Indian virtual numbers by region, type and digits with GET /v1/dids/available, buy one with POST /v1/dids/{id}/purchase, then manage renewal and release.

Source: https://edesy.in/docs/voice-api/phone-numbers/search-and-buy

Search available numbers with `GET /v1/dids/available`, filtering by region, number type and digits, then buy one with `POST /v1/dids/{id}/purchase`. Each listing shows the monthly price, setup fee and the exact first charge before you commit. KYC must be approved and the wallet must cover the first charge. The portal's Numbers page does the same thing with a form.

## Search

`GET https://voice-api.edesy.in/v1/dids/available?number_type=mobile&contains=2026`

| Query parameter | Description |
|---|---|
| `country` | ISO country code, for example `IN` |
| `region` | State or circle |
| `number_type` | For example `mobile`, `local` (landline) or `tollfree` |
| `series` | Number series, for example `92` for 92-series numbers |
| `contains` | Digits the number must contain |
| `page`, `per_page` | Pagination. `per_page` defaults to 50 |

```json
{
  "data": [
    {
      "phone_number_id": "4c1d2e3f-0000-4000-8000-000000000000",
      "number": "+9180XXXXXXXX",
      "region": "Karnataka",
      "city": "Bengaluru",
      "number_type": "local",
      "monthly_price": 449,
      "setup_fee": 0,
      "currency": "INR",
      "first_charge": { }
    }
  ],
  "meta": { "total": 120, "page": 1, "per_page": 50 }
}
```

`first_charge` breaks down what the purchase will deduct from your wallet. Some listings come straight from live carrier inventory; they carry a `live_ref` instead of a `phone_number_id` and are bought with `POST /v1/dids/purchase-live`.

## Buy

```bash
curl -X POST https://voice-api.edesy.in/v1/dids/4c1d2e3f-0000-4000-8000-000000000000/purchase \
  -H "Authorization: Bearer $EDESY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "friendly_name": "Support line" }'
```

| Field | Type | Description |
|---|---|---|
| `friendly_name` | string | Your label for the number |
| `acknowledged_total` | number | Optional. The first-charge total you showed the user, from `first_charge`. If the price changed since, the purchase is refused with `409 QUOTE_STALE` instead of charging a different amount |

For a live listing:

```json
{ "live_ref": "...", "friendly_name": "Sales", "months": 2 }
```

`months` prepays several months on numbers that support it.

### Purchase errors

| HTTP | Code | Meaning |
|---|---|---|
| 402 | `INSUFFICIENT_BALANCE` | Top up the wallet |
| 403 | `KYC_NOT_APPROVED` | Finish KYC first |
| 404 | `NOT_FOUND` | Listing not found |
| 409 | `NUMBER_NOT_OWNED` | Someone else just bought this number; pick another |
| 409 | `QUOTE_STALE` | The price changed; reload and retry |

## After you buy

1. The number appears in `GET /v1/phone-numbers` with its `phone_number_id`.
2. Use it as `from` on [`POST /v1/calls`](https://edesy.in/docs/voice-api/calls/make-a-call).
3. Decide where inbound calls go with [Inbound Routing](https://edesy.in/docs/voice-api/phone-numbers/inbound-routing).

## Renewal and release

- Rental is charged from the wallet. The number shows a "paid until" date and auto-renews.
- Supported numbers can be prepaid for several months at purchase.
- Release a number you no longer need with `POST /v1/dids/{id}/release` (optional `{"reason": "..."}`). A released number stops receiving calls and can no longer be used as a caller ID.

Prices: Rs 499/month for mobile and 92-series, Rs 449 for landline, Rs 999 for toll-free, no setup fee, all excluding 18% GST. See [virtual phone numbers](https://edesy.in/virtual-phone-number).