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

# Search numbers

> Search for available phone numbers you can purchase.

Searches for available phone numbers from the telephony provider. Use the results to find a number to purchase.

## Endpoint

`GET /user/phone-numbers/search`

## Query parameters

<ParamField query="country_code" type="string" default="US">
  ISO 3166-1 alpha-2 country code to search in (e.g., `US`, `GB`, `CA`).
</ParamField>

<ParamField query="contains" type="string">
  Filter numbers that contain specific digits. Numeric characters only, maximum 10 digits.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of available phone numbers.

  <Expandable title="Available number properties">
    <ResponseField name="phone_number" type="string">Phone number in E.164 format.</ResponseField>
    <ResponseField name="phone_number_formatted" type="string">Formatted display number.</ResponseField>
    <ResponseField name="country_code" type="string">ISO country code.</ResponseField>
    <ResponseField name="price" type="number">Monthly rental price in USD.</ResponseField>
    <ResponseField name="stripe_price_id" type="string">Stripe price ID used for billing.</ResponseField>
    <ResponseField name="address_requirements" type="string">Address requirements: `none`, `local`, `foreign`, or `inventory`.</ResponseField>
    <ResponseField name="sms_capable" type="boolean">Whether the number supports SMS.</ResponseField>
  </Expandable>
</ResponseField>

## Supported countries

| Country        | Code |
| -------------- | ---- |
| United States  | `US` |
| Canada         | `CA` |
| United Kingdom | `GB` |
| Australia      | `AU` |
| Israel         | `IL` |
| Poland         | `PL` |
| Finland        | `FI` |
| Netherlands    | `NL` |
| Denmark        | `DK` |
| Italy          | `IT` |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://portal.intellixent.ai/api/user/phone-numbers/search?country_code=US" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://portal.intellixent.ai/api/user/phone-numbers/search?country_code=US',
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const data = await response.json();
  console.log(data.data); // Available numbers
  ```
</CodeGroup>

```json 200 Response theme={null}
{
  "data": [
    {
      "phone_number": "+14155551234",
      "phone_number_formatted": "+1 415-555-1234",
      "country_code": "US",
      "price": 3.99,
      "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ",
      "address_requirements": "none",
      "sms_capable": true
    },
    {
      "phone_number": "+14155555678",
      "phone_number_formatted": "+1 415-555-5678",
      "country_code": "US",
      "price": 3.99,
      "stripe_price_id": "price_1PkA4dBXoZOzqQuAsvGvVJTZ",
      "address_requirements": "none",
      "sms_capable": false
    }
  ]
}
```

Pass a number from these results to the [Purchase phone number](/api-reference/phone-numbers/purchase-phone-number) endpoint.