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

# Objects

> Create, update, & manage objects and their subscriptions using NodeJS SDK.

Objects in SuprSend represent non-user entities such as organizations, teams , roles, and projects. Understand more about objects from our [objects documentation](/docs/objects)

## Upsert (create/update) an object

Object updating is an upsert function, meaning it would always override existing key values on further updates. Object id and type is mandatory to create object. You can optionally pass object properties (to use in template or workflow condition) or channel information (send notification on object channels) in the payload.

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

  // Initialize SDK
  const supr_client = new Suprsend("Workspace_Key", "Workspace_Secret")

  res = supr_client.objects.upsert("object_type", "object_id");
  res.then((res) => console.log(res)).catch((err) => console.log(err));
  ```

  ```javascript Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "key1": "val1"
        },
     "created_at":"2025-01-20T19:21:42.030343+00:00",
     "updated_at":"2025-02-14T14:06:05.928675+00:00",
     "$inbox":[
        {
           "value":"H4iGeGSHyXXXXXXSeuBb_PJGXXXgWu_LsXXXXXyiw",
           "id_provider":"suprsend",
           "status":"active",
           "perma_status":"active"
        }
     ],
  	"$email":[
        {
           "value":"abc@example.com",
           "status":"active",
           "perma_status":"active"
        }
     ]
  }
  ```
</CodeGroup>

## Edit an object

There are 2 ways in which you can edit an object data.

* Build edit payload yourself
* Use helper methods provided by SDK (Recommended)

### 1. Build edit payload yourself

Use this to modify an object, typically for removing channels or unsetting properties. The payload will follow the same structure as the [<u>Object Edit</u>](https://docs.suprsend.com/reference/edit-object-profile) API.

<CodeGroup>
  ```javascript Request theme={"system"}
  //for all supported operations, refer API documentation
  const payload = {operations: [{$unset: ["name"]}, {$remove: {"$email": "abc@example.com"}}]}

  const response = await supr_client.objects.edit(object_type, object_id, payload};
  ```

  ```javascript Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "name":"John Doe"
     },
     "created_at":"2025-03-14T15:31:59.151061+00:00",
     "updated_at":"2025-03-14T15:31:59.182616+00:00",
     "$inbox":[
        {
           "value":"75Ev_m8yln0N_i1iXXXXXXr2eNOE_4ROXXXXXX1TgTc",
           "id_provider":"suprsend",
           "status":"active",
           "perma_status":"active"
        }
     ]
  }
  ```
</CodeGroup>

### 2. Edit using helper methods \[Recommended]

It is possible to use the SDK's helper methods to perform edit operations on an object.

For this, first create object instance then call any of the helper methods mentioned below and finally save the changes.

<CodeGroup>
  ```javascript Request theme={"system"}
  // create instance
  const object_instance = supr_client.objects.get_instance(object_type, object_id);

  // call any helper methods
  object_instance.set(key, value);
  object_instance.add_email("johndoe@gmail.com");

  // save the changes
  const response = await supr_client.objects.edit(object_instance);
  ```

  ```javascript Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "$preferred_language":"en",
        "$timezone":"America/Los_Angeles",
        "company_name":"ABC company"
     },
     "created_at":"2025-03-04T08:34:58.061696+00:00",
     "updated_at":"2025-03-14T14:40:21.467156+00:00",
     "$inbox":[
        {
           "value":"dHvPs6pmUXXXXXXTAsfM2yroXXXX2CXZOtjXXXXXX8",
           "id_provider":"suprsend",
           "status":"active",
           "perma_status":"active"
        }
     ]
  }
  ```
</CodeGroup>

Here's a list of all edit helper methods:

<AccordionGroup>
  <Accordion title="Add Channels">
    Use `object_ins.add_*` method(s) to add user channels in a profile

    <CodeGroup>
      ```javascript Request theme={"system"}

      // add Email
      object_instance.add_email("object_ins@example.com");

      // add Email
      object_instance.add_sms("+15555555555");

      // add Whatsapp
      object_instance.add_whatsapp("+15555555555");

      // add fcm push token
      object_instance.add_androidpush("__android_push_fcm_token__");

      // add apns push token
      object_instance.add_iospush("__iospush_token__");

      // add Slack using email
      object_instance.add_slack(
        {
          "email": "user@example.com",
          "access_token": "xoxb-XXXXXXXX"
        });

      // add Slack if slack member_id is known
      object_instance.add_slack(
        {
          "user_id": "U03XXXXXXXX",
          "access_token": "xoxb-XXXXXXXX"
        });

      // add Slack channel
      object_instance.add_slack(
        {
          "channel_id": "CXXXXXXXX",
          "access_token": "xoxb-XXXXXXXX"
        });

      // add Slack incoming webhook
      object_instance.add_slack(
        {
          "incoming_webhook": {
            "url": "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
          }
        });

      // add MS teams user or channel using conversation_id
      object_instance.add_ms_teams(
        {
          "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
          "service_url": "https://smba.trafficmanager.net/amer",
          "conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
        });

      // add MS teams user using user_id
      object_instance.add_ms_teams(
        {
          "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
          "service_url": "https://smba.trafficmanager.net/amer",
          "object_ins_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
        });

      // add MS teams using incoming webhook
      object_instance.add_ms_teams(
        {
          "incoming_webhook": {
            "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
          }
        });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Remove Channels">
    Use `object_ins.remove_*` method(s) to remove channels from an object profile

    <CodeGroup>
      ```javascript Request theme={"system"}

      // remove Email
      object_instance.remove_email("object_ins@example.com");

      // remove SMS
      object_instance.remove_sms("+15555555555");

      // remove Whatsapp
      object_instance.remove_whatsapp("+15555555555");

      // remove fcm push token
      object_instance.remove_androidpush("__android_push_fcm_token__"); // - by default, token is assumed to be fcm-token

      // remove apns push token
      object_instance.remove_iospush("__iospush_token__");

      // remove Slack email
      object_instance.remove_slack(
        {
          "email": "object_ins@example.com",
          "access_token": "xoxb-XXXXXXXX"
        });

      // remove Slack if slack member_id is known
      object_instance.remove_slack(
        {
          "object_ins_id": "U03XXXXXXXX",
          "access_token": "xoxb-XXXXXXXX"
        });

      // remove Slack channel
      object_instance.remove_slack(
        {
          "channel_id": "CXXXXXXXX",
          "access_token": "xoxb-XXXXXXXX"
        });

      // remove Slack incoming webhook
      object_instance.remove_slack(
        {
          "incoming_webhook": {
            "url": "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
          }
        });

      // add MS teams user or channel using conversation_id
      object_instance.remove_ms_teams(
        {
          "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
          "service_url": "https://smba.trafficmanager.net/amer",
          "conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
        });

      // add MS teams user using user_id
      object_instance.remove_ms_teams(
        {
          "tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
          "service_url": "https://smba.trafficmanager.net/amer",
          "object_ins_id": "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
        });

      // add MS teams using incoming webhook
      object_instance.remove_ms_teams(
        {
          "incoming_webhook": {
            "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
          }
        });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Remove Channels in bulk">
    If you need to delete/unset all emails (or any other channel) of an object, you can call `object_ins.unset()` method on the object instance. The method accepts the channel key/s (a single key or list of keys)

    <CodeGroup>
      ```javascript Request theme={"system"}
      object_instance.unset("$email");
      object_instance.unset(["$email", "$sms", "$whatsapp"]);

      // available channel keys -
      //["$email","$whatsapp","$sms","$androidpush","$iospush","$webpush","$slack","$ms_teams"]

      // --- multiple channels can also be deleted in one call by passing argument as a list
      object_ins.unset(["$email", "$sms", "$whatsapp"]);
      res = object_ins.save();
      res.then((res) => console.log(res)).catch((err) => console.log(err));
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Set Preferred language">
    <CodeGroup>
      ```javascript Request theme={"system"}
      object_instance.set_preferred_language("en");
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Set Preferred Timezone">
    <CodeGroup>
      ```javascript Request theme={"system"}
      object_instance.set_timezone("America/Belize");
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Set">
    Set is used to set the custom property or properties. The given name and value will be assigned to the object, overwriting an existing property with the same name if present. It can take key as first param, value as second param for setting single object property or object for setting multiple object properties.

    <CodeGroup>
      ```javascript Request theme={"system"}
      //For setting single property
      object_instance.set("key", "value");

      //For multiple Properties
      object_instance.set({
        "prop1": "val1",
        "prop2": ["one", "two", "three"],
        "number": 20
      });
      ```
    </CodeGroup>

    | Parameters | Type              | Description                                                                                                                                                                                                                                                                                   |
    | :--------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **arg1**   | string/dictionary | *Mandatory* This param will be string in case where only single property needs to be created/updated. It will be a dictionary in cases where complex objects need to be set in object properties, like multiple properties, arrays, nested properties etc. Should not start with `$` or `ss_` |
    | **arg2**   | any               | *Optional* This will be value that will be attached to key property. Not required in cases where first param is a dictionary.                                                                                                                                                                 |

    <Warning>
      When you create a key, please ensure that the Key Name does not start with  or , as we have reserved these symbols for our internal events and property names.
    </Warning>
  </Accordion>

  <Accordion title="Set Once">
    Works just like `object_ins.set`, except it will not overwrite existing property values. This is useful for properties like *First login date*

    <CodeGroup>
      ```javascript Request theme={"system"}
      // For setting once a single property:
      object_instance.set_once(key, value);
      object_instance.set_once("first_login", "2021-11-02");

      // For setting once multiple properties
      object_instance.set_once(properties);
      object_instance.set_once({"first_login" : "2021-11-02", "DOB" : "1991-10-02"});
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Increment">
    Add the given amount to an existing property on the object. If the object does not already have the associated property, the amount will be added to zero. To reduce a property, provide a negative number for the value.

    <CodeGroup>
      ```javascript Request theme={"system"}
      // For incrementing a single property:
      object_instance.increment(key, value);
      object_instance.increment("login_count", 1);

      // For incrementing multiple properties:
      object_instance.increment(property_obj);
      object_instance.increment({"login_count" : 1, "remaining_credits" : -1});
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Append">
    This method will append a value to the list for a given property.

    <CodeGroup>
      ```javascript Request theme={"system"}
      // For appending a single property:
      object_instance.append.append(key, value);
      object_instance.append.append("wishlist", "iphone12");

      // For appending multiple properties:
      object_instance.append.append(properties);
      object_instance.append.append({"wishlist" : "iphone12", "cart" : "Apple airpods"});
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Remove">
    This method will remove a value from the list for a given property.

    <CodeGroup>
      ```javascript Request theme={"system"}
      // For removing a single property:
      object_instance.remove(key, value);
      object_instance.remove("wishlist", "iphone12");

      // For removing multiple properties:
      object_instance.remove(properties);
      object_instance.remove({"wishlist" : "iphone12", "wishlist": "Apple airpods"});
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Unset">
    This will remove a property permanently from properties.

    <CodeGroup>
      ```javascript Request theme={"system"}
      // For unsetting a single property:
      object_instance.unset(key);
      object_instance.unset("wishlist");

      // For unsetting multiple properties:
      object_instance.unset(property_list);
      object_instance.unset(["wishlist", "cart"]);
      ```
    </CodeGroup>

    | Parameters         | Type           | Description                                                       |
    | :----------------- | :------------- | :---------------------------------------------------------------- |
    | **key**            | string         | This property provided will be deleted from object properties     |
    | **property\_list** | array\[string] | If list is given all properties included in list will be removed. |
  </Accordion>
</AccordionGroup>

<Warning>
  After calling `add_*/remove_*/unset` methods, don't forget to call `object_ins.save()`. On call of save(), SDK sends the request to SuprSend platform to update the Object Profile.
</Warning>

## List objects

List objects for an `object_type`. You can also pass listing options in the payload which includes `limit`,`before`,`after`

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.list(object_type,{"limit":10, "after:"cursor"});
  ```
</CodeGroup>

## Get object details

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.get(object_type, object_id);
  ```
</CodeGroup>

## Create subscriptions

<CodeGroup>
  ```javascript Request theme={"system"}
  const payload = {
    "recipients": ["recipient1", "recipient2"],
    "properties": {"role":"manager"}
  }

  const response = await supr_client.objects.create_subscriptions(object_type, object_id, payload);
  ```
</CodeGroup>

## List subscriptions

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.get_subscriptions(object_type, object_id,{"limit":10})
  ```
</CodeGroup>

## Remove object subscription

<CodeGroup>
  ```javascript Request theme={"system"}
  const payload = {"recipients": ["recipient1", "recipient2"]}

  const response = await supr_client.objects.delete_subscriptions(object_type, object_id, payload)
  ```
</CodeGroup>

## Get list of objects subscribed by object

An object can subscribe to other objects. Use this method to get the list of all objects that the current object has subscribed to.

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.get_objects_subscribed_to(object_type, object_id);
  ```
</CodeGroup>

## Delete object

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.delete(object_type, object_id);
  ```
</CodeGroup>

### Bulk Delete object

<CodeGroup>
  ```javascript Request theme={"system"}
  const response = await supr_client.objects.bulk_delete(object_type, {object_ids: ["object_id1", "object_id2"]});
  ```
</CodeGroup>