Sign in

API reference

The CFBTEL Voice & Messaging REST API. It follows the widely used 2010-04-01 telephony REST conventions, so existing code and standard helper libraries work by changing the base URL: resource names, parameters, SIDs, XML instructions and webhook signatures are the same.

Contents: Base URL · Authentication · Webhooks · Event Streams · Debugger · IP addresses · XML instructions · Endpoints · Errors · Limits

Base URL

All requests go to https://api.cfbrun.com. Paths follow the 2010-04-01 API, for example https://api.cfbrun.com/2010-04-01/Accounts/{AccountSid}/Messages.json. Messaging Services use https://api.cfbrun.com/v1/Services.

Helper libraries that let you change the API host work by pointing them at api.cfbrun.com; any HTTP client works with the REST calls below.

curl -X POST https://api.cfbrun.com/2010-04-01/Accounts/$ACCOUNT_SID/Messages.json \
  -u "$ACCOUNT_SID:$AUTH_TOKEN" \
  --data-urlencode "To=+19495550100" --data-urlencode "From=+19495550199" \
  --data-urlencode "Body=Hello"

Authentication

HTTP Basic auth with either your Account SID and Auth Token, or an API key: the key SID (SK…) as the username and its secret as the password. Create keys and rotate the token under API credentials in the portal.

If you add addresses to the IP allowlist, requests from anywhere else are refused with HTTP 403 (error 20003), even with valid credentials.

Webhooks

We call your VoiceUrl, SmsUrl and status callbacks with these form parameters (CallSid, From, To, CallStatus, MessageSid, Body, NumMedia, MediaUrl0…). Reply to voice webhooks with XML instructions and to messaging webhooks with XML or an empty 200.

Every request carries X-CFBTEL-Signature: base64 HMAC-SHA1, keyed with your Auth Token, of the full URL followed by each POST parameter name and value sorted by name. Standard request-validation helpers work unchanged.

Voice webhooks must answer within 6 seconds; if they fail, we try the fallback URL. Status callbacks that fail are retried up to 6 times over about 45 minutes. Every delivery is listed under Webhooks in the portal.

Event Streams

Receive everything that happens on your account at one URL, using the Event Streams API: create a sink (POST /v1/Sinks, SinkType webhook) and a subscription listing the event types you want (POST /v1/Subscriptions). GET /v1/Types lists the types: call ringing and completed, inbound texts, message queued / sent / delivered / undelivered / failed, recordings, opt-outs, number changes and Debugger errors.

Each delivery is a JSON array of CloudEvents, POSTed to your URL with ?bodySHA256= appended and signed with X-CFBTEL-Signature (HMAC-SHA1 of the full URL, and the body's SHA-256 must match bodySHA256). Failed deliveries are retried for about 7 hours. You can also manage destinations, see every delivery and resend from Workbench → Webhooks in the portal.

Debugger and request IDs

Every API response carries a CFBTEL-Request-Id header (RQ…); find the request with its parameters and our response in Workbench → Logs (kept 30 days).

Errors and warnings (failed webhooks, invalid XML instructions, carrier delivery failures, API errors) are logged in the Debugger, with the request we made and the response we got. Read them with the Monitor Alerts API (GET /v1/Alerts, GET /v1/Alerts/{Sid}), subscribe to com.cfbtel.error-logs.error.logged, or set a Debugger webhook under Workbench → Health → Settings.

IP addresses

Allow these on your firewall if you restrict who can reach your webhook URLs:

AddressUsed for
167.114.17.11Webhooks and status callbacks from api.cfbrun.com

We announce changes to this list in the release notes before they happen.

XML instructions

Supported verbs: <Say> (natural voices; voice="Joanna-Neural" and the man/woman/alice names), <Play>, <Pause>, <Dial> with <Number> (record, timeout, callerId, action, whisper via url), <Redirect>, <Reject>, <Hangup>, and for messaging <Message>. Recordings are dual-channel MP3.

Endpoints

Account

GET/2010-04-01/Accounts/{AccountSid}.jsonGet account

Phone numbers

GET/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.jsonList my phone numbers
GET/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/US/Local.jsonSearch available numbers
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.jsonBuy a number
Use PhoneNumber=+1… instead of AreaCode to buy an exact number.
GET/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/US/Local.jsonSearch vanity numbers
Contains takes 3–7 letters or digits; *1234 means "ends in 1234". Letters map to keypad digits.
GET/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/US/TollFree.jsonSearch toll-free numbers
AreaCode 800/833/844/855/866/877/888, or Contains with a 4–7 letter word.
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/TollFree.jsonBuy a toll-free number
GET/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.jsonGet a phone number
POST/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.jsonUpdate a number’s webhooks
Leave a field empty to clear it; remove the line to leave it unchanged.
DELETE/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{PhoneNumberSid}.jsonRelease a number

Messaging

POST/2010-04-01/Accounts/{AccountSid}/Messages.jsonSend an SMS
Use MessagingServiceSid instead of From to send from a pool. Add MediaUrl for MMS.
GET/2010-04-01/Accounts/{AccountSid}/Messages.jsonList messages
GET/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}.jsonGet a message
GET/2010-04-01/Accounts/{AccountSid}/OptOuts.jsonList opt-outs
Scope is a sending number, a Messaging Service SID, or * for the whole account.
POST/2010-04-01/Accounts/{AccountSid}/OptOuts.jsonAdd opt-outs
Up to 10,000 numbers per request, separated by commas or new lines.
DELETE/2010-04-01/Accounts/{AccountSid}/OptOuts/{Contact}Remove an opt-out
GET/v1/ServicesList messaging services
POST/v1/ServicesCreate a messaging service
POST/v1/Services/{MessagingServiceSid}/PhoneNumbersAdd a number to a service

Calls

GET/2010-04-01/Accounts/{AccountSid}/Calls.jsonList calls
GET/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.jsonGet a call
GET/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.jsonRecordings for a call
GET/2010-04-01/Accounts/{AccountSid}/Recordings.jsonList recordings
GET/2010-04-01/Accounts/{AccountSid}/Recordings/{RecordingSid}.jsonGet a recording
The audio is at the same URL without .json (or with .mp3).

Usage

GET/2010-04-01/Accounts/{AccountSid}/Usage/Records/ThisMonth.jsonUsage this month
GET/2010-04-01/Accounts/{AccountSid}/Usage/Records/Daily.jsonDaily usage
Categories: calls-inbound, sms-inbound, sms-outbound, mms-inbound, mms-outbound, recordings, phonenumbers. Dates are YYYY-MM-DD.
GET/2010-04-01/Accounts/{AccountSid}/Usage/Records.jsonUsage for a date range

Applications

GET/2010-04-01/Accounts/{AccountSid}/Applications.jsonList applications
POST/2010-04-01/Accounts/{AccountSid}/Applications.jsonCreate an application
Point numbers at it with VoiceApplicationSid / SmsApplicationSid.

Events

GET/v1/TypesList event types
GET/v1/SinksList sinks (event destinations)
POST/v1/SinksCreate a webhook sink
Deliveries are a JSON array of CloudEvents signed with X-CFBTEL-Signature (URL + bodySHA256).
POST/v1/SubscriptionsSubscribe a sink to event types
Repeat Types for each event type (one per line).
POST/v1/Sinks/{SinkSid}/TestSend a test event to a sink

Debugger

GET/v1/AlertsList Debugger alerts
LogLevel is error or warning; StartDate/EndDate filter by time (ISO 8601).
GET/v1/Alerts/{AlertSid}Get one alert (with request and response)

Lists are paged with PageSize (up to 1000) and Page, and return next_page_uri.

Errors

Errors are JSON with a numeric code: {"code": 21211, "message": "...", "more_info": "...", "status": 400}.

20003Authentication failed, or your IP is not on the allowlist
20404The resource was not found
21211Invalid To number
21606The From number is not on your account or cannot send texts
21452No numbers match that search
21610The recipient has opted out (replied STOP)
30003–30008Delivery failures reported by the carrier (in status callbacks)

Limits

Texts are queued and paced so carriers do not filter them: by default 1 message per second per local number, 3 per second per toll-free number, and 10 per second per account. Higher rates follow your 10DLC registration; ask CFBTEL to raise them. Requests are never rejected for speed: they wait their turn and keep status "queued".