API Reference
RESTful endpoints for integrating with Ringback. All API routes require authentication unless noted.
https://your-domain.com/api🔐 Authentication
Most endpoints use Supabase Auth session cookies (browser) or Bearer tokens (server-to-server).
Bearer
Supabase Auth session cookie (browser) or Bearer token (API). Set Authorization: Bearer <token>
Public
No authentication required (onboarding, webhooks with signature verification)
Twilio Signature
Validated via X-Twilio-Signature header. Configure webhook URL in Twilio Console.
Stripe Signature
Validated via Stripe-Signature header. Configure in Stripe Dashboard.
Cron Secret
Internal cron jobs. Requires CRON_SECRET header matching env var.
Authentication
/api/auth/registerRegister new user account
Onboarding
/api/onboarding/send-verificationSend SMS verification code to phone number
/api/onboarding/verify-codeVerify 6-digit code, create phone number record
/api/onboarding/resend-verificationResend verification code
Leads
/api/leadsList leads with filters (status, search, pagination)
/api/leadsCreate manual lead
/api/leads/[id]Get lead detail with timeline & messages
/api/leads/[id]Update lead (name, status, notes)
/api/leads/[id]/sendManually trigger next sequence step
/api/leads/[id]/closeClose lead (stop sequence)
/api/leads/[id]/mark-wonMark lead as won
/api/leads/[id]/mark-lostMark lead as lost
Phone Numbers
/api/phone-numbersList user's phone numbers
/api/phone-numbersAdd new phone number (starts verification)
/api/phone-numbers/[id]Delete phone number
/api/phone-numbers/[id]Update friendly name, forwarding status
Sequences
/api/sequences?phoneNumberId=Get sequence steps for a phone number
/api/sequencesUpdate sequence step (channel, delay, template)
/api/sequencesAdd new step to sequence
/api/sequences/[id]Delete sequence step
Settings
/api/settings/crmGet CRM configuration
/api/settings/crmUpdate CRM config (provider, fields, credentials)
/api/settings/crm/testTest CRM connection with sample payload
/api/settings/billingGet subscription & usage
/api/billing/checkoutCreate Stripe Checkout session
/api/billing/portalCreate Stripe Billing Portal session
Webhooks (Inbound)
/api/webhooks/twilio/smsTwilio SMS webhook (inbound replies, delivery status)
/api/webhooks/twilio/voiceTwilio Voice webhook (missed calls, AI voice)
/api/webhooks/stripeStripe events (subscription, payment, invoice)
/api/webhooks/hubspotHubSpot webhook (contact/deal updates)
Cron Jobs (Internal)
/api/cron/process-sequencesProcess due sequence steps (runs every minute)
/api/cron/send-messagesSend queued messages (runs every 30s)
/api/cron/process-sequences-batchBatch process for high volume
📄 Response Examples
GET /api/leads/[id]
{
"id": "uuid",
"phone_number_id": "uuid",
"name": "Marcus T.",
"phone_e164": "+12145550132",
"status": "active",
"source": "missed_call",
"metadata": {
"caller_id_name": "Marcus T.",
"forwarded_from": "+12145550199"
},
"created_at": "2026-01-12T14:14:00Z",
"updated_at": "2026-01-12T14:14:00Z"
}GET /api/sequences?phoneNumberId=
[
{
"id": "uuid",
"phone_number_id": "uuid",
"step_order": 1,
"channel": "sms",
"delay_minutes": 0,
"template_sms": "Hi {{lead_name}}, this is {{business_name}}...",
"template_email_subject": null,
"template_email_html": null,
"template_email_text": null,
"is_active": true,
"created_at": "2026-01-12T14:14:00Z",
"updated_at": "2026-01-12T14:14:00Z"
}
]Lead Messages (included in lead detail)
[
{
"id": "uuid",
"lead_id": "uuid",
"direction": "outbound",
"channel": "sms",
"content": "Hi Marcus, this is Torres Plumbing...",
"status": "delivered",
"twilio_sid": "SMxxxxxxxxxxxx",
"step_order": 1,
"scheduled_at": "2026-01-12T14:14:05Z",
"sent_at": "2026-01-12T14:14:06Z",
"delivered_at": "2026-01-12T14:14:08Z",
"created_at": "2026-01-12T14:14:05Z"
}
]🔔 Webhook Payloads (Inbound)
Configure these URLs in your provider dashboards. All webhooks verified via signature headers.
Twilio SMS Inbound (Lead Reply)
{
"MessageSid": "SMxxxxxxxxxxxx",
"From": "+12145550132",
"To": "+12145550199",
"Body": "Yes, I need a plumber tomorrow",
"MessageStatus": "received"
}Twilio Voice (Missed Call)
{
"CallSid": "CAxxxxxxxxxxxx",
"From": "+12145550132",
"To": "+12145550199",
"CallStatus": "no-answer",
"Direction": "inbound",
"CallerName": "Marcus T."
}Stripe Subscription Created
{
"id": "evt_xxxxxxxxxxxx",
"type": "customer.subscription.created",
"data": {
"object": {
"id": "sub_xxxxxxxxxxxx",
"customer": "cus_xxxxxxxxxxxx",
"status": "active",
"items": {
"data": [
{
"price": {
"id": "price_growth_monthly"
}
}
]
}
}
}
}⏱️ Rate Limits
- API endpoints: 120 requests/minute per user
- SMS sending: Per Twilio account limits (typically 1 msg/sec per number)
- Email sending: Per SendGrid/Mailgun limits
- Webhook retries: Exponential backoff (1m, 5m, 15m, 1h, 6h)
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
❌ Error Responses
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Phone number must be in E.164 format",
"details": { "field": "phone_number" }
}
}