Create / Update Tenants

API to create a new Tenant OR update an existing Tenant

post/v1/tenant/{tenant_id}/

Path parameters

tenant_idstring required

Tenant identifier to create or update. Max 64 chars; allowed characters [a-z0-9_.-].

Request body

namestring required

Tenant display name. Replaces the legacy tenant_name field; both are accepted.

tenant_namestring

Will be deprecated in future. Use name instead.

parent_idstring nullable

ID of the parent tenant if you want to add this tenant as a sub-tenant. Skip this field, or pass null or "" to create the tenant as a root. Setting it on an existing tenant re-parents it or leave it null to delink existing parent. Must reference an existing tenant. See Sub-tenants.

blocked_channelsstring[] nullable

Channels turned off for this tenant. Notifications on these channels won't be sent to any user of the tenant — including on root categories (which users normally can't unsubscribe from) — and users can't override this. If sub-tenants are used, a block set here also applies to every sub-tenant below and can't be removed lower down. Allowed: email, sms, whatsapp, androidpush, iospush, webpush, slack, ms_teams, inbox.

logostring

Tenant logo URL.

primary_colorstring

Primary brand color, used in the tenant's email header, buttons, and footer. If left empty on create, it's copied from the default tenant.

secondary_colorstring

Secondary brand color. Not part of the default tenant component but can be used in templates as {{$tenant.secondary_color}}. If left empty on create, it's copied from the default tenant.

tertiary_colorstring

Tertiary brand color. Not part of the default tenant component but can be used in templates as {{$tenant.tertiary_color}}. If left empty on create, it's copied from the default tenant.

preference_page_urlstring

URL of your product's preference page.

propertiesobject

Custom tenant properties. Merged per top-level key on update — keys not in the payload are kept as-is.

Example request

{
  "parent_id": "acme-corp",
  "blocked_channels": [
    "sms"
  ],
  "secondary_color": "#00ff00",
  "tertiary_color": "#0000ff"
}

Response

201 - Created

object required

Tenant object returned. Fields hold the tenant's own local values — values not set on this tenant come back as null (or as empty objects/arrays). For flat tenants (no sub-tenants), unset fields stay unresolved and the tenant simply has no value for them. For sub-tenants, unset fields still return null here, but are resolved from the closest ancestor that has a value set at trigger time.

Changes

Changed in 1 of the 7 revisions of this API.115

Aug 30, 2026ea7b2f7c41a9115See the full diff
- ▲
  added the pattern ^[a-z0-9_.-]+$ to the path request parameter tenant_id
  request-parameter-pattern-added
- ●
  for the path request parameter tenant_id, the maxLength was set to 64
  request-parameter-max-length-set
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new required request property with a default value
  new-required-request-property-with-default
- ○
  the request property became optional
  request-property-became-optional
- ○
  the request property default value Awesome Tenant was removed
  request-property-default-value-removed

Full history