Register an external SIP trunk / BYO number

curl --request POST \
  --url https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+12345678901",
  "agent_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "sip": {
    "gateway": "sip.acme.com",
    "port": 5060,
    "username": "<string>",
    "password": "<string>",
    "secondary_gateway": "<string>"
  },
  "additional_settings": {}
}
'

import requests

url = "https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks"

payload = {
    "phone_number": "+12345678901",
    "agent_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "sip": {
        "gateway": "sip.acme.com",
        "port": 5060,
        "username": "<string>",
        "password": "<string>",
        "secondary_gateway": "<string>"
    },
    "additional_settings": {}
}
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({
    phone_number: '+12345678901',
    agent_uuid: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    name: '<string>',
    sip: {
      gateway: 'sip.acme.com',
      port: 5060,
      username: '<string>',
      password: '<string>',
      secondary_gateway: '<string>'
    },
    additional_settings: {}
  })
};

fetch('https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks', 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/trunks",
  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([
    'phone_number' => '+12345678901',
    'agent_uuid' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'name' => '<string>',
    'sip' => [
        'gateway' => 'sip.acme.com',
        'port' => 5060,
        'username' => '<string>',
        'password' => '<string>',
        'secondary_gateway' => '<string>'
    ],
    'additional_settings' => [
        
    ]
  ]),
  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/trunks"

	payload := strings.NewReader("{\n  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\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/trunks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks")

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  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "data": {
    "phone_number_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": "<string>",
    "is_external": true,
    "channels": {
      "call": {
        "capable": true,
        "enabled": true,
        "channel_limit": 123,
        "whitelisted_destinations": [
          "US"
        ],
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "sms": {
        "capable": true,
        "enabled": true,
        "channel_limit": 123,
        "whitelisted_destinations": [
          "<string>"
        ],
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "whatsapp": {
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "inbound": {
        "enabled": true,
        "channel_limit": 123
      }
    }
  }
}

POST

api

phone-numbers

trunks

curl --request POST \
  --url https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+12345678901",
  "agent_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "sip": {
    "gateway": "sip.acme.com",
    "port": 5060,
    "username": "<string>",
    "password": "<string>",
    "secondary_gateway": "<string>"
  },
  "additional_settings": {}
}
'

import requests

url = "https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks"

payload = {
    "phone_number": "+12345678901",
    "agent_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "sip": {
        "gateway": "sip.acme.com",
        "port": 5060,
        "username": "<string>",
        "password": "<string>",
        "secondary_gateway": "<string>"
    },
    "additional_settings": {}
}
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({
    phone_number: '+12345678901',
    agent_uuid: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    name: '<string>',
    sip: {
      gateway: 'sip.acme.com',
      port: 5060,
      username: '<string>',
      password: '<string>',
      secondary_gateway: '<string>'
    },
    additional_settings: {}
  })
};

fetch('https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks', 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/trunks",
  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([
    'phone_number' => '+12345678901',
    'agent_uuid' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'name' => '<string>',
    'sip' => [
        'gateway' => 'sip.acme.com',
        'port' => 5060,
        'username' => '<string>',
        'password' => '<string>',
        'secondary_gateway' => '<string>'
    ],
    'additional_settings' => [
        
    ]
  ]),
  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/trunks"

	payload := strings.NewReader("{\n  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\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/trunks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{subdomain}.mihu.ai/api/v1/phone-numbers/trunks")

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  \"phone_number\": \"+12345678901\",\n  \"agent_uuid\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"name\": \"<string>\",\n  \"sip\": {\n    \"gateway\": \"sip.acme.com\",\n    \"port\": 5060,\n    \"username\": \"<string>\",\n    \"password\": \"<string>\",\n    \"secondary_gateway\": \"<string>\"\n  },\n  \"additional_settings\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "data": {
    "phone_number_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "number": "<string>",
    "is_external": true,
    "channels": {
      "call": {
        "capable": true,
        "enabled": true,
        "channel_limit": 123,
        "whitelisted_destinations": [
          "US"
        ],
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "sms": {
        "capable": true,
        "enabled": true,
        "channel_limit": 123,
        "whitelisted_destinations": [
          "<string>"
        ],
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "whatsapp": {
        "bound": true,
        "agent_uuid": "<string>",
        "agent_name": "<string>"
      },
      "inbound": {
        "enabled": true,
        "channel_limit": 123
      }
    }
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

phone_number

string

required

The external phone number to register, in E.164 format. Must NOT already be in your purchased inventory or bound on the same channel.

Example:

"+12345678901"

agent_uuid

string<uuid>

required

UUID of the agent that will answer traffic on this trunk. The agent must not already serve another number on the same channel.

channel

enum<string>

required

Which channel this trunk handles. One trunk row per (number, channel) pair — you can register the same number on call+whatsapp by calling this twice. SMS is not supported on the trunk endpoints; use POST /api/v1/agents/{uuid}/channels/sms instead.

Available options:

call,

whatsapp

name

string

Friendly label for the trunk, surfaced in dashboards and logs. Defaults to {channel}_trunk_{digits} if omitted (e.g. call_trunk_12345678901).

direction

enum<string>

Call-channel only. Whether this trunk handles inbound, outbound, or both. Defaults to both. Ignored for WhatsApp.

Available options:

inbound,

outbound,

both

sip

object

Optional SIP credentials for the call channel. All fields are encrypted at rest. Omit if you only want to register the binding without storing credentials.

Show child attributes

additional_settings

object

Free-form JSON stored on the binding. Use for channel-specific extras (for example, an ani_format: e164 flag).

Response

Trunk created

success

boolean

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

message

string

Human-readable response message. Safe to display in logs or simple client notifications; use structured fields for program logic.

data

object

Per-channel snapshot returned by /phone-numbers/{uuid}/channels, /phone-numbers/channels?number=…, and the trunk create/update/assign endpoints. Combines capability (what the carrier supports), state (what's enabled), and binding (which agent is wired up).

Show child attributes

List external trunks (BYO numbers)Delete an external trunk

API Documentation

API Reference

Register an external SIP trunk / BYO number

Authorizations

Body

Response