SuprSend Tenant API
The Tenant API from SuprSend — 7 operation(s) for tenant.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast Tenant API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Tenant
paths:
/v1/tenant/{tenant_id}/:
post:
summary: Create / Update Tenants
security:
- BearerAuth: []
description: API to create a new Tenant OR update an existing Tenant
operationId: create-tenants
parameters:
- name: tenant_id
in: path
description: unique identifier of the tenant that you want to create / update
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- tenant_name
properties:
tenant_name:
type: string
description: Name of the tenant. You can add company / organization name here
default: Awesome Tenant
logo:
type: string
description: URL of the tenant logo
default: https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png
primary_color:
type: string
description: Primary color of the tenant - used for designing tenant template. If you don't provide any of the colors for the tenant, SuprSend will assume you want to use the default values, so color settings will automatically be set to the color settings of default tenant.
default: '#ff0000'
secondary_color:
type: string
description: Secondary color of the tenant - not used for designing the default templates. You can however add this property and use it in your templates
example: '#00ff00'
tertiary_color:
type: string
description: Tertiary color of the tenant - not used for designing the default templates. You can however add this property and use it in your templates
example: '#0000ff'
preference_page_url:
type: string
description: Link of the preference page inside the tenant product
social_links:
type: object
description: urls of social media accounts of the tenant. If you really want to remove any social link, you must set its value="" (instead of null)
properties:
website:
type: string
description: link of tenant website. While updating a social link, if you want to remove the link, you must the value="" (instead of null)
default: https://suprsend.com
facebook:
type: string
description: tenant facebook page link
LinkedIn:
type: string
description: tenant linkedin page link
x:
type: string
description: tenant x(previously twitter) page link
instagram:
type: string
description: tenant instagram page link
medium:
type: string
description: tenant medium page link
discord:
type: string
description: tenant discord page link
telegram:
type: string
description: tenant telegram page link
youtube:
type: string
description: tenant youtube page link
tiktok:
type: string
description: tenant tiktok page link
properties:
type: object
description: Custom properties associated with the tenant. Update operation on properties works like upsert on 1st-level keys (i.e., if top-level key doesn't already exist, then it will be added, otherwise its value will be replaced by the new value. All other key-value pairs will remain unchanged).
additionalProperties:
type: string
responses:
'201':
description: 201 - Created
content:
application/json:
examples:
Result:
value:
tenant_id: brand_id
tenant_name: Awesome Tenant
logo: https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png
timezone: null
blocked_channels:
- email
embedded_preference_url: https://app.suprsend.com/settings
hosted_preference_domain: preferences.suprsend.com
primary_color: '#ff0000'
secondary_color: '#0000ff'
tertiary_color: '#00ffff'
social_links:
website: https://suprsend.com
facebook: https://www.company.com
LinkedIn: ''
x: ''
instagram: ''
medium: ''
discord: ''
telegram: ''
youtube: ''
properties:
k1: v1
address: my company address
updated_at: '2025-04-06T21:01:35.359787Z'
schema:
type: object
description: Updated Object Payload is returned in response. JSON structure similar to request payload.
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
code: 400
error_code: error
type: ValidationError
message: '{"tenant_name": ["Ensure this field contains non-html text"]}'
detail:
tenant_name:
- Ensure this field contains non-html text
schema:
type: object
description: error code and message detailing the error
deprecated: false
tags:
- Tenant
get:
summary: Get Tenant data
security:
- BearerAuth: []
description: API to fetch tenant settings (logo, colors, links, preference) corresponding to a tenant_id. To create or update tenant data, use the [Create/Update Tenant](#create-update-tenants) endpoint. To create or update tenant data, use the [Create/Update Tenant](#create-update-tenants) endpoint. To create or update tenant data, use the [Create/Update Tenant](#operation/create-tenants) endpoint.
operationId: get-tenant
parameters:
- name: tenant_id
in: path
description: unique identifier of the tenant you want to get the details for
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
tenant_id: _tenant_id_
tenant_name: Awesome Tenant
logo: https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png
timezone: null
blocked_channels:
- email
embedded_preference_url: https://app.suprsend.com/en/user-settings/notifications
hosted_preference_domain: preferences.suprsend.com
primary_color: '#ff0000'
secondary_color: '#0000ff'
tertiary_color: '#00ffff'
social_links:
website: https://suprsend.com
facebook: https://www.company.com
linkedin: ''
x: ''
instagram: ''
medium: ''
discord: ''
telegram: ''
youtube: ''
tiktok: ''
properties:
k1: v1
address: my company address
updated_at: '2025-04-06T21:01:35.359787Z'
schema:
type: object
description: Updated Object Payload is returned in response. JSON structure similar to [request payload](/reference/create-update-tenants).
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: No tenant found for tenant_id tenant
detail: No tenant found for tenant_id tenant
schema:
type: object
description: error code and message detailing the error
deprecated: false
tags:
- Tenant
delete:
summary: Delete Tenant
security:
- BearerAuth: []
description: API to permanently delete tenant and it's associated settings.
operationId: delete-tenant
parameters:
- name: tenant_id
in: path
description: unique identifier of the tenant you want to get the details for
schema:
type: string
required: true
responses:
'204':
description: 204 - No Content
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
error_code: not_found
type: NotFound
message: No tenant found for tenant_id 12
detail: No tenant found for tenant_id 12
schema:
type: object
description: error code and message detailing the error
deprecated: false
tags:
- Tenant
/v1/tenant/:
get:
summary: Get Tenant List
security:
- BearerAuth: []
description: API to fetch a paginated list of tenants available in your workspace.
operationId: get-tenant-list
parameters:
- name: limit
in: query
description: number of results to be returned in API response
schema:
type: integer
default: 20
- name: offset
in: query
description: starting position of tenant list
schema:
type: integer
responses:
'200':
description: 200 - OK
content:
application/json:
examples:
Result:
value:
meta:
count: 28
limit: 20
offset: 0
results:
- tenant_id: random_id
tenant_name: Awesome Tenant
logo: https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png
timezone: null
blocked_channels: null
embedded_preference_url: https://app.suprsend.com/en/user-settings/notifications
hosted_preference_domain: preferences.suprsend.com
primary_color: '#ff0000'
secondary_color: null
tertiary_color: null
social_links:
website: https://suprsend.com
facebook: ''
linkedin: ''
x: ''
instagram: ''
medium: ''
discord: ''
telegram: ''
youtube: ''
properties: {}
updated_at: '2025-04-06T20:57:16.935605Z'
schema:
type: object
properties:
meta:
type: object
properties:
count:
type: integer
example: 28
description: Total number of results returned.
limit:
type: integer
example: 20
description: Maximum number of results per page.
offset:
type: integer
example: 0
description: offset passed in request
results:
type: array
description: List of tenants available in the workspace. Tenant JSON is same as tenant upsert response.
items:
type: object
properties:
tenant_id:
type: string
description: Unique identifier of the tenant.
example: random_id
tenant_name:
type: string
description: Name of the tenant.
example: Awesome Tenant
logo:
type: string
format: uri
description: URL of the tenant logo.
example: https://logo.png
timezone:
type: string
nullable: true
description: timezone of the tenant. Used as fallback if user's timezone is not set.
example: America/New_York
blocked_channels:
type: string
nullable: true
examples:
email:
summary: Email channel
value: email
sms:
summary: SMS channel
value: sms
description: channels that are blocked for the tenant.
embedded_preference_url:
type: string
format: uri
example: https://app.suprsend.com/en/user-settings/notifications
description: url of the preference page inside the tenant product.
hosted_preference_domain:
type: string
example: preferences.suprsend.com
description: domain of the hosted preference page.
primary_color:
type: string
description: Primary color of the tenant used for template design.
example: '#ff0000'
secondary_color:
type: string
nullable: true
description: Secondary color of the tenant.
example: '#ff0000'
tertiary_color:
type: string
nullable: true
description: Tertiary color of the tenant.
example: '#ff0000'
social_links:
type: object
description: Social media links associated with the tenant.
properties:
website:
type: string
example: https://suprsend.com
facebook:
type: string
example: ''
linkedin:
type: string
example: ''
x:
type: string
example: ''
instagram:
type: string
example: ''
medium:
type: string
example: ''
discord:
type: string
example: ''
telegram:
type: string
example: ''
youtube:
type: string
example: ''
properties:
type: object
description: Custom properties associated with the tenant.
additionalProperties: true
example:
address: my company address
updated_at:
type: string
format: date-time
description: Timestamp when the tenant was last updated.
example: '2025-04-06T20:57:16.935605Z'
deprecated: false
tags:
- Tenant
/v1/tenant/{tenant_id}/category/{category_slug}/:
patch:
summary: Update Tenant Default Preference
security:
- BearerAuth: []
description: API to update tenant default preferences for a specific notification category.
operationId: update-brand-default-preference
x-codeSamples:
- lang: cURL
label: Update Tenant Default Preference
source: "curl -X PATCH \"https://hub.suprsend.com/v1/tenant/brand_id/preference/status-update-alert/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"preference\": \"opt_in\",\n \"visible_to_subscriber\": true\n }'\n"
parameters:
- name: tenant_id
in: path
description: unique identifier of the brand/tenant you want to update default preferences for
schema:
type: string
required: true
- name: category_slug
in: path
description: notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
preference:
type: string
description: set `**opt_in**` to turn on notifications on all or selected channels by default, `**opt_out**` to turn-off notifications by default, `**cant_unsubscribe**`if you do not want users to completely opt-out from this category.
enum:
- opt_in
- opt_out
- cant_unsubscribe
visible_to_subscriber:
type: boolean
description: set it `false` to hide a category from user's preference page
mandatory_channels:
type: array
description: Add mandatory channels that the user can't unsubscribe from if preference is `cant_unsubscribe`.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
- ms_teams
opt_in_channels:
type: array
nullable: true
description: Add channels that should be opted-in by default when preference is either `On` or `Can't Unsubscribe`. Set to null or do not pass this parameter to set all channels as opted-in. In case of `Can't Unsubscribe`, mandatory channels are opted-in by default.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
- ms_teams
blocked_channels:
type: array
nullable: true
description: Pass channels which are not applicable for the tenant. This setting will apply to all categories and user will not be able to opt-in to these channels for the tenant.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
- ms_teams
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value:
name: Status Update Alert
category: status-update-alert
description: Send me updates when account status changes
root_category: transactional
default_preference: opt_in
default_mandatory_channels: null
default_opt_in_channels:
- email
- sms
visible_to_subscriber: true
preference: opt_in
mandatory_channels: null
opt_in_channels: null
blocked_channels: null
schema:
type: object
properties:
name:
type: string
description: preference category name
category:
type: string
description: unique preference category slug. You can get it by clicking on category name on SuprSend dashboard -> preference page
description:
type: string
description: description of the notification category
root_category:
type: string
description: root category this sub-category belongs to
example: transactional
default_preference:
type: string
enum:
- cant_unsubscribe
- opt_in
- opt_out
description: default preference of the category set while updating the category.
default_mandatory_channels:
type: array
description: default mandatory channels set while updating the category in case default preference is can't unsubscribe
items:
type: string
default_opt_in_channels:
type: array
nullable: true
description: default opt-in channels set to have selective opt-in channels instead of all channels while updating the category.
items:
type: string
opt_in_channels:
type: array
nullable: true
description: opt-in channels overridden for this tenant.
items:
type: string
visible_to_subscriber:
type: boolean
description: set it `false` to hide a category from user's preference page
preference:
type: string
enum:
- opt_in
- opt_out
description: preference setting overridden for this tenant.
blocked_channels:
type: array
description: channels which are opted-out across all categories for this tenant.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
- ms_teams
'404':
description: '404'
content:
application/json:
examples:
Result:
value:
code: 404
message: tenant 'brand/tenant_id' not found
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: tenant 'brand/tenant_id' not found
tags:
- Tenant
/v1/tenant/{tenant_id}/preference/:
get:
summary: Get Tenant Full Preference
security:
- BearerAuth: []
description: API to fetch tenant preferences across all categories with translated names and descriptions.
operationId: get-tenant-full-preference
parameters:
- name: tenant_id
in: path
description: unique identifier of the tenant you want to get preferences for
schema:
type: string
required: true
- name: locale
in: query
description: "Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch preference translations in user's locale. When provided, the API looks for category and section names and descriptions in the respective locale file. \nIf a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).\n"
schema:
type: string
example: es
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
root_categories:
- root_category: system
sections:
- name: section système
slug: system-section
description: section système
tags:
- wwr
categories:
- name: Sous-catégorie
category: sub-category
description: Description de la sous-catégorie
tags:
- gjhgjhfjfjgfdjthdhtdhdhdyrhdyrdyrdrh
- aaaaeeee
effective_tags:
- aaaaeeee
- gjhgjhfjfjgfdjthdhtdhdhdyrhdyrdyrdrh
- wwr
default_preference: cant_unsubscribe
default_mandatory_channels:
- email
default_opt_in_channels:
- inbox
enabled_for_tenant: true
visible_to_subscriber: true
preference: opt_in
mandatory_channels: null
opt_in_channels: null
blocked_channels:
- sms
updated_at: '2025-12-04T10:45:39.061095+00:00'
schema:
type: object
properties:
root_categories:
type: array
items:
type: object
properties:
root_category:
type: string
enum:
- system
- transactional
- promotional
sections:
type: array
items:
type: object
properties:
name:
type: string
nullable: true
slug:
type: string
nullable: true
description:
type: string
nullable: true
tags:
type: array
nullable: true
items:
type: string
categories:
type: array
items:
type: object
properties:
name:
type: string
category:
type: string
description:
type: string
nullable: true
tags:
type: array
nullable: true
items:
type: string
effective_tags:
type: array
nullable: true
items:
type: string
default_preference:
type: string
enum:
- opt_in
- opt_out
- cant_unsubscribe
default_mandatory_channels:
type: array
nullable: true
items:
type: string
default_opt_in_channels:
type: array
nullable: true
items:
type: string
enabled_for_tenant:
type: boolean
visible_to_subscriber:
type: boolean
preference:
type: string
nullable: true
enum:
- opt_in
- opt_out
- cant_unsubscribe
mandatory_channels:
type: array
nu
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-tenant-api-openapi.yml