Docs

Tenants API reference

Complete reference documentation for the Tenants resource.

Tenants

A Tenant a grouping with configurable settings that can be applied to a workflow when it's triggered in order to override account-level settings such as branding. Use tenants when sending a notification to user(s) that you want to configure specific brand elements for, such as a separate organization logo.

Endpoints

DELETE/v1/tenants/{id}

GET/v1/tenants/{id}

PUT/v1/tenants/{id}

GET/v1/tenants

Delete a tenant

Delete a tenant and all associated data. This operation cannot be undone.

Endpoint

DELETE/v1/tenants/{id}

Tier 2

Path parameters

string

The unique identifier for the tenant.

Returns

204 No Content

Get a tenant

Get a tenant by ID.

Endpoint

GET/v1/tenants/{id}

Tier 4

Path parameters

string

The unique identifier for the tenant.

Query parameters

resolve_full_preference_settings

boolean

When true, merges environment-level default preferences into the tenant's settings.preference_set field before returning the response. Defaults to false.

Returns

Tenant

A tenant entity.

__typename

string

The typename of the schema.

string

The unique identifier for the tenant.

name

string

An optional name for the tenant.

settings

object

The settings for the tenant. Includes branding and preference set.

branding

object

The branding for the tenant.

icon_url

string(uri)

The icon URL for the tenant. Must point to a valid image with an image MIME type.

logo_url

string(uri)

The logo URL for the tenant. Must point to a valid image with an image MIME type.

primary_color

string

The primary color for the tenant, provided as a hex value.

primary_color_contrast

string

The primary color contrast for the tenant, provided as a hex value.

preference_set

PreferenceSet

The preference set for the tenant. Used to override the default preference set.

object(any)

Any additional custom properties.

Set a tenant

Sets a tenant within an environment, performing an upsert operation. Any existing properties will be merged with the incoming properties.

Endpoint

PUT/v1/tenants/{id}

Tier 3

Path parameters

string

The unique identifier for the tenant.

Query parameters

resolve_full_preference_settings

boolean

When true, merges environment-level default preferences into the tenant's settings.preference_set field before returning the response. Defaults to false.

Request body

channel_data

InlineChannelDataRequest

The channel data for the tenant.

name

string

An optional name for the tenant.

settings

object

The settings for the tenant. Includes branding and preference set.

branding

object

The branding for the tenant.

icon_url

string

The icon URL for the tenant. Must point to a valid image with an image MIME type.

logo_url

string

The logo URL for the tenant. Must point to a valid image with an image MIME type.

primary_color

string

The primary color for the tenant, provided as a hex value.

primary_color_contrast

string

The primary color contrast for the tenant, provided as a hex value.

preference_set

PreferenceSetRequest

The preference set for the tenant. Used to override the default preference set.

object(any)

Any additional custom properties.

Returns

SetTenantResponse

The response from setting a tenant.

List tenants

List tenants for the current environment.

Endpoint

GET/v1/tenants

Tier 4

Query parameters

tenant_id

string

Filter tenants by ID.

name

string

Filter tenants by name.

after

string

The cursor to fetch entries after.

before

string

The cursor to fetch entries before.

page_size

integer

The number of items per page (defaults to 50).

Returns

ListTenantsResponse

A response containing a list of tenants.

entries

Tenant[]

A list of tenants.

__typename

string

Required

The typename of the schema.

string

Required

The unique identifier for the tenant.

name

string

An optional name for the tenant.

settings

object

The settings for the tenant. Includes branding and preference set.

branding

object

The branding for the tenant.

icon_url

string(uri)

The icon URL for the tenant. Must point to a valid image with an image MIME type.

logo_url

string(uri)

The logo URL for the tenant. Must point to a valid image with an image MIME type.

primary_color

string

The primary color for the tenant, provided as a hex value.

primary_color_contrast

string

The primary color contrast for the tenant, provided as a hex value.

preference_set

PreferenceSet

The preference set for the tenant. Used to override the default preference set.

page_info

PageInfo

Pagination information for a list of resources.

__typename

string

The typename of the schema.

after

string

The cursor to fetch entries after.

before

string

The cursor to fetch entries before.

page_size

integer

The number of items per page (defaults to 50).

Bulk operations

Bulk operations available for tenants. These endpoints return a BulkOperation that executes the job asynchronously. Progress can be tracked via the Bulk operations API.

Endpoints

POST/v1/tenants/bulk/delete

POST/v1/tenants/bulk/set

Bulk delete tenants

Delete up to 1,000 tenants at a time in a single operation. This operation cannot be undone.

Endpoint

POST/v1/tenants/bulk/delete

Tier 1

Query parameters

tenant_ids[]

string[]

The IDs of the tenants to delete.

Returns

BulkOperation

A bulk operation entity.

__typename

string

The typename of the schema.

completed_at

string(date-time)

Timestamp when the bulk operation was completed.

error_count

integer

The number of failed operations.

error_items

object[]

A list of items that failed to be processed.

collection

string

The collection this object belongs to.

string

Required

Unique identifier for the object.

estimated_total_rows

integer

The estimated total number of rows to process.

failed_at

string(date-time)

Timestamp when the bulk operation failed.

string(uuid)

Unique identifier for the bulk operation.

inserted_at

string(date-time)

Timestamp when the resource was created.

name

string

The name of the bulk operation.

processed_rows

integer

The number of rows processed so far.

progress_path

string(uri)

The URI to the bulk operation's progress.

started_at

string(date-time)

Timestamp when the bulk operation was started.

status

enum(string)

The status of the bulk operation.

queuedprocessingcompletedfailed

success_count

integer

The number of successful operations.

updated_at

string(date-time)

The timestamp when the resource was last updated.

Bulk set tenants

Set or update up to 1,000 tenants in a single operation.

Endpoint

POST/v1/tenants/bulk/set

Tier 1

Request body

tenants

InlineTenantRequest[]

Required

The tenants to be upserted.

Returns

BulkOperation

A bulk operation entity.

__typename

string

The typename of the schema.

completed_at

string(date-time)

Timestamp when the bulk operation was completed.

error_count

integer

The number of failed operations.

error_items

object[]

A list of items that failed to be processed.

collection

string

The collection this object belongs to.

string

Required

Unique identifier for the object.

estimated_total_rows

integer

The estimated total number of rows to process.

failed_at

string(date-time)

Timestamp when the bulk operation failed.

string(uuid)

Unique identifier for the bulk operation.

inserted_at

string(date-time)

Timestamp when the resource was created.

name

string

The name of the bulk operation.

processed_rows

integer

The number of rows processed so far.

progress_path

string(uri)

The URI to the bulk operation's progress.

started_at

string(date-time)

Timestamp when the bulk operation was started.

status

enum(string)

The status of the bulk operation.

queuedprocessingcompletedfailed

success_count

integer

The number of successful operations.

updated_at

string(date-time)

The timestamp when the resource was last updated.

Tenant

A tenant entity.

Attributes

__typename

string

The typename of the schema.

string

The unique identifier for the tenant.

name

string

An optional name for the tenant.

settings

object

The settings for the tenant. Includes branding and preference set.

branding

object

The branding for the tenant.

icon_url

string(uri)

The icon URL for the tenant. Must point to a valid image with an image MIME type.

logo_url

string(uri)

The logo URL for the tenant. Must point to a valid image with an image MIME type.

primary_color

string

The primary color for the tenant, provided as a hex value.

primary_color_contrast

string

The primary color contrast for the tenant, provided as a hex value.

preference_set

PreferenceSet

The preference set for the tenant. Used to override the default preference set.

object(any)

Any additional custom properties.

TenantRequest

A tenant to be set in the system. You can supply any additional properties on the tenant object.

Attributes

channel_data

InlineChannelDataRequest

The channel data for the tenant.

string

The unique identifier for the tenant.

name

string

An optional name for the tenant.

preferences

InlinePreferenceSetRequest

The preferences for the tenant.

settings

object

The settings for the tenant. Includes branding and preference set.

branding

object

The branding for the tenant.

icon_url

string

The icon URL for the tenant. Must point to a valid image with an image MIME type.

logo_url

string

The logo URL for the tenant. Must point to a valid image with an image MIME type.

primary_color

string

The primary color for the tenant, provided as a hex value.

primary_color_contrast

string

The primary color contrast for the tenant, provided as a hex value.

preference_set

PreferenceSetRequest

The preference set for the tenant. Used to override the default preference set.

object(any)

Any additional custom properties.

InlineTenantRequest

An request to set a tenant inline.

Attributes

InlineTenantRequest

2 possible types

An request to set a tenant inline.