# Building on Surge: One Account per Customer
URL: /docs/registration/one-account-per-customer
LLM index: /llms.txt
Description: Why vertical SaaS platforms should create one Surge account per customer and how to implement the pattern.

# 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.

```mermaid
flowchart TD
  P["Your Platform<br/>(one API key)"]
  P --> A1["Account: Smith Realty<br/>org.type: llc"]
  P --> A2["Account: Jones Dental<br/>org.type: llc"]
  P --> A3["Account: Acme Co<br/>org.type: private_corporation"]
  A1 --> C1["Campaign + Phone Number<br/>brand: Smith Realty"]
  A2 --> C2["Campaign + Phone Number<br/>brand: Jones Dental"]
  A3 --> C3["Campaign + Phone Number<br/>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

<Warning>
**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.
</Warning>

## How to implement the pattern

<Steps>
  <Step title="Create an account when a customer signs up">
    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
    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
    {
      "id": "acct_01jrzhe8d9enptypyx360pcmxl",
      "name": "Smith Realty",
      "brand_name": "Smith Realty"
    }
    ```

    Save `acct_01jrzhe8d9enptypyx360pcmxl` against your customer's row.
  </Step>

  <Step title="Submit business information">
    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.
  </Step>

  <Step title="Create a campaign for their account">
    `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.
  </Step>

  <Step title="Purchase and attach a phone number">
    `POST /accounts/{account_id}/phone_numbers`. Once the campaign reaches `active`, Surge auto-attaches the number — see [Attaching numbers](../phone-numbers/attaching).
  </Step>

  <Step title="Send messages on their behalf">
    Use the customer's account ID in the path. The platform API key authorizes the call:

    ```bash
    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.
  </Step>
</Steps>

<Note>
You don't need separate API keys per customer. One platform-level API key authorizes every account under your platform.
</Note>

## 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
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.

## Further reading

The same pattern is covered from a different angle in Twilio's [Direct Customer to ISV Rearchitecture Guide](https://www.twilio.com/en-us/blog/developers/best-practices/direct-customer-to-isv-rearchitecture-guide), which documents why Twilio's largest platform customers moved away from shared accounts. The problems are identical across providers.