Skip to main content
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",
  "type": "local",
  "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>"
    }
  ]
}
'
{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.mindhunters.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Use a Bearer token to access these API endpoints. Example: "Bearer {your-token}"

Body

application/json
​
number
string
required

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"

​
country_code
string
required

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"

​
type
enum<string>
required

Number category from the search result. Drives which compliance requirements apply.

Available options:
local,
toll_free,
mobile,
national
​
monthly_fee
number<float>

Monthly fee value carried over from the search result. Stored on the inventory row for billing display. The first active number in your workspace is free regardless of this value.

​
capabilities
object

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.

​
location
string

Optional human-friendly location label, e.g. Sassari, Sardegna. Defaults to the country code if omitted.

​
address
object

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.

​
requirements
object[]

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).

Response

Number purchased

​
success
boolean

Indicates whether the request completed successfully. True for successful responses; false for documented error responses.

​
data
object

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.