Multi-Company Management

Sarah allows you to manage multiple companies from a single user account. This is ideal for consultants, accountants, or entrepreneurs who manage several businesses.

Basic Concepts

User and Companies

• One user can have access to multiple companies
• Each company has its own data: products, sales, customers, etc.
• You can switch companies at any time without logging out

Data Structure

Users store companies in their metadata:

json
{
  "user_metadata": {
    "business_id": 42,  // Current company
    "business": [42, 43, 44]  // List of all companies
  }
}

Add a New Company

From Onboarding

1. During registration, you can create your first company
2. Complete company data
3. Select a subscription plan
4. Company is created and associated with your account

Invite to Existing Company

If a company already exists and you want to access it:

1. Company administrator must invite you
2. You'll receive an invitation email
3. Accept the invitation
4. Company will be added to your company list

Create Additional Company

To create a second company:

1. Go to Settings > Company
2. Click Create New Company
3. Complete data
4. Select a plan
5. New company will be added to your account

Switch Companies

From Interface

1. Click the company selector in the sidebar
2. Select the company you want to use
3. Interface updates automatically

From API

POST /api/users/switch-business

Body:

json
{
  "user_id": "user-uuid",
  "business_id": 43
}

Validation:

• The business_id must be in your company list (business array)
• If you don't have access, you'll receive a 403 error

Permissions and Roles

Roles per Company

Each company can have different roles for the same user:

• Company A: Administrator (role_id: 1)
• Company B: Salesperson (role_id: 2)
• Company C: Viewer (role_id: 3)

Verify Permissions

Before performing actions, Sarah verifies:

1. That user has access to current company
2. That user has necessary role for the action
3. That data belongs to current company

Use Cases

Consultant with Multiple Clients

Scenario:

• You're a consultant managing 5 client companies
• Each company has its own products and sales

Solution:

1. Each client invites you to their company
2. Switch companies according to which client you're working with
3. All data is separated by company

Entrepreneur with Multiple Businesses

Scenario:

• You have a physical store and an online store
• You want to manage them separately but from one account

Solution:

1. Create two companies: "Physical Store" and "Online Store"
2. Switch between them as needed
3. Each has its own inventory and sales

Accountant Managing Multiple Clients

Scenario:

• You're an accountant managing billing for 10 clients
• Each client has their own company in Sarah

Solution:

1. Each client invites you as administrator
2. You can access all companies from your account
3. Manage billing for each one independently

Multi-Company WhatsApp

The WhatsApp assistant also supports multi-company:

Contacts with Multiple Companies

If a contact is registered in multiple companies:

1. Assistant detects multiple companies
2. Asks: "Which company do you want to talk to?"
3. Customer chooses a company
4. Assistant maintains the choice in future conversations

Conversation Example

Customer: Hello
Assistant: Good morning. I see you're a contact of several companies:
          1. Company A
          2. Company B
          Which one do you want to talk to today?

Customer: Company A
Assistant: Perfect, I'm ready to help you with Company A.
          How can I help you?

API and Webhooks

Filtering by Company

All APIs automatically filter by current company:

javascript
// Only returns products from current company
const products = await supabase
  .from('products')
  .select('*')
  .eq('company_id', currentCompanyId);

Webhooks

Webhooks include company_id in events:

json
{
  "event": "sales.created",
  "data": {
    "sale": {
      "id": 789,
      "company_id": 42,
      "total": 15000.00
    }
  }
}

Best Practices

1. Organization

• Name companies clearly: Use descriptive names
• Use different logos: Makes it easy to identify company quickly
• Keep data separated: Don't mix products or customers between companies

2. Security

• Review permissions regularly: Ensure only authorized users have access
• Use appropriate roles: Don't grant administrator permissions unnecessarily
• Regenerate tokens: If you suspect compromise, regenerate Integration Keys

3. Billing

• Each company has its own subscription: They can have different plans
• Manage payments separately: Each company pays its own subscription
• Update plans as needed: Each company can change plans independently

4. Reports

• Generate reports per company: Reports are automatically filtered
• Compare companies: You can export data and compare in external tools
• Maintain history: Historical data is preserved when switching companies

Troubleshooting

Cannot switch companies

1. Verify permissions: Ensure you have access to the company
2. Review metadata: Verify company is in your business list
3. Contact support: If problem persists

Data mixed between companies

1. Verify company_id: Ensure data has correct company_id
2. Review filters: Queries must filter by company_id
3. Contact support: If you find mixed data

Don't see all my companies

1. Refresh page: Sometimes list needs updating
2. Verify invitations: Ensure you've accepted all invitations
3. Review permissions: Verify you have access to companies

Additional Resources

• Company Configuration - Manage users and permissions
• Subscriptions - Manage plans and payments
• Security - Security best practices

Support

If you need help with multi-company:

1. Review this guide
2. Verify your permissions and configuration
3. Contact Sarah support with problem details