Close Phone Numbers API

The phone_numbers API from Close — 3 operation(s) for phone_numbers.

Documentation GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /phone_number/ List or search phone numbers · List or search for phone numbers #

Ask an LLM

“Which phone numbers does my team have?”

“Can I find the phone numbers assigned to a specific user?”

Tell an agent

List all phone numbers.

Find phone numbers belonging to user {user_id}.

POST /phone_number/request/internal/ Rent a new phone number · Request an internal phone number #

Ask an LLM

“How do I get a new phone number in a given country?”

“Can I rent a number with SMS and MMS support and a specific prefix?”

Tell an agent

Rent a new phone number in {country}.

Request a {country} number with prefix {prefix} that supports SMS.

GET /phone_number/{id}/ Retrieve a phone number · Retrieve a single phone number #

Ask an LLM

“What are the forwarding and voicemail settings on a specific number?”

“Can I retrieve one phone number by id?”

Tell an agent

Fetch phone number {id}.

Show the settings of phone number {id}.

PUT /phone_number/{id}/ Update a phone number's settings · Update a phone number #

Ask an LLM

“Can I set up call forwarding on my number?”

“Is it possible to change the label or voicemail greeting on a phone number?”

Tell an agent

Forward calls on number {id} to {forward_to}.

Rename phone number {id} to {label}.

DELETE /phone_number/{id}/ Release a phone number · Delete a phone number #

Ask an LLM

“Can I get rid of a phone number we no longer need?”

“Who is allowed to delete a group phone number?”

Tell an agent destructive · confirm first

Delete phone number {id}.

Release number {id} from my account.

Specifications

⚙

OpenAPI

https://raw.githubusercontent.com/api-evangelist/close/refs/heads/main/openapi/close-phone-numbers-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/close:close-phone-numbers-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  description: Close CRM REST API
  title: Close Phone Numbers API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: Phone Numbers
  externalDocs:
    url: https://developer.close.com/api/resources/phone-numbers
paths:
  /phone_number/:
    get:
      operationId: phone_numbers_list
      tags:
      - Phone Numbers
      summary: List or search for phone numbers
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/FieldsParam'
      - in: query
        name: number
        required: false
        schema:
          title: Number
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: user_id
        required: false
        description: Deprecated. Use `participant_user_id` instead. The distinction between personal and group numbers is being removed, and `user_id` will be removed in a future update.
        schema:
          title: User ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
          deprecated: true
      - in: query
        name: is_group_number
        required: false
        description: Deprecated. Use `participant_user_id` instead. The distinction between personal and group numbers is being removed, and `is_group_number` will be removed in a future update.
        schema:
          title: Is Group Number
          default: null
          anyOf:
          - type: boolean
          - type: 'null'
          deprecated: true
      - in: query
        name: participant_user_id
        required: false
        description: Return numbers the given user participates in, including both personal and group numbers they belong to.
        schema:
          title: Participant User ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                - address_id: null
                  bundle_id: null
                  carrier: null
                  carrier_type: null
                  country: US
                  date_created: '2016-07-18T22:54:24.787000+00:00'
                  date_updated: '2016-07-18T22:55:55.938000+00:00'
                  forward_to: null
                  forward_to_enabled: false
                  forward_to_formatted: null
                  id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3
                  inbound_ring_duration: null
                  is_group_number: false
                  is_premium: false
                  is_verified: true
                  label: Primary Number
                  last_billed_price: null
                  mms_enabled: true
                  next_billing_on: null
                  number: '+16503335555'
                  number_formatted: +1 650-333-5555
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  participants: []
                  phone_numbers:
                  - '+16508889898'
                  phone_numbers_formatted:
                  - +1 650-888-9898
                  press_1_to_accept: false
                  sms_enabled: true
                  supports_mms_to_countries:
                  - CA
                  - US
                  supports_sms_to_countries:
                  - CA
                  - US
                  type: internal
                  user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  voicemail_greeting_url: null
                  was_ported: false
                - address_id: null
                  bundle_id: null
                  carrier: null
                  carrier_type: null
                  country: US
                  date_created: '2016-07-18T22:54:24.787000+00:00'
                  date_updated: '2016-07-18T22:55:55.938000+00:00'
                  forward_to: null
                  forward_to_enabled: false
                  forward_to_formatted: null
                  id: phon_973589ev50ZKOqTVndOFN4effz092753608234569U3
                  is_group_number: false
                  is_premium: false
                  is_verified: true
                  label: My Personal Cell
                  last_billed_price: null
                  mms_enabled: true
                  next_billing_on: null
                  number: '+14151231234'
                  number_formatted: +1 415-123-1234
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  participants: []
                  phone_numbers: []
                  phone_numbers_formatted: []
                  press_1_to_accept: false
                  sms_enabled: false
                  supports_mms_to_countries:
                  - CA
                  - US
                  supports_sms_to_countries: []
                  type: external
                  user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  voicemail_greeting_url: null
                  was_ported: false
                - address_id: null
                  bundle_id: null
                  carrier: null
                  carrier_type: null
                  country: US
                  date_created: '2016-07-14T20:37:23.022000+00:00'
                  date_updated: '2016-07-18T22:54:41.548000+00:00'
                  forward_to: null
                  forward_to_enabled: false
                  forward_to_formatted: null
                  id: phon_324230958beOjoa6F42w5Hlkdjfg8p3wmIPnTuvNbaX
                  inbound_ring_duration: null
                  is_group_number: true
                  is_premium: false
                  is_verified: true
                  label: Group Number
                  last_billed_price: null
                  mms_enabled: true
                  next_billing_on: null
                  number: '+16508881234'
                  number_formatted: +1 650-888-1234
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  participants:
                  - user_OWiN4rEbBR04K2AKXe3jq5j1JWQqmTguuuZa1dG7qQr
                  - user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk
                  - user_SJMF1fEyZGdtl2RPzCm9zVQ7qhd33VajdGDREhbsxjF
                  phone_numbers: []
                  phone_numbers_formatted: []
                  press_1_to_accept: false
                  sms_enabled: true
                  supports_mms_to_countries:
                  - CA
                  - US
                  supports_sms_to_countries:
                  - CA
                  - US
                  type: internal
                  user_id: null
                  voicemail_greeting_url: null
                has_more: false
              schema:
                type: object
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
                    type: array
                  has_more:
                    type: boolean
                required:
                - data
                - has_more
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /phone_number/request/internal/:
    post:
      operationId: phone_numbers_create
      tags:
      - Phone Numbers
      summary: Request an internal phone number
      description: '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.'
      requestBody:
        content:
          application/json:
            example:
              country: US
              prefix: '650'
              sharing: personal
            schema:
              $ref: '#/components/schemas/CreatePhoneNumberRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                address_id: null
                bundle_id: null
                carrier: null
                carrier_type: null
                country: US
                date_created: '2021-03-17T11:45:56.651057'
                date_updated: '2021-03-17T11:45:56.651057'
                forward_to: null
                forward_to_enabled: false
                forward_to_formatted: null
                id: phon_MiLNdBqo8utNOf1U78RaZgQB1Iq6rRGftiDW5C8B9uL
                inbound_ring_duration: null
                is_group_number: false
                is_premium: false
                is_verified: true
                label: null
                last_billed_price: null
                mms_enabled: true
                next_billing_on: null
                number: '+16503335555'
                number_formatted: +1 650-333-5555
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                press_1_to_accept: false
                sms_enabled: true
                supports_mms_to_countries:
                - CA
                - US
                supports_sms_to_countries:
                - CA
                - PR
                - US
                type: internal
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                voicemail_greeting_url: null
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /phone_number/{id}/:
    get:
      operationId: phone_numbers_get
      tags:
      - Phone Numbers
      summary: Retrieve a single phone number
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/FieldsParam'
      responses:
        '200':
          content:
            application/json:
              example:
                address_id: null
                bundle_id: null
                carrier: null
                carrier_type: null
                country: US
                date_created: '2016-07-18T22:54:24.787000+00:00'
                date_updated: '2016-07-18T22:55:55.938000+00:00'
                forward_to: null
                forward_to_enabled: false
                forward_to_formatted: null
                id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3
                inbound_ring_duration: null
                is_group_number: false
                is_premium: false
                is_verified: true
                label: Primary Number
                last_billed_price: null
                mms_enabled: true
                next_billing_on: null
                number: '+16503335555'
                number_formatted: +1 650-333-5555
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                press_1_to_accept: false
                sms_enabled: true
                supports_mms_to_countries:
                - CA
                - US
                supports_sms_to_countries:
                - CA
                - US
                type: internal
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                voicemail_greeting_url: null
              schema:
                $ref: '#/components/schemas/PhoneNumber'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    put:
      operationId: phone_numbers_update
      tags:
      - Phone Numbers
      summary: Update a phone number
      description: 'You need the "Manage Team 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".

        - Change how long (in seconds, 15-90) the number rings on inbound calls before moving on (e.g. to voicemail) via `inbound_ring_duration`.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              forward_to: '+16502221111'
              forward_to_enabled: true
              inbound_ring_duration: 45
              label: My number w/ forwarding
              voicemail_greeting_url: https://s3.amazonaws.com/bucket/aaa-bbb-ccc.mp3
            schema:
              $ref: '#/components/schemas/UpdatePhoneNumber'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                address_id: null
                bundle_id: null
                carrier: null
                carrier_type: null
                country: US
                date_created: '2016-07-18T22:54:24.787000+00:00'
                date_updated: '2016-07-22T22:55:55.938000+00:00'
                forward_to: '+16502221111'
                forward_to_enabled: true
                forward_to_formatted: +1 650-222-1111
                id: phon_asdjkfev50ZKOqTVndOFN4effzv99vDvpDxrks9XLU3
                inbound_ring_duration: 45
                is_group_number: false
                is_premium: false
                is_verified: true
                label: My number w/ forwarding
                last_billed_price: null
                mms_enabled: true
                next_billing_on: null
                number: '+16503335555'
                number_formatted: +1 650-333-5555
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                press_1_to_accept: false
                sms_enabled: true
                supports_mms_to_countries:
                - CA
                - US
                supports_sms_to_countries:
                - CA
                - US
                type: internal
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                voicemail_greeting_url: https://s3.amazonaws.com/bucket/aaa-bbb-ccc.mp3
              schema:
                $ref: '#/components/schemas/PhoneNumber'
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
    delete:
      operationId: phone_numbers_delete
      tags:
      - Phone Numbers
      summary: Delete a phone number
      description: You need the "Manage Team Phone Numbers" permission to delete a group number. You can only delete your own personal numbers.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  schemas:
    UnderlyingCarrier:
      title: UnderlyingCarrier
      type: string
      enum:
      - twilio
      - plivo
    PhoneNumber:
      title: PhoneNumber
      type: object
      properties:
        address_id:
          title: Address ID
          anyOf:
          - type: string
          - type: 'null'
        bundle_id:
          title: Bundle ID
          anyOf:
          - type: string
          - type: 'null'
        carrier:
          anyOf:
          - $ref: '#/components/schemas/UnderlyingCarrier'
          - type: 'null'
        carrier_type:
          anyOf:
          - $ref: '#/components/schemas/CarrierNumberType'
          - type: 'null'
        country:
          title: Country
          anyOf:
          - type: string
          - type: 'null'
        date_created:
          title: Date Created
          type: string
          format: date-time
        date_updated:
          title: Date Updated
          type: string
          format: date-time
        forward_to:
          title: Forward To
          anyOf:
          - type: string
          - type: 'null'
        forward_to_enabled:
          title: Forward To Enabled
          type: boolean
        forward_to_formatted:
          title: Forward To Formatted
          anyOf:
          - type: string
          - type: 'null'
        id:
          title: ID
          type: string
        inbound_ring_duration:
          title: Inbound Ring Duration
          description: 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.
          anyOf:
          - type: integer
          - type: 'null'
        is_group_number:
          title: Is Group Number
          description: Deprecated. The distinction between personal and group numbers is being removed, and `is_group_number` will be removed in a future update.
          deprecated: true
          type: boolean
        is_premium:
          title: Is Premium
          type: boolean
        is_verified:
          title: Is Verified
          type: boolean
        label:
          title: Label
          type: string
        last_billed_price:
          title: Last Billed Price
          anyOf:
          - type: number
          - type: 'null'
        mms_enabled:
          title: Mms Enabled
          type: boolean
        next_billing_on:
          title: Next Billing On
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        number:
          title: Number
          type: string
        number_formatted:
          title: Number Formatted
          type: string
        organization_id:
          title: Organization ID
          type: string
        participants:
          title: Participants
          type: array
          items:
            type: string
        phone_numbers:
          title: Phone Numbers
          type: array
          items:
            type: string
        phone_numbers_formatted:
          title: Phone Numbers Formatted
          type: array
          items:
            type: string
        press_1_to_accept:
          title: Press 1 To Accept
          type: boolean
        sms_enabled:
          title: SMS Enabled
          type: boolean
        supports_mms_to_countries:
          title: Supports Mms To Countries
          type: array
          items:
            type: string
        supports_sms_to_countries:
          title: Supports SMS To Countries
          type: array
          items:
            type: string
        type:
          $ref: '#/components/schemas/PhoneNumberType'
        user_id:
          title: User ID
          description: Deprecated. Set to the sole member's user ID for single-member numbers, otherwise `null`. `user_id` will be removed in a future update.
          deprecated: true
          anyOf:
          - type: string
          - type: 'null'
        voicemail_greeting_url:
          title: Voicemail Greeting URL
          anyOf:
          - type: string
          - type: 'null'
        was_ported:
          title: 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
    UpdatePhoneNumber:
      title: UpdatePhoneNumber
      type: object
      properties:
        forward_to:
          title: Forward To
          type: string
        forward_to_enabled:
          title: Forward To Enabled
          type: boolean
        inbound_ring_duration:
          title: Inbound Ring Duration
          description: Number of seconds (15-90) to ring this number on inbound calls before moving on (e.g. to voicemail).
          type: integer
          minimum: 15
          maximum: 90
        label:
          title: Label
          type: string
        participants:
          title: Participants
          type: array
          items:
            type: string
        phone_numbers:
          title: Phone Numbers
          type: array
          items:
            type: string
        press_1_to_accept:
          title: Press 1 To Accept
          type: boolean
        voicemail_greeting_url:
          title: Voicemail Greeting URL
          anyOf:
          - type: string
          - type: 'null'
      additionalProperties: false
    CarrierNumberType:
      title: CarrierNumberType
      type: string
      enum:
      - local
      - national
      - mobile
      - tollfree
      - shortcode
    PhoneNumberType:
      title: PhoneNumberType
      type: string
      enum:
      - internal
      - external
      - virtual
    PhoneNumberSharing:
      title: PhoneNumberSharing
      type: string
      enum:
      - personal
      - group
    CreatePhoneNumberRequest:
      title: CreatePhoneNumberRequest
      type: object
      properties:
        bundle_id:
          title: Bundle ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
        carrier_type:
          title: Carrier Type
          default: null
          anyOf:
          - type: string
            enum:
            - local
            - national
            - mobile
            - tollfree
          - type: 'null'
        country:
          title: Country
          description: A two letter ISO country code (e.g. `US` for United States).
          type: string
        prefix:
          title: Prefix
          description: A string with the phone number prefix or area code, not including the country code.
          type: string
          default: ''
          maxLength: 5
        sharing:
          description: Deprecated. `personal` for a number that belongs to an individual user, or `group` for a group number. The distinction between personal and group numbers is being removed, and this field will be removed in a future update. When omitted, defaults to `personal`.
          deprecated: true
          default: personal
          $ref: '#/components/schemas/PhoneNumberSharing'
        with_mms:
          title: With MMS
          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.
          default: null
          anyOf:
          - type: boolean
          - type: 'null'
        with_sms:
          title: With SMS
          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.
          default: null
          anyOf:
          - type: boolean
          - type: 'null'
      required:
      - country
      additionalProperties: false
  parameters:
    LimitParam:
      description: Number of results to return.
      in: query
      name: _limit
      required: false
      schema:
        default: 100
        type: integer
    FieldsParam:
      description: Comma-separated list of fields to include in the response.
      in: query
      name: _fields
      required: false
      schema:
        type: string
    SkipParam:
      description: Number of results to skip before returning, for pagination.
      in: query
      name: _skip
      required: false
      schema:
        default: 0
        type: integer
  securitySchemes:
    ApiKeyAuth:
      description: Use your API key as the username and leave the password empty.
      scheme: basic
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://app.close.com/oauth2/authorize/
          scopes:
            all.full_access: Full access to all resources
            offline_access: Request a refresh token
          tokenUrl: https://api.close.com/oauth2/token/
      type: oauth2