Building on Surge: One Account per Customer

If you're building a SaaS platform and you want your customers to send messages under their own brand, the right architecture is one Surge account per customer. This pattern is called multi-tenant messaging, and the design decisions you make here are much harder to undo than to get right from the start.

The core expectation

When you send messages through Surge, carriers ask: whose brand is behind this message? The brand registered on the account must match the brand the message recipient expects to see as the sender.

If your customers are distinct businesses — a real estate agency, a dental practice, a law firm — each of those businesses needs its own account with its own registration. Sending all their messages through one shared account means you can only register one brand, and messages from "Sarah's Dental" arriving from "AcmeSaaS Corp" will get flagged.

Why separate accounts matter

Compliance partitioning. If one of your customers gets flagged for spam — whether it's a rogue employee or a misunderstanding — only their account is affected. Their campaign suspension doesn't touch your other customers. A single shared account means a flag on one customer's campaign can take down messaging for every customer.

Cost attribution. Each account bills independently, so you can pass usage costs through to your customers without building a message-counting system on your end. Surge's usage reports are already broken down by account.

Scaling isolation. A customer with a sudden volume spike doesn't consume rate-limit headroom for your other customers. Message delivery, error rates, and carrier relationships are isolated per account.

The biggest gotcha

The brand you register must match what message recipients see.

Say you're building a platform for real estate agents. You create an account for agent Jane Smith, register it under "Smith Realty LLC," and purchase a number for her. Every message Jane sends through that number should identify itself as coming from Smith Realty — not from your platform's brand.

If the registration says "Smith Realty" but the message says "Powered by YourPlatform," or if you use a shared number across multiple agents' accounts, reviewers will flag the mismatch.

How to implement the pattern

1. When a customer signs up on your platform, call POST /accounts to create a Surge account for them. Store the returned id alongside their record in your database.

2. Collect their business information (EIN, website, address, authorized representative) and submit it with the account creation or via PATCH /accounts/:id.

3. Create a campaign for their account via POST /accounts/:account_id/campaigns. The campaign should reflect their messaging use case, their opt-in flow, and their brand — not yours.

4. Purchase a phone number via POST /accounts/:account_id/phone_numbers and attach it to their campaign.

5. When sending messages on their behalf, use their account ID in the path: POST /accounts/CUSTOMER_ACCOUNT_ID/messages.

Your API key (at the platform level) authorizes all of this. You don't need separate API keys per customer — one platform API key can access all accounts under your platform.

Checking registration status programmatically

When you create an account for a customer, you may not have all their business information up front. The status endpoint lets you check what's still needed:

curl "https://api.surge.app/accounts/CUSTOMER_ACCOUNT_ID/status?capabilities=local_messaging" \
  -H "Authorization: Bearer YOUR_PLATFORM_API_KEY"

The fields_needed array tells you exactly what to collect before you can submit a campaign. Build this check into your onboarding flow so customers see a guided setup experience rather than a registration failure.

Further reading

The same pattern is covered from a different angle in Twilio's ISV re-architecture guide, which documents why Twilio's largest platform customers moved away from shared accounts. The problems are identical across providers.