Close Phone Numbers API
The phone_numbers API from Close — 3 operation(s) for phone_numbers.
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/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.
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.\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."
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:
parameters:
FieldsParam:
description: Comma-separated list of fields to include in the response.
in: query
name: _fields
required: false
schema:
type: string
LimitParam:
description: Number of results to return.
in: query
name: _limit
required: false
schema:
default: 100
type: integer
SkipParam:
description: Number of results to skip before returning, for pagination.
in: query
name: _skip
required: false
schema:
default: 0
type: integer
schemas:
CarrierNumberType:
title: CarrierNumberType
type: string
enum:
- local
- national
- mobile
- tollfree
- shortcode
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
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
PhoneNumberSharing:
title: PhoneNumberSharing
type: string
enum:
- personal
- group
UnderlyingCarrier:
title: UnderlyingCarrier
type: string
enum:
- twilio
- plivo
PhoneNumberType:
title: PhoneNumberType
type: string
enum:
- internal
- external
- virtual
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
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