Trillet AI logo

Bring Your Own Number

Register a phone number you already own (Twilio, Telnyx or your own SIP trunk) so your agents can use it.

POSThttps://api.trillet.ai/v1/api/twilio/register-external-number

Register a number from your own Twilio account, your own Telnyx account, or any SIP trunk. Numbers you bring yourself cost nothing on Trillet (monthlyPrice is 0). After registering, bind an agent to it with Update Phone Number Configuration.

A number can be registered only once across all of Trillet.

Your role needs the phone_number:create permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

phoneNumberstringrequired

The number to register, in E.164 format, for example +14155550123.

providerstringrequired

twilio, telnyx or sip.

credentialsobjectrequired

The credentials for the provider. Always send an object, even an empty one.

workspaceIdstring

Optional. If sent, it must equal x-workspace-id, otherwise the request fails with 403.

Response Fields

The response status is 201.

messagestring

<provider> phone number registered successfully.

phoneNumberstring

The registered number.

idstring

The new phone number's _id. Use it as phoneNumberId in Update Phone Number Configuration.

statusstring

Always active in this response. A Twilio number is stored as ready until you bind an agent to it; check the stored value with List Phone Numbers.

monthlyPricenumber

Always 0.

Errors

StatusBodyWhen
400{"error": "Phone number, provider type, and workspace ID are required."}phoneNumber or provider missing
400{"error": "Invalid workspace ID", "message": "..."}x-workspace-id missing or malformed
403{"error": "workspaceId in the request body does not match x-workspace-id."}Body workspaceId differs from the header
500{"error": "..."}Any other failure, with the reason in error

Example Request

Twilio
{
  "phoneNumber": "+14155550123",
  "provider": "twilio",
  "credentials": {
    "accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "authToken": "your_twilio_auth_token"
  }
}
SIP trunk
{
  "phoneNumber": "+14155550123",
  "provider": "sip",
  "credentials": {
    "sipUri": "sip:pbx.example.com",
    "username": "trillet",
    "password": "your_sip_password",
    "ipAddresses": [
      { "id": "pbx-1", "ip": "203.0.113.10", "subnetMask": "32" }
    ],
    "sipType": "direct"
  }
}

Example Response

{
  "message": "twilio phone number registered successfully",
  "phoneNumber": "+14155550123",
  "id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "status": "active",
  "monthlyPrice": 0
}

Last updated on