# Search available phone numbers (/docs/api-reference/phone-numbers/searchPhoneNumbers)

> Search the OmniDimension number shop for phone numbers available to buy in a region. Price and validity are flat per region, so every result shows the same monthly_rental_usd and validity_days, and that is the exact amount a purchase will charge.

**GET** `/phone_number/search`

Search the OmniDimension number shop for phone numbers available to buy
in a region. Price and validity are flat per region, so every result
shows the same `monthly_rental_usd` and `validity_days`, and that is the
exact amount a purchase will charge.

```yaml
operationId: searchPhoneNumbers
parameters:
  - name: region
    in: query
    required: true
    description: Region to search in.
    schema:
      type: string
      enum:
        - IN
        - US
    example: US
  - name: pattern
    in: query
    required: false
    description: Digits or prefix to match within the number.
    schema:
      type: string
    example: '555'
  - name: page
    in: query
    required: false
    description: Page of results to return.
    schema:
      type: integer
      minimum: 1
      default: 1
  - name: limit
    in: query
    required: false
    description: Results per page.
    schema:
      type: integer
      minimum: 1
      maximum: 150
      default: 20
  - name: user_id
    in: query
    required: false
    description: 'Reseller accounts only: the client to act on. Omit it to act on your own account.'
    schema:
      type: integer
responses:
  '200':
    description: Numbers available in this region.
    content:
      application/json:
        schema:
          type: object
          properties:
            success:
              type: boolean
            region:
              type: string
              enum:
                - IN
                - US
            numbers:
              type: array
              items:
                type: object
                properties:
                  phone_number:
                    type: string
                  monthly_rental_usd:
                    type: number
                    description: Amount, in USD, that a purchase of this number will charge per month.
                  validity_days:
                    type: integer
                    description: Days the number stays active before it has to be renewed.
                  region:
                    type: string
                    enum:
                      - IN
                      - US
                  kyc_required:
                    type: boolean
                    description: Whether identity verification is required before buying this number.
            total:
              type: integer
            page:
              type: integer
            limit:
              type: integer
            total_pages:
              type: integer
        example:
          success: true
          region: US
          numbers:
            - phone_number: '+15551234567'
              monthly_rental_usd: 5
              validity_days: 30
              region: US
              kyc_required: false
          total: 1
          page: 1
          limit: 20
          total_pages: 1
  '400':
    description: '`page` or `limit` is not a valid integer, or is out of range.'
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: invalid_request
          error_description: page must be >= 1 and limit between 1 and 150.
  '401':
    description: Missing or invalid API key.
  '403':
    description: |
      A `user_id` was sent by a key that is not a reseller admin, or
      the named client's account is currently unavailable.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: forbidden
          error_description: Access denied. Only reseller accounts can use this endpoint.
  '404':
    description: |
      The `user_id` did not name one of your clients (`not_found`),
      or numbers are not available for this region (`not_available`).
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: not_found
          error_description: Child user not found.
  '500':
    description: Unexpected server error.
    content:
      application/json:
        schema:
          allOf:
            - type: object
              properties:
                error:
                  type: string
                  description: Machine-readable error code.
                error_description:
                  type: string
                  description: Human-readable explanation.
            - type: object
              properties:
                ref:
                  type: string
                  description: Reference to quote to support.
        example:
          error: server_error
          error_description: >-
            Something went wrong on our side. Please try again shortly, or contact support with
            reference a1b2c3d4e5f6.
          ref: a1b2c3d4e5f6
```

**curl**

```bash
curl -X GET "https://omnidim.io/api/v1/phone_number/search?region=US&pattern=555" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY"
```

Searching does not reserve anything. A number is claimed only when a purchase
starts, so a number you saw a moment ago can be gone by the time you buy it.

Next step: [purchase a number](/docs/api-reference/phone-numbers/purchasePhoneNumber),
or read the flow end to end in [Buy a number over the API](/docs/buy-a-number-api).