> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create / Update Tenants > API to create a new Tenant OR update an existing Tenant ## OpenAPI ````yaml POST /v1/tenant/{tenant_id}/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /v1/tenant/{tenant_id}/: post: summary: Create / Update Tenants description: API to create a new Tenant OR update an existing Tenant operationId: create-tenants parameters: - name: tenant_id in: path description: >- Tenant identifier to create or update. Max 64 chars; allowed characters `[a-z0-9_.-]`. schema: type: string pattern: ^[a-z0-9_.-]+$ maxLength: 64 required: true requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: >- Tenant display name. Replaces the legacy `tenant_name` field; both are accepted. default: Awesome Tenant tenant_name: type: string description: Will be deprecated in future. Use `name` instead. parent_id: type: string nullable: true description: >- 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). example: acme-corp blocked_channels: type: array items: type: string nullable: true description: >- 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`. example: - sms logo: type: string description: Tenant logo URL. default: >- https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png primary_color: type: string description: >- 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. default: '#ff0000' secondary_color: type: string description: >- 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. example: '#00ff00' tertiary_color: type: string description: >- 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. example: '#0000ff' preference_page_url: type: string description: URL of your product's preference page. social_links: type: object description: >- Tenant's social media URLs. Pass `""` to clear a link (not `null`). properties: website: type: string description: Website URL. default: https://suprsend.com facebook: type: string description: Facebook page URL. LinkedIn: type: string description: LinkedIn page URL. x: type: string description: X (formerly Twitter) page URL. instagram: type: string description: Instagram page URL. medium: type: string description: Medium page URL. discord: type: string description: Discord URL. telegram: type: string description: Telegram URL. youtube: type: string description: YouTube channel URL. tiktok: type: string description: TikTok URL. properties: type: object description: >- Custom tenant properties. Merged per top-level key on update — keys not in the payload are kept as-is. additionalProperties: type: string responses: '201': description: 201 - Created content: application/json: examples: Result: value: id: acme-corp name: Awesome Tenant tenant_id: acme-corp tenant_name: Awesome Tenant parent_id: null ancestors: [] level: 0 children_count: 0 logo: >- https://ik.imagekit.io/l0quatz6utm/suprsend/staging/media/suprsend-only-logo_c8aa27faef118418e8c5bd7b31a1cafc74e09200.png timezone: null blocked_channels: - sms 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: '' linkedin: '' x: '' instagram: '' medium: '' discord: '' telegram: '' youtube: '' properties: region: US support_email: help@example.com updated_at: '2026-08-27T21:01:35.359787Z' schema: type: object description: >- 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. '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 security: - BearerAuth: [] components: securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ````