API reference

Carrier API overview

The /carrier/v1 API lets carriers manage their entire platform: accounts, phone numbers, rates, ring groups, SIP trunks, billing balances, and more.

Base URL & auth

https://voice.ruut.chat/carrier/v1

Authenticate with a carrier-scoped API key (OAuth2 bearer token with the carrier_api scope). See API authentication.

Authbash

curl "https://voice.ruut.chat/carrier/v1/accounts" \
  -H "Authorization: Bearer $CARRIER_API_KEY"

Resources

Resource	Base path	Reference
Accounts	`/accounts`	accounts
Phone numbers	`/phone_numbers`	phone numbers
Phone calls	`/phone_calls`	phone calls
Messages	`/messages`	messages
Rates	`/rates`	rates
Ring groups	`/accounts/{id}/ring_groups`	ring groups
SIP trunks	`/sip_trunks`	SIP trunks
TTS events	`/tts_events`	TTS events
Events	`/events`	events
Balances	`/accounts/{id}/balances`	balances
Agent extensions	`/accounts/{id}/agent_extensions`	agent extensions

Request format

Carrier API requests use JSON bodies (JSON:API style), with the resource nested under a data key:

Requestjson

{
  "data": {
    "type": "phone_number",
    "attributes": {
      "number": "+23412000000",
      "country": "NG",
      "visibility": "public",
      "price": "5000.00"
    }
  }
}

Responses

Responses follow JSON:API conventions:

Responsejson

{
  "data": {
    "id": "PN…",
    "type": "phone_number",
    "attributes": { "number": "+23412000000", "status": "available" }
  }
}

Collection responses nest the list under data (an array). Errors use the JSON:API error format (see errors).

The carrier API is separate from the customer-facing Twilio-compatible REST API. Use the Twilio API for call/message/recording operations; use the carrier API for provisioning and billing.