User-Tenant Mapping

​

How it works

​

When to use it

• Same user, different push tokens per app. A workspace runs multiple mobile apps (each a tenant); the user has separate $androidpush / $iospush tokens per app install, and a push for one app should never be routed to another app’s token.
• Tenant-scoped role or plan properties. The user is “admin” on projectA and “viewer” on projectB — template branches on role.
• Different work email per business line. $email on the global profile is the personal address; per-tenant $email is the tenant-specific work address.

​

When NOT to use it — user-tenant mapping vs neighboring approaches

​

User tenancy mode — shared vs exclusive

​

Channel fallback — controlling what leaks from global

​

Default-tenant exemption

​

Associating a user to a tenant

• Dashboard
• REST API

1

Open the tenant's Associated Users tab

Go to Tenants → tenant_id → Associated Users. The tab lists every user already mapped to this tenant, with Channels Overridden and Properties Overridden columns so you can see at a glance which fields diverge from the user’s global profile.

2

Add the user

Click + Add Users. In the side sheet, pick the user from the User dropdown, then add per-tenant channels and properties. Every field you enter here writes to the per-tenant profile, not the global one.

3

Save

Click Add User. The user now appears on the Associated Users tab with the channels and properties you overrode.

Alternative — edit tenant overrides from the User detail page. Open Users → distinct_id and switch the View for tenant dropdown (top-right) to the tenant you want to scope changes to. A banner confirms the tenant context and any values overridden for this tenant render highlighted in blue. Use the per-field editor to override a channel or property, or click Reset all to clear every override at once.

You can also list users through the tenant’s lens from Users → View for tenant → tenant_id. The listing then reflects each user’s effective profile for that tenant.

curl -X POST "https://hub.suprsend.com/v1/user/joe@example.com/tenant/suprstack/" \
  --header 'Authorization: Bearer __YOUR_API_KEY__' \
  --header 'Content-Type: application/json' \
  --data '{
    "$email": ["joe@suprstack.com"],
    "$androidpush": ["fcm_token_suprstack_abc123"],
    "$timezone": "America/New_York",
    "$preferred_language": "en",
    "role": "admin"
  }'

See Upsert user-tenant profile for the full request and response schema.

​

Triggering a workflow with tenant context

{
  "workflow": "invoice-reminder",
  "tenant_id": "suprstack",
  "recipients": [{ "distinct_id": "joe@example.com" }],
  "data": { "invoice_no": "INV-2287", "amount": "$1,240" }
}

{
  "workflow": "invoice-reminder",
  "tenant_id": "suprstack",
  "recipients": [
    {
      "distinct_id": "joe@example.com",
      "$email": ["joe@suprstack.com"],
      "$context": { "tenant_id": "suprstack" }
    }
  ],
  "data": { "invoice_no": "INV-2287" }
}

​

Deleting a user-tenant mapping

curl -X DELETE "https://hub.suprsend.com/v1/user/joe@example.com/tenant/suprstack/" \
  --header 'Authorization: Bearer __YOUR_API_KEY__'

​

Key behaviors and constraints

• Global profile is untouched — creating per-tenant profiles never modifies the global one. A user with no per-tenant profile behaves identically to today.
• Shallow merge, per-tenant wins — object-typed values are replaced, not deep-merged. If properties.address exists on both profiles, the per-tenant object replaces the global one entirely.
• Isolation is per-workspace — user_tenancy_mode applies to every tenant in the workspace; it can’t be set per tenant.
• Fallback is per-channel — governed by the workspace-level user_tenancy_channel_fallback_mode + user_tenancy_channel_fallback list; not settable per tenant or per user.
• The default tenant behaves like global on the trigger path — unless user_tenancy_channel_fallback_applies_to_default_tenant is enabled.
• Preferences are separate — per-tenant user preferences already exist and are governed by the preference APIs. User-tenant mapping stores properties and channel identities, not preferences.

​

Troubleshooting

​

FAQ

​

Next steps