Twilio & Compliance API Documentation

🔧 INTERNAL

🤖

📞

Twilio API Documentation

Complete reference for Twilio SMS, Voice, and webhook integration

🏠 Dashboard 💬 SMS Agent 📱 Voice

Twilio & Compliance API

Complete API for managing A2P brands, campaigns, and phone numbers

Introduction

The CloudFran Twilio & Compliance API allows CloudFran customers to programmatically manage all aspects of Twilio services including A2P brand registration, campaign management, phone number purchasing, and compliance operations.

Base URL: https://your-domain.com/api/v1/twilio

This API enables you to:

Register and manage A2P brands ($12 one-time fee)
Create and manage messaging campaigns ($20-30/month)
Purchase and manage phone numbers ($24-48/year)
Handle cancellations with 60-day policy
Reclaim cancelled numbers within 30 days ($25 fee)
Export SMS and call data

Authentication

🔐 API Key Authentication

All API requests require authentication using API keys passed in the request headers:

X-API-Key: Your API key (obtained from CloudFran dashboard)
X-Tenant-Id: Your tenant identifier

Note: Keep your API keys secure. Never share them in public repositories or client-side code.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format:

Status Code	Meaning
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
500	Internal Server Error - Something went wrong on our end

Error Response Format:

{
  "error": "invalid_api_key",
  "message": "Invalid or missing API key"
}

POST /brands

Request Parameters

Parameter	Type	Description
tenantIdrequired	string	Your tenant identifier
businessNamerequired	string	Legal business name
emailrequired	string	Business email address
phonerequired	string	Business phone number
einrequired	string	Employer Identification Number
businessTyperequired	string	Business type (LLC, Corporation, etc.)
websiterequired	string	Business website URL
addressrequired	string	Business street address
cityrequired	string	City
staterequired	string	State (2-letter code)
zipCoderequired	string	ZIP code
webhookUrl	string	Optional webhook URL for status updates

POST /campaigns

Create a new A2P messaging campaign associated with a brand. Marketing: $30/month | Non-Marketing: $20/month

Request Parameters

Parameter	Type	Description
tenantIdrequired	string	Your tenant identifier
brandSidrequired	string	Brand SID from brand registration
campaignNamerequired	string	Campaign name
descriptionrequired	string	Campaign description
useCaserequired	string	MARKETING or other use case
messageSamplesrequired	array	Array of sample messages (at least 2)
hasEmbeddedLinks	boolean	Messages contain links
hasEmbeddedPhone	boolean	Messages contain phone numbers

GET /phone-numbers/available

Search for available phone numbers to purchase.

Query Parameters

Parameter	Type	Description
areaCoderequired	string	Desired area code (e.g., 415)
type	string	Number type: "local" or "tollfree" (default: local)
limit	integer	Number of results (default: 10, max: 10)

POST /phone-numbers

Purchase and provision a phone number. Local: $24/year | Toll-Free: $48/year

Request Parameters

Parameter	Type	Description
tenantIdrequired	string	Your tenant identifier
phoneNumberrequired	string	Phone number in E.164 format (e.g., +15551234567)
email	string	Billing email address
webhookUrl	string	Optional webhook URL for status updates

GET /phone-numbers

Get all phone numbers for your account.

Query Parameters

Parameter	Type	Description
status	string	Filter by status: "active", "pending_cancellation", "cancelled_held", "released", or "all" (default)

POST /phone-numbers/{serviceId}/cancel

Request cancellation of a phone number. 60-day notice required. You will continue to be billed during this period. Data will be automatically exported 24 hours before cancellation.

⏱️ 60-Day Cancellation Policy

When you cancel a phone number:

Cancellation takes effect in 60 days
You continue to be billed during the 60-day period
SMS and call logs are auto-exported 24 hours before effective date
Number enters 30-day hold period after cancellation
Can reclaim during hold period for $25 fee

POST /phone-numbers/{serviceId}/undo-cancel

Undo a pending cancellation before the 60-day effective date. Number will remain active.

POST /phone-numbers/{serviceId}/reclaim

Reclaim a cancelled number within the 30-day hold period. Reclaim fee: $25

Request Parameters

Parameter	Type	Description
email	string	Billing email for $25 reclaim fee

💰 30-Day Hold Period

After the 60-day cancellation period:

Number enters 30-day hold period
Number is not billed during hold
Can reclaim for one-time $25 fee
After 30 days, number is permanently released

POST /phone-numbers/{serviceId}/export

Export all SMS and call logs for a phone number to CSV format.

GET /usage/monthly

Retrieve monthly usage and billing summary for your account.

Webhooks

CloudFran sends webhook events to your specified URL when important events occur:

Event	Description
brand.registered	A2P brand registration completed
campaign.registered	A2P campaign registration completed
phone_number.purchased	Phone number successfully purchased
phone_number.cancelled	Phone number cancellation processed
number.reclaimed	Phone number reclaimed from hold period

Webhook Payload Format:

{
  "event": "phone_number.purchased",
  "tenantId": "your_tenant_id",
  "phoneNumber": "+15551234567",
  "serviceId": "uuid...",
  "numberSid": "PN...",
  "annualFee": 24.00,
  "timestamp": "2025-11-04T20:00:00Z"
}

curl -X POST \
  https://your-domain.com/api/v1/twilio/brands \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": "your_tenant_id",
    "businessName": "Acme Corporation",
    "email": "compliance@acme.com",
    "phone": "+15551234567",
    "ein": "12-3456789",
    "businessType": "LLC",
    "website": "https://acme.com",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102"
  }'

Response (200 OK)

{
  "success": true,
  "brandSid": "BN...",
  "serviceId": "uuid...",
  "status": "pending",
  "fee": 12.00,
  "paymentIntentId": "pi_..."
}

Purchase Phone Number

curl -X POST \
  https://your-domain.com/api/v1/twilio/phone-numbers \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantId": "your_tenant_id",
    "phoneNumber": "+15551234567",
    "email": "billing@acme.com"
  }'

List Phone Numbers

curl -X GET \
  https://your-domain.com/api/v1/twilio/phone-numbers?status=active \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id'

Cancel Phone Number

curl -X POST \
  https://your-domain.com/api/v1/twilio/phone-numbers/{serviceId}/cancel \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id'

Reclaim Number ($25)

curl -X POST \
  https://your-domain.com/api/v1/twilio/phone-numbers/{serviceId}/reclaim \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "billing@acme.com"
  }'

Monthly Usage

curl -X GET \
  https://your-domain.com/api/v1/twilio/usage/monthly \
  -H 'X-API-Key: your_api_key' \
  -H 'X-Tenant-Id: your_tenant_id'