Objects

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

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.

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);
  }
}

{
   "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"
      }
   ]
}

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

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);
  }
}

{
   "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"
      }
   ]
}

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.

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);
  }
}

{
   "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"
      }
   ]
}

Add Channels

Use object_ins.add* method(s) to add user channels in a profile

// 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");

Remove Channels

Use object_ins.remove* method(s) to remove channels from an object profile

// 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");

Remove Channels in bulk

This method will delete/unset all values in specified channel for object (ex: remove all emails attached to object).

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"}

Set Preferred language

If you want to send notification in user’s preferred language, you can set it by passing language code in this method. This is useful especially for the applications which offer vernacular or multi-lingual support.

object_ins.setPreferredLanguage("es")

Set Preferred Timezone

You can set timezone of user using this method. Value for timezone must be from amongst the IANA timezones.

object_ins.setTimezone("America/Los_Angeles");

Set

Set any custom property using this method. It will shallow merge existing properties with new values. Key shouldn’t start with $ or ss.

//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);

Unset

Remove any custom property key using this method.

//unset single property
object_ins.unset(key);
object_ins.unset("company_name");

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

Append

This method will append a value to the list for a given property.

//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);

Remove

This method will remove a value from the list for a given property.

//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);

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

//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);

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.

//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);

List objects

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

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);

Get object details

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

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

Create subscriptions

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);

List subscriptions

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);

Remove object subscription

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);

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.

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);

Delete object

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

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

Bulk delete object

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

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

Developer Resources

Updates and Versioning

Authentication

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

Upsert (create/update) an object

Edit an object

1. Build edit payload yourself

2. Edit using helper methods [Recommended]

List objects

Get object details

Create subscriptions

List subscriptions

Remove object subscription

Get list of objects subscribed by object

Delete object

Bulk delete object

​Upsert (create/update) an object

​Edit an object

​1. Build edit payload yourself

​2. Edit using helper methods [Recommended]

​List objects

​Get object details

​Create subscriptions

​List subscriptions

​Remove object subscription

​Get list of objects subscribed by object

​Delete object

​Bulk delete object

Upsert (create/update) an object

Edit an object

1. Build edit payload yourself

2. Edit using helper methods [Recommended]

List objects

Get object details

Create subscriptions

List subscriptions

Remove object subscription

Get list of objects subscribed by object

Delete object

Bulk delete object