---
title: "List or search for phone numbers"
method: GET
path: "/phone_number/"
tags: ["phone_numbers"]
---

# List or search for phone numbers

`GET /phone_number/`

## Query parameters

- `_limit` integer
- `_skip` integer
- `_fields` string
- `number` string, nullable
- `user_id` string, nullable
- `is_group_number` boolean, nullable
- `participant_user_id` string, nullable

## Response `200`

Successful response

- object
  - `data` PhoneNumber[], required
    - `address_id` string, nullable, required
    - `bundle_id` string, nullable, required
    - `carrier` 'twilio' | 'plivo', required
    - `carrier_type` 'local' | 'national' | 'mobile' | 'tollfree' | 'shortcode', required
    - `country` string, nullable, required
    - `date_created` string, date-time, required
    - `date_updated` string, date-time, required
    - `forward_to` string, nullable
    - `forward_to_enabled` boolean
    - `forward_to_formatted` string, nullable
    - `id` string, required
    - `inbound_ring_duration` integer, nullable — Number of seconds we ring this number on inbound calls before moving on (e.g. to voicemail). `null` means the default of 30 seconds is used.
    - `is_group_number` boolean, required — This field is deprecated and will be removed in a future update. Until then, it is set to `false` when the phone number has exactly one member (as defined by the `participants` field) and doesn't have any of the "shared" configuration set up (e.g. a phone menu, lead-based routing, a non-default ring order, etc.), and `true` otherwise.
    - `is_premium` boolean, required
    - `is_verified` boolean, required
    - `label` string, required
    - `last_billed_price` number, nullable, required
    - `mms_enabled` boolean, required
    - `next_billing_on` string, date-time, nullable, required
    - `number` string, required
    - `number_formatted` string, required
    - `organization_id` string, required
    - `participants` string[] — Every member of the phone number, as user IDs. If this field is absent, see `user_id` for the sole member.
    - `phone_numbers` string[] — Present unless the phone number has exactly one member and no shared-number configuration (a phone menu, lead-based routing, a dial-out list, or a non-default ring order).
    - `phone_numbers_formatted` string[] — Present under the same condition as `phone_numbers`, with each value formatted for display.
    - `press_1_to_accept` boolean
    - `sms_enabled` boolean, required
    - `supports_mms_to_countries` string[], required
    - `supports_sms_to_countries` string[], required
    - `type` 'internal' | 'external' | 'virtual', required
    - `user_id` string, nullable, required — This field is deprecated. See the `participants` field instead to learn who's assigned to this phone number. This `user_id` field will be removed in a future update. Until then, it is set to a specific user ID *only if* the given phone number has a single participant and no additional "shared" configuration (e.g. a phone menu, lead-based routing, a non-default ring order, etc.).
    - `voicemail_greeting_url` string, nullable
    - `was_ported` boolean
  - `has_more` boolean, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.dev/close/apis/close-api.md) · [All operations](https://skmtc.dev/close/apis/close-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/close/close-api/revisions/59969f4fe8c1/schema)