> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search numbers

> Find local US and Canada numbers you can buy, with the monthly price.

<Note>
  This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

<ParamField body="countryCode" type="string" default="US">
  `US` or `CA`.
</ParamField>

<ParamField body="areaCode" type="string">
  A 3-digit area code, for example `415`.
</ParamField>

<ParamField body="contains" type="string">
  Digits the number must contain, up to 10.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  How many numbers to return, 1 to 100.
</ParamField>

Only local numbers are for sale. Toll-free and premium numbers are not.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nedzo.ai/v1/phone-numbers/search" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "countryCode": "US", "areaCode": "415", "limit": 5 }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "items": [
      {
        "phoneNumber": "+14155551234",
        "nationalFormat": "(415) 555-1234",
        "region": { "city": "San Francisco", "state": "CA" },
        "monthlyPriceCents": 99
      }
    ],
    "total": 1
  }
  ```
</ResponseExample>

## Errors

| Status | When |
| - | - |
| `400` | A field is not valid |
| `502` | The phone number service did not answer. Try again |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.