---
title: "Create / Update Tenants"
method: POST
path: "/v1/tenant/{tenant_id}/"
---

# Create / Update Tenants

`POST /v1/tenant/{tenant_id}/`

API to create a new Tenant OR update an existing Tenant

## Path parameters

- `tenant_id` string, required

## Request body

- object
  - `name` string, required — Tenant display name. Replaces the legacy `tenant_name` field; both are accepted.
  - `tenant_name` string — Will be deprecated in future. Use `name` instead.
  - `parent_id` string, 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](/docs/sub-tenants).
  - `blocked_channels` string[], 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](/docs/notification-category#root-categories) (which users normally can't unsubscribe from) — and users can't override this. If [sub-tenants](/docs/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`.
  - `logo` string — Tenant logo URL.
  - `primary_color` string — 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_color` string — 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_color` string — 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_url` string — URL of your product's preference page.
  - `social_links` object — Tenant's social media URLs. Pass `""` to clear a link (not `null`).
    - `website` string — Website URL.
    - `facebook` string — Facebook page URL.
    - `LinkedIn` string — LinkedIn page URL.
    - `x` string — X (formerly Twitter) page URL.
    - `instagram` string — Instagram page URL.
    - `medium` string — Medium page URL.
    - `discord` string — Discord URL.
    - `telegram` string — Telegram URL.
    - `youtube` string — YouTube channel URL.
    - `tiktok` string — TikTok URL.
  - `properties` object — Custom tenant properties. Merged per top-level key on update — keys not in the payload are kept as-is.

## Response `201`

201 - Created

- object — 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](/docs/sub-tenants)), unset fields stay unresolved and the tenant simply has no value for them. For [sub-tenants](/docs/sub-tenants), unset fields still return `null` here, but are resolved from the closest ancestor that has a value set at trigger time.

## Other responses

- `400` — 400 - Bad Request

## Changes

- **2026-08-30** `ea7b2f7c41a9` — 1 breaking, 1 warning, 5 info
  - added the pattern `^[a-z0-9_.-]+$` to the `path` request parameter `tenant_id`
  - for the `path` request parameter `tenant_id`, the maxLength was set to `64`
  - added the new optional request property `blocked_channels`
  - added the new optional request property `parent_id`
  - …3 more

[Change history](https://skmtc.dev/suprsend/apis/suprsend-api/changes/v1/tenant/:tenant_id/post.md)

---

[API](https://skmtc.dev/suprsend/apis/suprsend-api.md) · [All operations](https://skmtc.dev/suprsend/apis/suprsend-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/suprsend/suprsend-api/revisions/ea7b2f7c41a9/schema)