# Request an internal phone number

POST https://api.close.com/api/v1/phone_number/request/internal/
Content-Type: application/json

Renting a phone number incurs a cost. You need the "Manage Group 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.

Reference: https://developer.close.com/api/resources/phone-numbers/create

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Close API
  version: 1.0.0
paths:
  /phone_number/request/internal/:
    post:
      operationId: create
      summary: Request an internal phone number
      description: >-
        Renting a phone number incurs a cost. You need the "Manage Group 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.
      tags:
        - subpackage_phoneNumbers
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/phone_numbers_create_Response_201'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Not found
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePhoneNumberRequest'
servers:
  - url: https://api.close.com/api/v1
components:
  schemas:
    CreatePhoneNumberRequestCarrierType:
      type: string
      enum:
        - local
        - national
        - mobile
        - tollfree
      title: CreatePhoneNumberRequestCarrierType
    PhoneNumberSharing:
      type: string
      enum:
        - personal
        - group
      title: PhoneNumberSharing
    CreatePhoneNumberRequest:
      type: object
      properties:
        bundle_id:
          type:
            - string
            - 'null'
        carrier_type:
          oneOf:
            - $ref: '#/components/schemas/CreatePhoneNumberRequestCarrierType'
            - type: 'null'
        country:
          type: string
          description: A two letter ISO country code (e.g. `US` for United States).
        prefix:
          type: string
          default: ''
          description: >-
            A string with the phone number prefix or area code, not including
            the country code.
        sharing:
          $ref: '#/components/schemas/PhoneNumberSharing'
          description: >-
            `personal` for a number that belongs to an individual user, or
            `group` for a group number.
        with_mms:
          type:
            - boolean
            - 'null'
          description: >-
            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:
          type:
            - boolean
            - 'null'
          description: >-
            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.
      required:
        - country
        - sharing
      title: CreatePhoneNumberRequest
    phone_numbers_create_Response_201:
      type: object
      properties: {}
      description: Empty response body
      title: phone_numbers_create_Response_201
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
    OAuth2:
      type: http
      scheme: bearer

```