> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surge.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Building on Surge: One Account per Customer
> Why vertical SaaS platforms should create one Surge account per customer and how to implement the pattern.
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.
Every number should be registered to the business from which the end customer thinks they're receiving a message. If the message is presented as coming from your platform, and the recipient opted in to messages from your platform, a single platform account can be the right fit. If the message is presented as coming from one of your customers, that customer's business needs its own account, campaign, and number.
For example, imagine a communication platform for dental offices called "DentalSoft" with customers like "ABC Dental" and "XYZ Dental." DentalSoft could use one DentalSoft account for payment receipts or appointment reminders that clearly identify DentalSoft as the sender and rely on patient opt-in to DentalSoft. But if a patient opted in to messages from ABC Dental, or reasonably believes ABC Dental is messaging them directly, that number should be registered to ABC Dental. XYZ Dental would need its own account for the same reason.
```mermaid theme={null}
flowchart TD
P["Your Platform
(one API key)"]
P --> A1["Account: Smith Realty
org.type: llc"]
P --> A2["Account: Jones Dental
org.type: llc"]
P --> A3["Account: Acme Co
org.type: private_corporation"]
A1 --> C1["Campaign + Phone Number
brand: Smith Realty"]
A2 --> C2["Campaign + Phone Number
brand: Jones Dental"]
A3 --> C3["Campaign + Phone Number
brand: Acme Co"]
```
## 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 message has a "Powered by YourPlatform" attribution alongside the client's brand, that is fine. But if the registration says "YourPlatform Co" but the message says "Smith Realty," or if you use a shared number across multiple agents' accounts, it will get flagged.
## How to implement the pattern
Call `POST /accounts` with the customer's business name. Store the returned `id` alongside their record in your database — every subsequent call uses it.
```bash theme={null}
curl -X POST https://api.surge.app/accounts \
-H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Smith Realty",
"brand_name": "Smith Realty"
}'
```
```json theme={null}
{
"id": "acct_01jrzhe8d9enptypyx360pcmxl",
"name": "Smith Realty",
"brand_name": "Smith Realty"
}
```
Save `acct_01jrzhe8d9enptypyx360pcmxl` against your customer's row.
Collect EIN, website, address, and authorized representative from the customer, then submit via `PATCH /accounts/{account_id}`. Submit it all at once — partial submissions can't enter review. See [Register via API → Account fields](./api-walkthrough) for the full body shape.
`POST /accounts/{account_id}/campaigns` with their use case, opt-in flow, and sample messages. The campaign reflects **their** brand, not yours. See [Schema Reference → Campaign fields](./schema-reference#campaign-fields) for required values.
`POST /accounts/{account_id}/phone_numbers`. Once the campaign reaches `active`, Surge auto-attaches the number — see [Attaching numbers](../phone-numbers/attaching).
Use the customer's account ID in the path. The platform API key authorizes the call:
```bash theme={null}
curl -X POST https://api.surge.app/accounts/{account_id}/messages \
-H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"body": "Smith Realty: Showing confirmed for Saturday at 2pm."
}'
```
See [POST /messages](../api-reference/endpoint/messages/create) for the full request and response shapes.
You don't need separate API keys per customer. One project-level API key authorizes every account in your project.
## 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:
```bash theme={null}
curl "https://api.surge.app/accounts/{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.