openapi: 3.1.0
info:
  title: API Endpoints subpackage_activities subpackage_phoneNumbers API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
tags:
- name: subpackage_phoneNumbers
paths:
  /phone_number/:
    get:
      operationId: list
      summary: List or search for phone numbers
      tags:
      - subpackage_phoneNumbers
      parameters:
      - name: _limit
        in: query
        description: Number of results to return.
        required: false
        schema:
          type: integer
          default: 100
      - name: _skip
        in: query
        description: Number of results to skip before returning, for pagination.
        required: false
        schema:
          type: integer
          default: 0
      - name: _fields
        in: query
        description: Comma-separated list of fields to include in the response.
        required: false
        schema:
          type: string
      - name: number
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: user_id
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: is_group_number
        in: query
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/phone_numbers_list_Response_200'
        '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
  /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.\n\nIf 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.\n\n* `has-voice-only`: This country/prefix combination only has non-SMS-capable\n  numbers. You can attempt renting the number by passing `with_sms` as `false`.\n* `needs-more-info`: More information (such as proof of address) is needed to\n  rent this number. This number can only be rented by contacting Close support.\n* `billing-error`: An error related to billing has occurred. For example, the\n  telephony budget has been reached, or there are not enough funds and recharging failed.\n* `error`: An error has occurred while renting this number. A human-readable\n  message is returned in the `error` field."
      tags:
      - subpackage_phoneNumbers
      parameters:
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        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'
  /phone_number/{id}/:
    get:
      operationId: get
      summary: Retrieve a single phone number
      tags:
      - subpackage_phoneNumbers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: _fields
        in: query
        description: Comma-separated list of fields to include in the response.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '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
    put:
      operationId: update
      summary: Update a phone number
      description: 'You need the "Manage Group Phone Numbers" permission to update a group number. You can only update your own personal numbers.


        You can:


        - Change a `label` of your number.

        - Set up call forwarding via `forward_to` and `forward_to_enabled`.

        - Set up a voicemail greeting by including a URL of an mp3 recording in `voicemail_greeting_url`. We require the URL to be secure (i.e. starting with https://).

        - Modify which team members are part of a group number via `participants`. This should be a list of user IDs.

        - Modify which external phone numbers are part of a group number via `phone_numbers`. This should be a list of phone numbers in E.164 international format, e.g. "+16503334444".'
      tags:
      - subpackage_phoneNumbers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '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/UpdatePhoneNumber'
    delete:
      operationId: delete
      summary: Delete a phone number
      description: You need the "Manage Group Phone Numbers" permission to delete a group number. You can only delete your own personal numbers.
      tags:
      - subpackage_phoneNumbers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Use your API key as the username and leave the password empty.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/phone_numbers_delete_Response_200'
        '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
components:
  schemas:
    UnderlyingCarrier:
      type: string
      enum:
      - twilio
      - plivo
      title: UnderlyingCarrier
    CarrierNumberType:
      type: string
      enum:
      - local
      - national
      - mobile
      - tollfree
      - shortcode
      title: CarrierNumberType
    PhoneNumberType:
      type: string
      enum:
      - internal
      - external
      - virtual
      title: PhoneNumberType
    phone_numbers_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        has_more:
          type: boolean
      required:
      - data
      - has_more
      title: phone_numbers_list_Response_200
    phone_numbers_delete_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: phone_numbers_delete_Response_200
    PhoneNumberSharing:
      type: string
      enum:
      - personal
      - group
      title: PhoneNumberSharing
    PhoneNumber:
      type: object
      properties:
        address_id:
          type:
          - string
          - 'null'
        bundle_id:
          type:
          - string
          - 'null'
        carrier:
          oneOf:
          - $ref: '#/components/schemas/UnderlyingCarrier'
          - type: 'null'
        carrier_type:
          oneOf:
          - $ref: '#/components/schemas/CarrierNumberType'
          - type: 'null'
        country:
          type:
          - string
          - 'null'
        date_created:
          type: string
          format: date-time
        date_updated:
          type: string
          format: date-time
        forward_to:
          type:
          - string
          - 'null'
        forward_to_enabled:
          type: boolean
        forward_to_formatted:
          type:
          - string
          - 'null'
        id:
          type: string
        is_group_number:
          type: boolean
        is_premium:
          type: boolean
        is_verified:
          type: boolean
        label:
          type: string
        last_billed_price:
          type:
          - number
          - 'null'
          format: double
        mms_enabled:
          type: boolean
        next_billing_on:
          type:
          - string
          - 'null'
          format: date-time
        number:
          type: string
        number_formatted:
          type: string
        organization_id:
          type: string
        participants:
          type: array
          items:
            type: string
        phone_numbers:
          type: array
          items:
            type: string
        phone_numbers_formatted:
          type: array
          items:
            type: string
        press_1_to_accept:
          type: boolean
        sms_enabled:
          type: boolean
        supports_mms_to_countries:
          type: array
          items:
            type: string
        supports_sms_to_countries:
          type: array
          items:
            type: string
        type:
          $ref: '#/components/schemas/PhoneNumberType'
        user_id:
          type:
          - string
          - 'null'
        voicemail_greeting_url:
          type:
          - string
          - 'null'
        was_ported:
          type: boolean
      required:
      - address_id
      - bundle_id
      - carrier
      - carrier_type
      - country
      - date_created
      - date_updated
      - id
      - is_group_number
      - is_premium
      - is_verified
      - label
      - last_billed_price
      - mms_enabled
      - next_billing_on
      - number
      - number_formatted
      - organization_id
      - sms_enabled
      - supports_mms_to_countries
      - supports_sms_to_countries
      - type
      - user_id
      title: PhoneNumber
    phone_numbers_create_Response_201:
      type: object
      properties: {}
      description: Empty response body
      title: phone_numbers_create_Response_201
    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
    UpdatePhoneNumber:
      type: object
      properties:
        forward_to:
          type: string
        forward_to_enabled:
          type: boolean
        label:
          type: string
        participants:
          type: array
          items:
            type: string
        phone_numbers:
          type: array
          items:
            type: string
        press_1_to_accept:
          type: boolean
        voicemail_greeting_url:
          type:
          - string
          - 'null'
      title: UpdatePhoneNumber
    CreatePhoneNumberRequestCarrierType:
      type: string
      enum:
      - local
      - national
      - mobile
      - tollfree
      title: CreatePhoneNumberRequestCarrierType
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: basic
      description: Use your API key as the username and leave the password empty.
    OAuth2:
      type: http
      scheme: bearer