# Surge

- [What is Surge](https://docs.surge.app/overview/what-is-surge.md): An introduction to Surge, the SMS and voice API for developers.
- [How Surge is Organized](https://docs.surge.app/overview/how-surge-is-organized.md): The Project, Account, and User hierarchy, what each level owns, and how the API is structured.
- [Send Your First Message](https://docs.surge.app/quickstart.md): Send your first SMS in under five minutes using Surge's demo number. No registration or phone number purchase required.
- [Register Your Business](https://docs.surge.app/registration/index.md): Carrier registration overview: what you need, how the review process works, and how to choose your registration path.
- [Register via API](https://docs.surge.app/registration/api-walkthrough.md): Step-by-step: create an account, submit a campaign, purchase a phone number, and reach production via the Surge API.
- [Canonical Schema Reference](https://docs.surge.app/registration/schema-reference.md): All valid enum values for organization type, industry, regions, campaign use cases, content includes, and volume.
- [Register via Dashboard](https://docs.surge.app/registration/dashboard.md): Register your brand and campaign using the Surge dashboard form, the current path for toll-free verification.
- [Building on Surge: One Account per Customer](https://docs.surge.app/registration/one-account-per-customer.md): Why vertical SaaS platforms should create one Surge account per customer and how to implement the pattern.
- [Avoiding Rejection: Patterns from Real Registration Reviews](https://docs.surge.app/registration/avoiding-rejection.md): The seven most common campaign rejection reasons with real reviewer quotes and specific fixes for each.
- [Sole Proprietor Path](https://docs.surge.app/registration/sole-proprietor.md): How sole proprietors register on Surge: no EIN required, dashboard-first flow, and lower throughput expectations.
- [Toll-Free Verification](https://docs.surge.app/registration/toll-free.md): How toll-free number verification works on Surge and how it differs from standard 10DLC local number registration.
- [Fixing a Rejected or Changes-Needed Campaign](https://docs.surge.app/registration/fixing-rejected.md): How to read reviewer feedback, update a campaign in a valid status, and get back to production after rejection.
- [Send to One Person](https://docs.surge.app/sending/send-one.md): Send SMS and MMS to a single recipient: required fields, attachments, scheduling, personalization, and common errors.
- [Send to Many People](https://docs.surge.app/sending/send-many.md): Blasts vs Audiences: when to use each, how to create and send to both, and campaign volume caps.
- [Ongoing Conversations](https://docs.surge.app/sending/conversations.md): How contacts and conversation threads work, when to use them, and how to manage opt-out state per thread.
- [Track Message Delivery](https://docs.surge.app/sending/track-delivery.md): How message delivery statuses work, webhook-based tracking, and how to list messages with cursor pagination.
- [Handle Failures](https://docs.surge.app/sending/handle-failures.md): Every send-time and delivery-time error code, retryability, and specific remediation steps for each failure type.
- [Receiving Messages & Webhooks](https://docs.surge.app/receiving/index.md): Configure a webhook endpoint, verify Surge webhook signatures, and handle incoming events in Python, TypeScript, Ruby, and Elixir.
- [Webhook Events](https://docs.surge.app/receiving/events.md): A categorized index of webhook event types with links to each event's detailed reference page.
- [Two-Way Messaging Patterns](https://docs.surge.app/receiving/two-way.md): Receive inbound messages, reply in the same thread, handle opt-outs inline, and avoid duplicate event processing.
- [Purchasing a Number](https://docs.surge.app/phone-numbers/purchasing.md): Purchase local, toll-free, or short code phone numbers via API and understand per-plan phone number limits.
- [Importing a Number](https://docs.surge.app/phone-numbers/importing.md): Port an existing phone number into Surge or host an external number to route its messaging traffic through Surge.
- [International Numbers](https://docs.surge.app/phone-numbers/international.md): US and Canada numbers are available via API. Numbers in other countries are available through support on request.
- [Attaching a Number to a Campaign](https://docs.surge.app/phone-numbers/attaching.md): How Surge automatically attaches phone numbers to active campaigns and when to listen for the attachment event.
- [Send and verify a code](https://docs.surge.app/verifications/send-and-verify.md): Send a six-digit OTP to a phone number and verify the user's code with two API calls, expiry and retry limits included.
- [Usage patterns and delivery gotchas](https://docs.surge.app/verifications/usage-patterns.md): Opted-out contacts, international quirks, carrier filtering, and security tips for OTP verification in production.
- [RCS and WhatsApp](https://docs.surge.app/channels-roadmap/rcs-and-whatsapp.md): RCS and WhatsApp are coming to Surge. How to build SMS workflows today so your code extends to new channels without rewrites.
- [Voice](https://docs.surge.app/channels-roadmap/voice.md): Voice calls, recording, voicemail, and AI voice agent integrations available now; more features and full GA coming soon.
- [Embeddable UI Components](https://docs.surge.app/embeddable/index.md): Add a messaging inbox, conversation view, and dialpad to your app using Surge's embeddable UI components and JWT auth.
- [Working with Users](https://docs.surge.app/embeddable/users.md): Provision Users via the API, generate short-lived JWTs for embedded components, and attribute messages to users.
- [Inbox component](https://docs.surge.app/embeddable/inbox.md): Embed the Inbox component to show a real-time conversation list scoped to the current User.
- [Conversation Component](https://docs.surge.app/embeddable/conversation.md): Mount the Conversation component to display a single message thread with send capability for the current User.
- [Unread Count Component](https://docs.surge.app/embeddable/unread-count.md): Embed a live unread conversation count badge that updates in real time as new messages arrive.
- [SMS Segments & Encoding](https://docs.surge.app/concepts/sms-segments.md): How SMS segments and character encodings work, why emoji messages use more segments, and practical cost advice.
- [The Campaign Registry (TCR) and Becoming a CSP](https://docs.surge.app/concepts/tcr.md): What TCR is, how Surge submits your registrations as your CSP, and when becoming a CSP yourself makes sense.
- [Consent Flows: How Users Opt In](https://docs.surge.app/concepts/consent-flows.md): Valid opt-in methods, what makes a consent flow carrier-compliant, and how to write the consent_flow description.
- [Required Disclosures and Opt-In Templates](https://docs.surge.app/concepts/required-disclosures.md): The three required SMS disclosures, where to place them, and copy-ready opt-in templates for common use cases.
- [Deliverability](https://docs.surge.app/concepts/deliverability.md): T-Mobile volume caps, Verizon batching delays, Surge's content policy layer, and how to monitor message delivery health.
- [Using the SDKs](https://docs.surge.app/sdks/index.md): Choose a Surge SDK, authenticate with an env var or constructor, and make requests for endpoints without typed methods.
- [Python SDK](https://docs.surge.app/sdks/python.md): Install the Python SDK, send messages with sync and async clients, paginate, handle typed errors, and verify webhooks.
- [TypeScript SDK](https://docs.surge.app/sdks/typescript.md): Install the TypeScript SDK, send messages with full type safety, paginate, handle typed errors, and verify webhooks.
- [Ruby SDK](https://docs.surge.app/sdks/ruby.md): Install the Ruby SDK with Sorbet types, send messages, paginate, handle errors, and verify webhooks in Rails.
- [Elixir SDK](https://docs.surge.app/sdks/elixir.md): Install the Elixir SDK, configure for Phoenix, send messages, handle errors, and use WebhookPlug or WebhookHandler.
- [Introduction](https://docs.surge.app/api-reference/introduction.md): The Surge REST API is a JSON API over HTTPS. Base URL: https://api.surge.app.
- [Authentication](https://docs.surge.app/api-reference/authentication.md): Create and manage API keys, authenticate with a Bearer token, scope account requests, and view API logs.
- [Error Reference](https://docs.surge.app/api-reference/errors.md): Every API error type by category: HTTP status codes, causes, and messaging-layer delivery failures with descriptions.
- [Create account](https://docs.surge.app/api-reference/endpoint/accounts/create.md): Create a new account under your project. Submit organization details to begin the carrier registration process.
- [List accounts](https://docs.surge.app/api-reference/endpoint/accounts/list.md): Return all accounts under your project. Useful for syncing the accounts you manage and inspecting their carrier registration status.
- [Retrieve account](https://docs.surge.app/api-reference/endpoint/accounts/get.md): Retrieve a single account by ID.
- [Check account status](https://docs.surge.app/api-reference/endpoint/accounts/check-status.md): Check an account's registration status and see which fields are still needed for the requested capabilities.
- [Update account](https://docs.surge.app/api-reference/endpoint/accounts/update.md): Update organization details on an existing account to fill gaps identified by the status check.
- [Archive account](https://docs.surge.app/api-reference/endpoint/accounts/archive.md): Archive an account, preventing further sends. Archived accounts cannot be restored via the API.
- [Retrieve attachment file](https://docs.surge.app/api-reference/endpoint/attachments/get-file.md): Download the media file for an MMS attachment. Returns a redirect to a short-lived signed URL.
- [Create audience](https://docs.surge.app/api-reference/endpoint/audiences/create.md): Create a named audience (contact group) that you can reuse across multiple blast sends.
- [Add contact to audience](https://docs.surge.app/api-reference/endpoint/audiences/add-contact.md): Add a contact to an audience.
- [List audience contacts](https://docs.surge.app/api-reference/endpoint/audiences/list-contacts.md): List all contacts in an audience with cursor-based pagination.
- [Create blast](https://docs.surge.app/api-reference/endpoint/blasts/create.md): Send a message to a list of recipients or an audience in a single API call.
- [Create campaign](https://docs.surge.app/api-reference/endpoint/campaigns/create.md): Register a new A2P 10DLC campaign with The Campaign Registry under an account.
- [List campaigns](https://docs.surge.app/api-reference/endpoint/campaigns/list.md): List all campaigns registered to an account with cursor-based pagination.
- [Retrieve campaign](https://docs.surge.app/api-reference/endpoint/campaigns/get.md): Retrieve a single campaign by ID, including its current registration status.
- [Update campaign](https://docs.surge.app/api-reference/endpoint/campaigns/update.md): Update campaign details to address changes-needed feedback from carrier review.
- [Resend brand verification OTP](https://docs.surge.app/api-reference/endpoint/campaigns/resend-brand-verification-message.md): Enqueues an SMS OTP for a sole proprietor brand awaiting identity verification.
- [Create contact](https://docs.surge.app/api-reference/endpoint/contacts/create.md): Create a contact record identified by phone number under an account.
- [List contacts](https://docs.surge.app/api-reference/endpoint/contacts/list.md): List all contacts for an account with cursor-based pagination.
- [Retrieve contact](https://docs.surge.app/api-reference/endpoint/contacts/get.md): Retrieve a single contact by ID, including opt-out status and metadata.
- [Update contact](https://docs.surge.app/api-reference/endpoint/contacts/update.md): Update contact details such as name, email, or custom metadata.
- [Send message](https://docs.surge.app/api-reference/endpoint/messages/create.md): Queue an SMS or MMS message from a phone number to be sent to a recipient, asynchronously.
- [List messages](https://docs.surge.app/api-reference/endpoint/messages/list.md): List messages for an account with cursor-based pagination and optional conversation filtering.
- [Retrieve message](https://docs.surge.app/api-reference/endpoint/messages/get.md): Retrieve a single message by ID, including its current delivery status.
- [Purchase phone number](https://docs.surge.app/api-reference/endpoint/phone-numbers/purchase.md): Purchase a local or toll-free phone number and assign it to an account.
- [List phone numbers](https://docs.surge.app/api-reference/endpoint/phone-numbers/list.md): List all phone numbers provisioned under an account.
- [Retrieve phone number](https://docs.surge.app/api-reference/endpoint/phone-numbers/get.md): Retrieves a PhoneNumber object.
- [Update phone number](https://docs.surge.app/api-reference/endpoint/phone-numbers/update.md): Updates a phone number's details.
- [Release phone number](https://docs.surge.app/api-reference/endpoint/phone-numbers/release.md): Releases a phone number from the account.
- [List available numbers](https://docs.surge.app/api-reference/endpoint/phone-numbers/list-available-numbers.md): Browse purchasable phone numbers from Surge inventory before buying.
- [List recordings](https://docs.surge.app/api-reference/endpoint/recordings/list.md): List call recordings for an account.
- [Retrieve recording](https://docs.surge.app/api-reference/endpoint/recordings/get.md): Retrieve a single call recording by ID, including its processing status.
- [Delete recording](https://docs.surge.app/api-reference/endpoint/recordings/delete.md): Permanently delete a call recording and its associated audio file from storage.
- [Download recording file](https://docs.surge.app/api-reference/endpoint/recordings/get-file.md): Download the audio file for a call recording. Returns a redirect to a short-lived signed URL.
- [Create user](https://docs.surge.app/api-reference/endpoint/users/create.md): Create a user record under an account. Users are shown inside embeddable UI components.
- [List users](https://docs.surge.app/api-reference/endpoint/users/list.md): List all users provisioned under an account with cursor-based pagination.
- [Retrieve user](https://docs.surge.app/api-reference/endpoint/users/get.md): Retrieve a single user by ID.
- [Update user](https://docs.surge.app/api-reference/endpoint/users/update.md): Update a user's name or custom metadata.
- [Delete user](https://docs.surge.app/api-reference/endpoint/users/delete.md): Permanently delete a user record from an account.
- [Create user token](https://docs.surge.app/api-reference/endpoint/users/create-token.md): Create a short-lived JWT for a user to authenticate with Surge's embeddable UI components.
- [Create verification](https://docs.surge.app/api-reference/endpoint/verifications/create.md): Send a one-time passcode (OTP) to a phone number to begin the verification flow.
- [Check verification](https://docs.surge.app/api-reference/endpoint/verifications/check.md): Submit the OTP a user received to complete phone number verification.
- [Webhooks Overview](https://docs.surge.app/api-reference/webhooks/intro.md): How Surge webhook delivery works: event types, retry behavior, and where to configure your endpoint.
- [Signature Verification](https://docs.surge.app/api-reference/webhooks/signature-validation.md): Verify Surge webhook signatures using Standard Webhooks HMAC-SHA256 to authenticate incoming requests.
- [message.sent](https://docs.surge.app/api-reference/webhooks/message/sent.md): Fires when Surge accepts an outbound message and passes it to the carrier for delivery.
- [message.delivered](https://docs.surge.app/api-reference/webhooks/message/delivered.md): Fires when the carrier confirms an outbound message was delivered to the recipient's handset.
- [message.failed](https://docs.surge.app/api-reference/webhooks/message/failed.md): Fires when an outbound message could not be delivered. Includes a failure_reason code.
- [message.received](https://docs.surge.app/api-reference/webhooks/message/received.md): Fires when an inbound message arrives from a contact to one of your phone numbers.
- [contact.opted_in](https://docs.surge.app/api-reference/webhooks/contact/opted_in.md): Fires when a contact opts back in to messaging by sending a keyword like START, YES, or UNSTOP.
- [contact.opted_out](https://docs.surge.app/api-reference/webhooks/contact/opted_out.md): Fires when a contact opts out of messaging by sending a keyword like STOP, CANCEL, or UNSUBSCRIBE.
- [conversation.created](https://docs.surge.app/api-reference/webhooks/conversation/created.md): Fires when a new conversation thread is created, on the first inbound message from a contact.
- [campaign.approved](https://docs.surge.app/api-reference/webhooks/campaign/approved.md): Fires when a campaign transitions to active after carrier approval.
- [phone_number.imported](https://docs.surge.app/api-reference/webhooks/phone_number/imported.md): Fires when a phone number is imported into Surge from an external provider.
- [phone_number.attached_to_campaign](https://docs.surge.app/api-reference/webhooks/phone_number/attached_to_campaign.md): Fires when a phone number is successfully attached to a campaign and is ready for production messaging.
- [link.followed](https://docs.surge.app/api-reference/webhooks/link/followed.md): Fires the first time a contact clicks a shortened link in a message.
- [call.ended](https://docs.surge.app/api-reference/webhooks/call/ended.md): Fires when a call ends, regardless of direction or how it was terminated.
- [recording.completed](https://docs.surge.app/api-reference/webhooks/recording/completed.md): Fires when a non-voicemail call recording finishes processing and is available for download.
- [voicemail.received](https://docs.surge.app/api-reference/webhooks/voicemail/received.md): Fires when a voicemail recording finishes processing and is available for download.
- [HIPAA Compliance](https://docs.surge.app/resources/hipaa.md): HIPAA-compliant messaging and voice are in development on the Custom plan. How to start the process with Surge.
- [Release Notes](https://docs.surge.app/resources/release-notes.md): Browse Surge's public release notes on the web or via the API to track new features, deprecations, and removed surfaces.
- [Deprecation Notices](https://docs.surge.app/resources/deprecations.md): Active deprecations: the surge-signature header, link.followed.message_id field, and publishable tokens for embeds.
- [Glossary](https://docs.surge.app/resources/glossary.md): Definitions for Surge and A2P messaging terms: Account, Brand, Campaign, CSP, TypeID, Dashboard User, User, and more.

## OpenAPI Specs

- [openapi.documented](https://app.stainless.com/api/spec/documented/surge/openapi.documented.yml)