---
title: "Request an internal phone number"
method: POST
path: "/phone_number/request/internal/"
tags: ["phone_numbers"]
---

# Request an internal phone number

`POST /phone_number/request/internal/`

Renting a phone number incurs a cost. You need the "Manage Team Phone Numbers" permission to rent group numbers.

If a number was rented, a 201 response is returned with the new number. If no number was rented (4xx response code), the response contains a `status` field which may contain one of the values below. New statuses may be added in the future.

* `has-voice-only`: This country/prefix combination only has non-SMS-capable
  numbers. You can attempt renting the number by passing `with_sms` as `false`.
* `needs-more-info`: More information (such as proof of address) is needed to
  rent this number. This number can only be rented by contacting Close support.
* `billing-error`: An error related to billing has occurred. For example, the
  telephony budget has been reached, or there are not enough funds and recharging failed.
* `error`: An error has occurred while renting this number. A human-readable
  message is returned in the `error` field.

## Request body

- CreatePhoneNumberRequest
  - `bundle_id` string, nullable
  - `carrier_type` 'local' | 'national' | 'mobile' | 'tollfree', nullable
  - `country` string, required — A two letter ISO country code (e.g. `US` for United States).
  - `prefix` string — A string with the phone number prefix or area code, not including the country code.
  - `sharing` 'personal' | 'group'
  - `with_mms` boolean, nullable — By default, MMS-capable numbers are rented if Close supports MMS for the given country. Renting an MMS-capable number can be forced by setting this flag to `true`. If set to `false`, certain prefixes that don't support MMS can be rented in countries where Close supports MMS. In most scenarios, this flag should not be passed. When you request an MMS number, you must set `with_sms` to `true` as well.
  - `with_sms` boolean, nullable — By default, SMS-capable numbers are rented if Close supports SMS for the given country. Renting an SMS-capable number can be forced by setting this flag to `true`. If set to `false`, certain prefixes that don't support SMS can be rented in countries where Close supports SMS. In most scenarios, this flag should not be passed unless a `has-voice-only` error status is received.

## Response `201`

Successful response

## Other responses

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

---

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