> ## 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.

# Tenants

> Learn how to create, update, fetch, & list tenants using NodeJS SDK.

Tenants (previously named as brands) are used for white labeling notifications, personalizing template content or capturing admin preferences for another entity/organization. Tenants are workspace-level entities and by default, a tenant with `tenant_id="default"` (representing your organization) is created your workspace.

Read more about tenants [here](/docs/tenants).

## Create / Update tenant

This method will create a new tenant or update an existing tenant.

<CodeGroup>
  ```javascript Request theme={"system"}
  const { Suprsend } = require("@suprsend/node-sdk");

  const supr_client = new Suprsend("workspace_key", "workspace_secret")

  const tenant_payload = {...} // prepare tenant datastructure payload

  // ---- Optional Parameters -------
  const requestData = {
      secondary_color: "#00ff00",
      tertiary_color: "#0000ff",
      timezone: "America/New_York",
      // blocked channels will be skipped triggering notifications for this tenant.
      blocked_channels: ["email"],
      social_links: {
          website: "https://suprsend.com",
          facebook: "",
          linkedin: "",
          x: "",
          instagram: "",
          medium: "",
          discord: "",
          telegram: "",
          youtube: "",
          tiktok: ""
      },
      // In-product Notification center link for capturing user preferences.
      embedded_preference_url: "",
      properties: {
          prop1: "value1",
          prop2: { prop3: ["value2"] }
      }
  };

  // create or update tenant
  const response = supr_client.tenants.upsert(tenant_id, tenant_payload);
  response.then((res) => console.log("response", res));
  ```
</CodeGroup>

| Field                                 | Description                                                                                                                                                               |
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| tenant\_id (mandatory)                | max 64 characters and should contains alphanumeric characters(a-z, 0-9), hyphen (-) and underscode(\_).                                                                   |
| tenant\_name (mandatory)              | name of the tenant.                                                                                                                                                       |
| colors (primary, secondary, tertiary) | used while designing templates. If not provided `default` tenant colour will be picked.                                                                                   |
| social\_links                         | social links to your tenant. Pass `""` if you want to remove existing link.                                                                                               |
| properties                            | Custom properties associated with the tenant. Update operation is upsert (new properties are added to existing one's and if key is already present, value is overridden). |

All properties of the tenant can be referred as `{{$tenant.prop}}` (handlebars) or `data["tenant"].prop` in JSONNET format.

## Get tenant

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = supr_client.tenants.get(tenant_id)
  ```

  ```javascript Response theme={"system"}
  {
     "tenant_id":"tenant_id",
     "tenant_name":"ABC Company",
     "logo":"https://logo_url.png",
     "timezone":"America/New_York",
     "blocked_channels":[
        "whatsapp",
        "email"
     ],
     "embedded_preference_url":"https://app.suprsend.com/preferences",
     "hosted_preference_domain":"preferences.suprsend.com",
     "primary_color":"#0751E8",
     "secondary_color":"#e308e3",
     "tertiary_color":"#1EE9F1",
     "social_links":{
        "website":"https://www.suprsend.com/",
        "facebook":"",
        "linkedin":"",
        "x":"",
        "instagram":"",
        "medium":"",
        "discord":"",
        "telegram":"",
        "youtube":"",
        "tiktok":""
     },
     "properties":{
        "address":"5678 Market Street Suite 300 San Francisco, CA 94103 USA"
     },
     "updated_at":"2025-02-27T10:21:15.235666Z"
  }
  ```
</CodeGroup>

## List tenants

By default, `limit=20`. The maximum value for `limit` is `1000`.

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = supr_client.tenants.list();  // default limit 20
  const response = supr_client.tenants.list({limit:20, offset:0}); //  max limit 1000
  ```

  ```javascript Response theme={"system"}
  {
     "meta":{
        "count":28,
        "limit":20,
        "offset":0
     },
     "results":[
        {
           "tenant_id":"tenant_01",
           "tenant_name":"ABC Company",
           "logo":"https://logo.url",
           ...
           "updated_at":"2025-03-13T18:16:35.744843Z"
        },
  	  {
           "tenant_id":"tenant_02",
           "tenant_name":"CDE Company",
           "logo":"https://logo.url",
           ...
           "updated_at":"2025-03-13T18:16:35.744843Z"
        }
  	...
     ]
  }
  ```
</CodeGroup>

## Add tenant in workflow

<CodeGroup>
  ```javascript Request theme={"system"}
  const wf = new Workflow(workflow_body, {tenant_id :  "_tenant_id_"})
  ```
</CodeGroup>

## Add tenant in event

<CodeGroup>
  ```javascript Request theme={"system"}
  const event = new Event(distinct_id, event_name, properties, {tenant_id :  "_tenant_id_"})
  ```
</CodeGroup>

***