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

# Search Available Numbers

> Search for available phone numbers to provision

Search for available phone numbers to add to your account. Filter by area code, country, number type, and pattern matching.

## Request Body

Send one of `areaCode`, `state`, `city`, or `query`. If none provided with just `numberType`, returns default US numbers.

<ParamField body="areaCode" type="string">
  3-digit area code to search in.

  **Example:** `604`
</ParamField>

<ParamField body="state" type="string">
  2-letter US state or Canadian province code. Auto-detects Canadian provinces.

  **Example:** `CA`, `NY`, `BC`, `ON`
</ParamField>

<ParamField body="city" type="string">
  City name. Supports 40+ major US and Canadian cities.

  **Example:** `vancouver`, `san francisco`, `new york`
</ParamField>

<ParamField body="numberType" type="string" default="local">
  Number type: `local` or `tollFree`.
</ParamField>

<ParamField body="query" type="string">
  Legacy free-text search. Accepts area codes, city names, state codes, or `canada`/`usa`.
</ParamField>

Returns up to **75 numbers** per search (3 pages of 25 in the UI).

## Response

<ResponseField name="numbers" type="array">
  Array of available phone numbers with details.
</ResponseField>

### Number Object

<ResponseField name="phone_number" type="string">
  The phone number in E.164 format.
</ResponseField>

<ResponseField name="friendly_name" type="string">
  Human-readable formatted number.
</ResponseField>

<ResponseField name="locality" type="string">
  City or region for local numbers.
</ResponseField>

<ResponseField name="region" type="string">
  State or province code.
</ResponseField>

<ResponseField name="capabilities" type="object">
  What the number supports: `voice`, `sms`, `mms`.
</ResponseField>

<ResponseField name="monthly_cost" type="number">
  Monthly cost in USD.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/search-phone-numbers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "area_code": "604",
      "country": "CA",
      "limit": 5
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/search-phone-numbers',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        area_code: '604',
        country: 'CA',
        limit: 5
      }),
    }
  );

  const { numbers } = await response.json();
  console.log('Available numbers:', numbers);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/search-phone-numbers',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'area_code': '604',
          'country': 'CA',
          'limit': 5
      }
  )

  data = response.json()
  for num in data['numbers']:
      print(f"{num['phone_number']} - {num['locality']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "numbers": [
      {
        "phone_number": "+16045551234",
        "friendly_name": "(604) 555-1234",
        "locality": "Vancouver",
        "region": "BC",
        "capabilities": {
          "voice": true,
          "sms": true,
          "mms": true
        },
        "monthly_cost": 2.00
      },
      {
        "phone_number": "+16045555678",
        "friendly_name": "(604) 555-5678",
        "locality": "Vancouver",
        "region": "BC",
        "capabilities": {
          "voice": true,
          "sms": true,
          "mms": true
        },
        "monthly_cost": 2.00
      }
    ]
  }
  ```
</ResponseExample>