> ## 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 with Java 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>
  ```java Request theme={"system"}
  import org.json.JSONObject;
  import suprsend.Suprsend;

  public class ObjectEdit {
    public static void main(String[] args) throws Exception {
      objectEditInstance();
    }

    public static void getSuprClient() throws Exception {
      Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
      return suprsendClient;
    }

    public static void objectEditInstance() throws Exception {
      Suprsend suprsendClient = getSuprClient();
      // Instiantiate object
      String objectType = "departments";
      String objectId = "engineering";

      // Object Payload to upsert properties and communication channels
      JSONObject payload = new JSONObject()
        .put("k1", "value1");
        .put("$email", "devs@abc.com");

      JSONObject object = suprClient.objects.upsert(objectType, objectId, payload);
      System.out.println(object);
    }
  }
  ```

  ```java Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "k1": "value1"
        },
     "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":"devs@abc.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 [Object Edit](https://docs.suprsend.com/reference/edit-object-profile) API.

<CodeGroup>
  ```java Request theme={"system"}
  import org.json.JSONObject;
  import suprsend.Suprsend;


  public class ObjectEdit {

    public static void objectEditInstance() throws Exception {
      Suprsend suprsendClient = getSuprClient();

      // Instiantiate object
      String objectType = "departments";
      String objectId = "engineering";

      // Object Payload
      JSONObject payload = new JSONObject().put("operations",
  				new JSONObject[] { new JSONObject().put("$set", new JSONObject().put("k2", "value2")) });

  		JSONObject object = suprClient.objects.edit(objectType, objectId, payload);
  		System.out.println(object);
    }
  }
  ```

  ```java Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "k1": "value1",
        "k2": "value2"
     },
     "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>
  ```java Request theme={"system"}
  import org.json.JSONObject;
  import suprsend.Suprsend;
  import suprsend.ObjectEdit;

  public class ObjectEdit {

    public static void objectEditInstance() throws Exception {
      Suprsend suprsendClient = getSuprClient();

      //Fetch Object Instance
      String objectType = "departments";
      String objectId = "engineering";
      ObjectEdit object_ins = suprClient.objects.getInstance(objectType, objectId);

      // Call object update methods
      object_ins.set("company_name", "ABC company");
      object_ins.setTimezone("America/Los_Angeles");

      // Call edit api
      JSONObject res = suprClient.objects.edit(object_ins);
      System.out.println(res);
    }
  }
  ```

  ```java Response theme={"system"}
  {
     "object_type":"departments",
     "id":"engineering",
     "subscriptions_count":0,
     "properties":{
        "$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>

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

  <CodeGroup>
    ```java Request theme={"system"}
    // Add Email
    object_ins.addEmail("example@example.com");

    //Add SMS
    object_ins.addSms("+919999999999");

    //Add Whatsapp
    object_ins.addWhatsapp("+919999999999");

    // Add Androidpush token.Pass the vendor as 2nd param.
    object_ins.addAndroidpush("androidpush_fcm_token__","fcm");

    // Add iospush token
    object_ins.addIospush("__iospush_apns_token__");

    // Add Slack using user email id
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("email", "user@example.com");
    object_ins.addSlack(slackIdent);

    // Add Slack using member_id of the user if known
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("user_id", "U03XXXXXXXX");
    object_ins.addSlack(slackIdent);

    // Add Slack channel_id
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("channel_id", "C04XXXXXXXX");
    object_ins.addSlack(slackIdent);

    // Add Slack incoming webhook
    JSONObject slackIdent = new JSONObject()
      .put("incoming_webhook", new JSONObject().put("url", "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"))
    object_ins.addSlack(slackIdent);

    // Add Webpush token json (VAPID)
    JSONObject webpush = new JSONObject()
      .put("endpoint", "__end_point__")
      .put("expirationTime", "")
      .put("keys", new JSONObject()
           .put("p256dh", "__p256dh__")
           .put("auth", "__auth_key__"));
    object_ins.addWebpush(webpush, "vapid");
    ```
  </CodeGroup>
</Accordion>

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

  <CodeGroup>
    ```java Request theme={"system"}
    // Remove Email
    object_ins.removeEmail("example@example.com");

    //Remove SMS
    object_ins.removeSms("+919999999999");

    //Remove Whatsapp
    object_ins.removeWhatsapp("+919999999999");

    // Remove Androidpush token.Pass the vendor as 2nd param.
    object_ins.removeAndroidpush("androidpush_fcm_token__","fcm");

    // Remove iospush token
    object_ins.removeIospush("__iospush_apns_token__");

    // Remove Slack using user email id
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("email", "user@example.com");
    object_ins.removeSlack(slackIdent);

    // Remove Slack using member_id of the user if known
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("user_id", "U03XXXXXXXX");
    object_ins.removeSlack(slackIdent);

    // Remove Slack channel_id
    JSONObject slackIdent = new JSONObject()
      .put("access_token", "xoxb-XXXXXXXX")
      .put("channel_id", "C04XXXXXXXX");
    object_ins.removeSlack(slackIdent);

    // Remove Slack incoming webhook
    JSONObject slackIdent = new JSONObject()
      .put("incoming_webhook", new JSONObject().put("url", "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"))
      object_ins.removeSlack(slackIdent);

    // Remove Webpush token json (VAPID)
    JSONObject webpush = new JSONObject()
      .put("endpoint", "__end_point__")
      .put("expirationTime", "")
      .put("keys", new JSONObject()
           .put("p256dh", "__p256dh__")
           .put("auth", "__auth_key__"));
    object_ins.removeWebpush(webpush, "vapid");

    ```
  </CodeGroup>
</Accordion>

<Accordion title="Remove Channels in bulk">
  This method will delete/unset all values in specified channel for object (ex: remove all emails attached to object).

  <CodeGroup>
    ```java Request theme={"system"}
    object_ins.unset("$email");
    object_ins.unset(Arrays.asList(new String[] { "$sms", "$email" }));

    // available channel keys -
    //{"$email","$whatsapp","$sms","$androidpush","$iospush","$webpush","$slack","$ms_teams"}
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Set Preferred language">
  If you want to send notification in user's preferred language, you can set it by passing [language code](https://github.com/suprsend/suprsend-py-sdk/blob/v0.12.0/src/suprsend/language_codes.py) in this method. This is useful especially for the applications which offer vernacular or multi-lingual support.

  <CodeGroup>
    ```java Request theme={"system"}
    object_ins.setPreferredLanguage("es")
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Set Preferred Timezone">
  You can set timezone of user using this method. Value for timezone must be from amongst the [IANA timezones](https://data.iana.org/time-zones/tzdb-2024a/zonenow.tab).

  <CodeGroup>
    ```java Request theme={"system"}
    object_ins.setTimezone("America/Los_Angeles");
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Set">
  Set any custom property using this method. It will shallow merge existing properties with new values. Key shouldn't start with `$` or `ss`.

  <CodeGroup>
    ```java Request theme={"system"}
    //set single property
    object_ins.set(key, value);
    object_ins.set("company_name", "ABC company");

    //set multiple properties
    JSONObject objectsProperties = new JSONObject()
      .put("company_name", "ABC company")
      .put("city", "San Francisco")
    object_ins.set(objectsProperties);
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Unset">
  Remove any custom property key using this method.

  <CodeGroup>
    ```java Request theme={"system"}
    //unset single property
    object_ins.unset(key);
    object_ins.unset("company_name");

    //unset multiple properties
    object_ins.unset(Arrays.asList(new String[] { "$sms", "wishlist" }));
    ```
  </CodeGroup>
</Accordion>

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

  <CodeGroup>
    ```java Request theme={"system"}
    //append single property
    object_ins.append("array", "k1");

    //append multiple properties
    JSONObject objectsProperties = new JSONObject()
      .put("wishlist", "iphone12")
      .put("products", "tenancy");
    object_ins.append(objectsProperties);
    ```
  </CodeGroup>
</Accordion>

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

  <CodeGroup>
    ```java Request theme={"system"}
    //append single property
    object_ins.remove("array", "k1");

    //append multiple properties
    JSONObject objectsProperties = new JSONObject()
      .put("wishlist", "iphone12")
      .put("products", "tenancy");
    object_ins.remove(objectsProperties);
    ```
  </CodeGroup>
</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>
    ```java Request theme={"system"}
    //single property
    object_ins.setOnce("first_login", "2021-11-02");

    //multiple properties
    JSONObject objectsProperties = new JSONObject()
      .put("first_login", "2021-11-02")
      .put("DOB", "1991-10-02");
    object_ins.setOnce(objectsProperties);
    ```
  </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>
    ```java Request theme={"system"}
    //single property
    object_ins.increment("login_count", 1);

    //multiple properties
    JSONObject objectsProperties = new JSONObject()
      .put("login_count", 1)
      .put("remaining_credits", -1);
    object_ins.increment(objectsProperties);
    ```
  </CodeGroup>
</Accordion>

***

## List objects

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

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

  String objectType = "__objecttype__";

  // optional params to pass limit (default=10) and cursor pointer for fetching the next set of results
  HashMap<String, Object> opts = new HashMap<String, Object>() {
    {
      put("limit", 10);
      put("after", "01HFS04E4J29KHPYRK7HT3YQQ5");
    }
  };


  JSONObject res = suprClient.objects.list(objectType, opts);
  System.out.println(res);
  ```
</CodeGroup>

## Get object details

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

  String objectType = "__objecttype__";
  String objectId = "__objectid__";

  JSONObject res = suprClient.objects.get(objectType, objectId);
  System.out.println(res);

  ```
</CodeGroup>

## Create subscriptions

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

  String objectType = "__objecttype__";
  String objectId = "__objectid__";
  JSONObject payload = new JSONObject().put("recipients",
      Arrays.asList("__recipient_id_1__", new JSONObject().put("distinct_id", "__recipient_id_2__"),
          new JSONObject().put("object_type", objectType).put("id", objectId)));

  JSONObject res = suprClient.objects.createSubscriptions(objectType, objectId, payload);
  System.out.println(res);

  ```
</CodeGroup>

## List subscriptions

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

  String objectType = "__objecttype__";
  String objectId = "__objectid__";

  // optional params to pass limit (default=10) and cursor pointer for fetching the next set of results
  HashMap<String, Object> opts = new HashMap<String, Object>() {
    {
      put("limit", 10);
      put("after", "01HFS04E4J29KHPYRK7HT3YQQ5");
    }
  };

  JSONObject res = suprClient.objects.getSubscriptions(objectType, objectId, opts);
  System.out.println(res);
  ```
</CodeGroup>

## Remove object subscription

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

  String objectType = "__objecttype__";
  String objectId = "__objectid__";
  JSONObject payload = new JSONObject().put("recipients",
      Arrays.asList("__recipient_id_1__", new JSONObject().put("distinct_id", "__recipient_id_2__"),
          new JSONObject().put("object_type", "__objecttype__").put("id", "__objectid_child_")));

  JSONObject res = suprClient.objects.deleteSubscriptions(objectType, objectId, payload);
  System.out.println(res);

  ```
</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>
  ```java Request theme={"system"}

  String objectType = "__objecttype__";
  String objectId = "__objectid__";

  // optional params to pass limit (default=10) and cursor pointer for fetching the next set of results
  HashMap<String, Object> opts = new HashMap<String, Object>() {
    {
      put("limit", 10);
      put("after", "01HFS04E4J29KHPYRK7HT3YQQ5");
    }
  };

  JSONObject res = suprClient.objects.getObjectsSubscribedTo(objectType, objectId, opts);
  System.out.println(res);

  ```
</CodeGroup>

## Delete object

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

  String objectType = "__objecttype__";
  String objectId = "__objectid__";

  JSONObject res = suprClient.objects.delete(objectType, objectId);
  System.out.println(res);

  ```
</CodeGroup>

### Bulk delete object

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

  String objectType = "__objecttype__";
  JSONObject payload = new JSONObject().put("object_ids", Arrays.asList("__objectid__"));

  JSONObject res = suprClient.objects.bulkDelete(objectType, payload);
  System.out.println(res);

  ```
</CodeGroup>