For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomepageProduct HelpLog inTry for Free
Developers HomeAPI ReferenceMCP
Developers HomeAPI ReferenceMCP
  • Getting Started
    • Introduction
    • Authentication with API Keys
    • Authentication with OAuth
    • API Clients
    • Pagination
    • Specifying Fields
    • Filter Parameters
    • HTTP Response Codes
    • Rate Limits
    • Timezone Offsets
    • Rich Text Fields
    • Changelog
  • CRM Core
    • Leads
    • Contacts
    • Opportunities
    • Tasks
    • Files
    • Custom Objects
    • Comments
  • Activities
    • Activities
    • Notes
    • Calls
    • Emails
    • Email Threads
    • WhatsApp Messages
    • Meetings
    • Custom Activities
    • Creations
    • Form Submissions
    • Lead Status Changes
    • Opportunity Status Changes
    • Lead Merges
    • Task Completions
  • Events & Webhooks
    • Webhooks
    • Events
  • Search & Reporting
    • Advanced Filtering
    • Smart Views
    • Reporting
  • Automation & Bulk Actions
    • Sequences (Workflows)
    • Bulk Actions
    • Exports
    • AI Field Enrichment
  • CRM Configuration
    • Custom Fields
    • Custom Activity Types
    • Custom Object Types
    • Pipelines
    • Opportunity Statuses
    • Lead Statuses
    • Integration Links
    • Forms
  • Communication Configuration
    • Email Templates
    • SMS Templates
    • Outcomes
    • Playbooks
    • Scheduling Links Guide
    • Scheduling Links
    • Connected Accounts
    • Send As
    • Unsubscribed Emails
    • Phone Numbers
      • GETList or search for phone numbers
      • POSTRequest an internal phone number
      • GETRetrieve a single phone number
      • PUTUpdate a phone number
      • DELDelete a phone number
    • Blocked Phone Numbers
    • Dialers
  • Users & Organizations
    • Users
    • Organizations
    • Memberships
    • Roles
    • Groups
Close

Product

OverviewCommunicationAutomationIntegrationsReportingSMSCallingSecurityForms

Pricing & Use Cases

PricingClose vs Other CRMsCustomer Stories

Resources

Sales BlogSales ResourcesSales GuidesWebinarsOn-Demand DemoSales Tools

Company

AboutCareersPartner with CloseBrand GuidelinesTermsPrivacyGDPRCCPA

Get Help

+1-833-GO-CLOSEHelp CenterDownload the Close AppProduct UpdatesSystem Status
LogoLogo
HomepageProduct HelpLog inTry for Free
Communication ConfigurationPhone Numbers

Request an internal phone number

||View as Markdown|
POST
https://api.close.com/api/v1/phone_number/request/internal/
POST
/api/v1/phone_number/request/internal/
$curl -X POST https://api.close.com/api/v1/phone_number/request/internal/ \
>     -H "Content-Type: application/json" \
>     -u "<CLOSE_API_KEY>:" \
>     -d '{
>  "country": "US",
>  "sharing": "personal",
>  "prefix": "650"
>}'
1{
2  "address_id": null,
3  "bundle_id": null,
4  "carrier": null,
5  "carrier_type": null,
6  "country": "US",
7  "date_created": "2021-03-17T11:45:56.651057",
8  "date_updated": "2021-03-17T11:45:56.651057",
9  "forward_to": null,
10  "forward_to_enabled": false,
11  "forward_to_formatted": null,
12  "id": "phon_MiLNdBqo8utNOf1U78RaZgQB1Iq6rRGftiDW5C8B9uL",
13  "is_group_number": false,
14  "is_premium": false,
15  "is_verified": true,
16  "label": null,
17  "last_billed_price": null,
18  "mms_enabled": true,
19  "next_billing_on": null,
20  "number": "+16503335555",
21  "number_formatted": "+1 650-333-5555",
22  "organization_id": "orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH",
23  "press_1_to_accept": false,
24  "sms_enabled": true,
25  "supports_mms_to_countries": [
26    "CA",
27    "US"
28  ],
29  "supports_sms_to_countries": [
30    "CA",
31    "PR",
32    "US"
33  ],
34  "type": "internal",
35  "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
36  "voicemail_greeting_url": null
37}
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.
Was this page helpful?
Previous

List or search for phone numbers

Next

Retrieve a single phone number

Built with

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.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
countrystringRequired

A two letter ISO country code (e.g. US for United States).

sharingenumRequired

personal for a number that belongs to an individual user, or group for a group number.

Allowed values:
bundle_idstring or nullOptional
carrier_typeenum or nullOptional
Allowed values:
prefixstringOptional<=5 charactersDefaults to
A string with the phone number prefix or area code, not including the country code.
with_mmsboolean or nullOptional

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_smsboolean or nullOptional

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

Successful response

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error