Buy a phone number
curl --request POST \
--url https://{subdomain}.mihu.ai/api/v1/phone-numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "+390790080041",
"country_code": "IT",
"monthly_fee": 123,
"capabilities": {},
"location": "<string>",
"address": {
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"phone_number": "<string>",
"street_address": "<string>",
"extended_address": "<string>",
"locality": "<string>",
"administrative_area": "<string>",
"postal_code": "<string>",
"country_code": "IT"
},
"requirements": [
{
"key": "proof_of_address",
"requirement_id": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"value": "<string>",
"document_id": "<string>"
}
]
}
'import requests
url = "https://{subdomain}.mihu.ai/api/v1/phone-numbers"
payload = {
"number": "+390790080041",
"country_code": "IT",
"monthly_fee": 123,
"capabilities": {},
"location": "<string>",
"address": {
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"phone_number": "<string>",
"street_address": "<string>",
"extended_address": "<string>",
"locality": "<string>",
"administrative_area": "<string>",
"postal_code": "<string>",
"country_code": "IT"
},
"requirements": [
{
"key": "proof_of_address",
"requirement_id": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"value": "<string>",
"document_id": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
number: '+390790080041',
country_code: 'IT',
monthly_fee: 123,
capabilities: {},
location: '<string>',
address: {
first_name: '<string>',
last_name: '<string>',
business_name: '<string>',
phone_number: '<string>',
street_address: '<string>',
extended_address: '<string>',
locality: '<string>',
administrative_area: '<string>',
postal_code: '<string>',
country_code: 'IT'
},
requirements: [
{
key: 'proof_of_address',
requirement_id: '9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b',
value: '<string>',
document_id: '<string>'
}
]
})
};
fetch('https://{subdomain}.mihu.ai/api/v1/phone-numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{subdomain}.mihu.ai/api/v1/phone-numbers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'number' => '+390790080041',
'country_code' => 'IT',
'monthly_fee' => 123,
'capabilities' => [
],
'location' => '<string>',
'address' => [
'first_name' => '<string>',
'last_name' => '<string>',
'business_name' => '<string>',
'phone_number' => '<string>',
'street_address' => '<string>',
'extended_address' => '<string>',
'locality' => '<string>',
'administrative_area' => '<string>',
'postal_code' => '<string>',
'country_code' => 'IT'
],
'requirements' => [
[
'key' => 'proof_of_address',
'requirement_id' => '9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b',
'value' => '<string>',
'document_id' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{subdomain}.mihu.ai/api/v1/phone-numbers"
payload := strings.NewReader("{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{subdomain}.mihu.ai/api/v1/phone-numbers")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{subdomain}.mihu.ai/api/v1/phone-numbers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"phone_number_uuid": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"number": "+12084439178",
"country_code": "US",
"location": "Sassari, Sardegna",
"type": "local",
"is_external": true,
"source": "purchased",
"status": "active",
"compliance": {
"status": "completed",
"requirements": [
{
"name": "<string>",
"type": "textual",
"description": "<string>"
}
]
},
"capabilities": {
"voice": true,
"sms": true,
"mms": true,
"fax": true,
"emergency": true,
"local_calling": true
},
"channel_settings": {
"voice": {
"enabled": true,
"channel_limit": 123,
"whitelisted_destinations": [
"US"
]
},
"sms": {
"enabled": true,
"channel_limit": 123,
"whitelisted_destinations": [
"US"
]
},
"inbound": {
"enabled": true,
"channel_limit": 123
}
},
"billing": {
"monthly_fee": 123,
"currency": "EUR"
},
"bindings": {
"call": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
},
"sms": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
},
"whatsapp": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
}
},
"purchased_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}Phone Numbers
Buy a phone number
Purchases a number returned by the search endpoint. If the country/type requires compliance, include an address (when needed) and a list of requirement values — text answers and document IDs from /api/v1/phone-numbers/documents.
POST
/
api
/
v1
/
phone-numbers
Buy a phone number
curl --request POST \
--url https://{subdomain}.mihu.ai/api/v1/phone-numbers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "+390790080041",
"country_code": "IT",
"monthly_fee": 123,
"capabilities": {},
"location": "<string>",
"address": {
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"phone_number": "<string>",
"street_address": "<string>",
"extended_address": "<string>",
"locality": "<string>",
"administrative_area": "<string>",
"postal_code": "<string>",
"country_code": "IT"
},
"requirements": [
{
"key": "proof_of_address",
"requirement_id": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"value": "<string>",
"document_id": "<string>"
}
]
}
'import requests
url = "https://{subdomain}.mihu.ai/api/v1/phone-numbers"
payload = {
"number": "+390790080041",
"country_code": "IT",
"monthly_fee": 123,
"capabilities": {},
"location": "<string>",
"address": {
"first_name": "<string>",
"last_name": "<string>",
"business_name": "<string>",
"phone_number": "<string>",
"street_address": "<string>",
"extended_address": "<string>",
"locality": "<string>",
"administrative_area": "<string>",
"postal_code": "<string>",
"country_code": "IT"
},
"requirements": [
{
"key": "proof_of_address",
"requirement_id": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"value": "<string>",
"document_id": "<string>"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
number: '+390790080041',
country_code: 'IT',
monthly_fee: 123,
capabilities: {},
location: '<string>',
address: {
first_name: '<string>',
last_name: '<string>',
business_name: '<string>',
phone_number: '<string>',
street_address: '<string>',
extended_address: '<string>',
locality: '<string>',
administrative_area: '<string>',
postal_code: '<string>',
country_code: 'IT'
},
requirements: [
{
key: 'proof_of_address',
requirement_id: '9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b',
value: '<string>',
document_id: '<string>'
}
]
})
};
fetch('https://{subdomain}.mihu.ai/api/v1/phone-numbers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{subdomain}.mihu.ai/api/v1/phone-numbers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'number' => '+390790080041',
'country_code' => 'IT',
'monthly_fee' => 123,
'capabilities' => [
],
'location' => '<string>',
'address' => [
'first_name' => '<string>',
'last_name' => '<string>',
'business_name' => '<string>',
'phone_number' => '<string>',
'street_address' => '<string>',
'extended_address' => '<string>',
'locality' => '<string>',
'administrative_area' => '<string>',
'postal_code' => '<string>',
'country_code' => 'IT'
],
'requirements' => [
[
'key' => 'proof_of_address',
'requirement_id' => '9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b',
'value' => '<string>',
'document_id' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{subdomain}.mihu.ai/api/v1/phone-numbers"
payload := strings.NewReader("{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{subdomain}.mihu.ai/api/v1/phone-numbers")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{subdomain}.mihu.ai/api/v1/phone-numbers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"number\": \"+390790080041\",\n \"country_code\": \"IT\",\n \"monthly_fee\": 123,\n \"capabilities\": {},\n \"location\": \"<string>\",\n \"address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"business_name\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"street_address\": \"<string>\",\n \"extended_address\": \"<string>\",\n \"locality\": \"<string>\",\n \"administrative_area\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country_code\": \"IT\"\n },\n \"requirements\": [\n {\n \"key\": \"proof_of_address\",\n \"requirement_id\": \"9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b\",\n \"value\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"phone_number_uuid": "9bcb8f00-c0c5-4ee1-9b75-ad1e87a2bd8b",
"number": "+12084439178",
"country_code": "US",
"location": "Sassari, Sardegna",
"type": "local",
"is_external": true,
"source": "purchased",
"status": "active",
"compliance": {
"status": "completed",
"requirements": [
{
"name": "<string>",
"type": "textual",
"description": "<string>"
}
]
},
"capabilities": {
"voice": true,
"sms": true,
"mms": true,
"fax": true,
"emergency": true,
"local_calling": true
},
"channel_settings": {
"voice": {
"enabled": true,
"channel_limit": 123,
"whitelisted_destinations": [
"US"
]
},
"sms": {
"enabled": true,
"channel_limit": 123,
"whitelisted_destinations": [
"US"
]
},
"inbound": {
"enabled": true,
"channel_limit": 123
}
},
"billing": {
"monthly_fee": 123,
"currency": "EUR"
},
"bindings": {
"call": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
},
"sms": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
},
"whatsapp": {
"bound": true,
"agent_uuid": "<string>",
"agent_name": "<string>"
}
},
"purchased_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}Authorizations
Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}"
Body
application/json
The exact E.164 number to purchase, returned by GET /phone-numbers/search. The endpoint refuses if the same number already exists in your inventory or as an external trunk.
Example:
"+390790080041"
ISO 3166-1 alpha-2 country code the number belongs to. Used to fetch regulatory requirements and as the default for the address country_code.
Example:
"IT"
Number category from the search result. Drives which compliance requirements apply.
Available options:
local, toll_free, mobile, national Monthly subscription price displayed in Buy Number, in the workspace billing currency.
Capability flags object copied from the search result (voice, sms, mms, etc.). Indicates which channels the number supports. Optional — when omitted, channel capabilities are unknown until the number is purchased.
Optional human-friendly location label, e.g. Sassari, Sardegna. Defaults to the country code if omitted.
Compliance address. Required when the country/type combination needs one (check GET /phone-numbers/search/requirements). All fields are individually optional — provide as many as the carrier requires.
Show child attributes
Show child attributes
Compliance requirement values. One entry per requirement listed in GET /phone-numbers/search/requirements. Each entry identifies the requirement (by key slug or stable requirement_id) and supplies the value (text answer or uploaded document id).
Show child attributes
Show child attributes
Response
Number purchased
Indicates whether the request completed successfully. True for successful responses; false for documented error responses.
A phone number connected to your workspace. Always returned by inventory and lookup endpoints. The shape is the same for purchased and external (trunk) numbers — fields that don't apply to externals come back as null.
Show child attributes
Show child attributes
⌘I