> For a complete page index, fetch https://developer.close.com/llms.txt # 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. The new number is assigned to you unless you name other users via `assign_to`, which requires the "Manage Team Phone Numbers" permission. 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 ## Authentication - `Authorization` header (basic auth, required) — Use your API key as the username and leave the password empty. - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects a CreatePhoneNumberRequest. - `country` (string, required) — A two letter ISO country code (e.g. `US` for United States). - `assign_to` (list of string, optional, nullable) — IDs of the users the new phone number is assigned to. When omitted, the number is assigned to the user making the request. Assigning it to anyone else requires the "Manage Team Phone Numbers" permission, and every user must be an active member of the organization who is allowed to make calls. - `bundle_id` (string, optional, nullable) - `carrier_type` (enum, optional, nullable) - Allowed values: `local`, `national`, `mobile`, `tollfree` - `prefix` (string, optional, default: ) — A string with the phone number prefix or area code, not including the country code. - `with_mms` (boolean, optional, nullable) — 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` (boolean, optional, nullable) — 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. - `sharing` (enum, optional, deprecated) — 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`. - Allowed values: `personal`, `group` ## Response ### 201 Successful response ## Errors ### 400 Bad Request Error Bad request - `any` ### 401 Unauthorized Error Unauthorized - `any` ### 404 Not Found Error Not found - `any` ## Examples **Request** ```json { "country": "US", "prefix": "650", "sharing": "personal" } ``` **Response** ```json { "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", "participant_groups": [], "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 } ``` **SDK Code** ```python phone_numbers_create_example import requests url = "https://api.close.com/api/v1/phone_number/request/internal/" payload = { "country": "US", "prefix": "650", "sharing": "personal" } headers = { "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, auth=("", "")) print(response.json()) ``` ```javascript phone_numbers_create_example const url = 'https://api.close.com/api/v1/phone_number/request/internal/'; const credentials = btoa(":"); const options = { method: 'POST', headers: {Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json'}, body: '{"country":"US","prefix":"650","sharing":"personal"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go phone_numbers_create_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.close.com/api/v1/phone_number/request/internal/" payload := strings.NewReader("{\n \"country\": \"US\",\n \"prefix\": \"650\",\n \"sharing\": \"personal\"\n}") req, _ := http.NewRequest("POST", url, payload) req.SetBasicAuth("", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby phone_numbers_create_example require 'uri' require 'net/http' url = URI("https://api.close.com/api/v1/phone_number/request/internal/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request.basic_auth("", "") request["Content-Type"] = 'application/json' request.body = "{\n \"country\": \"US\",\n \"prefix\": \"650\",\n \"sharing\": \"personal\"\n}" response = http.request(request) puts response.read_body ``` ```java phone_numbers_create_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.close.com/api/v1/phone_number/request/internal/") .basicAuth("", "") .header("Content-Type", "application/json") .body("{\n \"country\": \"US\",\n \"prefix\": \"650\",\n \"sharing\": \"personal\"\n}") .asString(); ``` ```php phone_numbers_create_example request('POST', 'https://api.close.com/api/v1/phone_number/request/internal/', [ 'body' => '{ "country": "US", "prefix": "650", "sharing": "personal" }', 'headers' => [ 'Content-Type' => 'application/json', ], 'auth' => ['', ''], ]); echo $response->getBody(); ``` ```csharp phone_numbers_create_example using RestSharp; using RestSharp.Authenticators; var client = new RestClient("https://api.close.com/api/v1/phone_number/request/internal/"); client.Authenticator = new HttpBasicAuthenticator("", ""); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"country\": \"US\",\n \"prefix\": \"650\",\n \"sharing\": \"personal\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ```