OBJECTS
Add Subscription
API to add subscribers (users/child objects) to a given object, to notify subscribers when workflow is triggered on the parent object.
POST
/
v1
/
object
/
{object_type}
/
{id}
/
subscription
/
cURL
curl -X POST "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/" \
--header 'Authorization: Bearer __YOUR_API_KEY__' \
--header 'Content-Type: application/json' \
--data '{
"recipients": ["user123","user456"],
"properties": {
"role": "developer"
}
}'import requests
url = "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/"
payload = {
"recipients": [
{
"distinct_id": "id1",
"$email": ["<string>"],
"$sms": ["<string>"],
"$whatsapp": ["<string>"],
"$inbox": ["<string>"],
"$androidpush": ["<string>"],
"$iospush": ["<string>"],
"$slack": [
{
"email": "user@example.com",
"access_token": "xoxb-XXXXXXXX"
}
],
"$ms_teams": [
{
"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
"service_url": "https://smba.trafficmanager.net/amer",
"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
}
],
"$locale": "en_GB",
"$timezone": "<string>"
}
],
"properties": { "role": "developer" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
distinct_id: 'id1',
$email: ['<string>'],
$sms: ['<string>'],
$whatsapp: ['<string>'],
$inbox: ['<string>'],
$androidpush: ['<string>'],
$iospush: ['<string>'],
$slack: [{email: 'user@example.com', access_token: 'xoxb-XXXXXXXX'}],
$ms_teams: [
{
tenant_id: 'c1981ab2-9aaf-xxxx-xxxx',
service_url: 'https://smba.trafficmanager.net/amer',
conversation_id: '19:c1524d7c-a06f-456f-8abe-xxxx'
}
],
$locale: 'en_GB',
$timezone: '<string>'
}
],
properties: {role: 'developer'}
})
};
fetch('https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'recipients' => [
[
'distinct_id' => 'id1',
'$email' => [
'<string>'
],
'$sms' => [
'<string>'
],
'$whatsapp' => [
'<string>'
],
'$inbox' => [
'<string>'
],
'$androidpush' => [
'<string>'
],
'$iospush' => [
'<string>'
],
'$slack' => [
[
'email' => 'user@example.com',
'access_token' => 'xoxb-XXXXXXXX'
]
],
'$ms_teams' => [
[
'tenant_id' => 'c1981ab2-9aaf-xxxx-xxxx',
'service_url' => 'https://smba.trafficmanager.net/amer',
'conversation_id' => '19:c1524d7c-a06f-456f-8abe-xxxx'
]
],
'$locale' => 'en_GB',
'$timezone' => '<string>'
]
],
'properties' => [
'role' => 'developer'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/"
payload := strings.NewReader("{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"properties": {
"department": "frontend"
},
"user": {
"distinct_id": "_distinct_id_",
"updated_at": "2025-04-05T10:33:33.629736+00:00"
},
"object": {
"id": "_object_id_",
"object_type": "_object_type_",
"subscriptions_count": 10,
"updated_at": "2025-04-06T11:00:24.257046+00:00"
},
"created_at": "2025-04-06T10:59:07.726336+00:00",
"updated_at": "2025-04-06T10:59:07.726336+00:00"
}
]
}{
"code": 404,
"message": "object 'object_type/id' not found"
}Authorizations
Pass as Bearer <API_KEY>. Get API Key from SuprSend dashboard Developers -> API Keys section.
Path Parameters
Unique identifier of the object in your system
Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
Body
application/json
List of recipients to be notified. You can either add recipient as array of distinct_ids or array of recipient objects. You can add up to 100 recipients in a single API.
Option 1: Add user subscription - Add user subscription by passing user json. You can pass user distinct_ids in array as ["id1","id2"] or as user object to identify recipient inline.
- Add user
- Add child object
Show child attributes
Show child attributes
properties defining the relation between object and its subscribers. Can be referenced as recipient.subscription.<key> in workflow and template.
Example:
{ "role": "developer" }
Response
200
Show child attributes
Show child attributes
Show child attributes
Show child attributes
object subscription properties, referred as $recipient.subscription.<key> in template or workflow.
Timestamp when the subscription was created.
Example:
"2025-04-04T09:55:12.397Z"
Timestamp when the subscription was last updated.
Example:
"2025-04-04T09:55:12.422Z"
Was this page helpful?
⌘I
cURL
curl -X POST "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/" \
--header 'Authorization: Bearer __YOUR_API_KEY__' \
--header 'Content-Type: application/json' \
--data '{
"recipients": ["user123","user456"],
"properties": {
"role": "developer"
}
}'import requests
url = "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/"
payload = {
"recipients": [
{
"distinct_id": "id1",
"$email": ["<string>"],
"$sms": ["<string>"],
"$whatsapp": ["<string>"],
"$inbox": ["<string>"],
"$androidpush": ["<string>"],
"$iospush": ["<string>"],
"$slack": [
{
"email": "user@example.com",
"access_token": "xoxb-XXXXXXXX"
}
],
"$ms_teams": [
{
"tenant_id": "c1981ab2-9aaf-xxxx-xxxx",
"service_url": "https://smba.trafficmanager.net/amer",
"conversation_id": "19:c1524d7c-a06f-456f-8abe-xxxx"
}
],
"$locale": "en_GB",
"$timezone": "<string>"
}
],
"properties": { "role": "developer" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
distinct_id: 'id1',
$email: ['<string>'],
$sms: ['<string>'],
$whatsapp: ['<string>'],
$inbox: ['<string>'],
$androidpush: ['<string>'],
$iospush: ['<string>'],
$slack: [{email: 'user@example.com', access_token: 'xoxb-XXXXXXXX'}],
$ms_teams: [
{
tenant_id: 'c1981ab2-9aaf-xxxx-xxxx',
service_url: 'https://smba.trafficmanager.net/amer',
conversation_id: '19:c1524d7c-a06f-456f-8abe-xxxx'
}
],
$locale: 'en_GB',
$timezone: '<string>'
}
],
properties: {role: 'developer'}
})
};
fetch('https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'recipients' => [
[
'distinct_id' => 'id1',
'$email' => [
'<string>'
],
'$sms' => [
'<string>'
],
'$whatsapp' => [
'<string>'
],
'$inbox' => [
'<string>'
],
'$androidpush' => [
'<string>'
],
'$iospush' => [
'<string>'
],
'$slack' => [
[
'email' => 'user@example.com',
'access_token' => 'xoxb-XXXXXXXX'
]
],
'$ms_teams' => [
[
'tenant_id' => 'c1981ab2-9aaf-xxxx-xxxx',
'service_url' => 'https://smba.trafficmanager.net/amer',
'conversation_id' => '19:c1524d7c-a06f-456f-8abe-xxxx'
]
],
'$locale' => 'en_GB',
'$timezone' => '<string>'
]
],
'properties' => [
'role' => 'developer'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/"
payload := strings.NewReader("{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"recipients\": [\n {\n \"distinct_id\": \"id1\",\n \"$email\": [\n \"<string>\"\n ],\n \"$sms\": [\n \"<string>\"\n ],\n \"$whatsapp\": [\n \"<string>\"\n ],\n \"$inbox\": [\n \"<string>\"\n ],\n \"$androidpush\": [\n \"<string>\"\n ],\n \"$iospush\": [\n \"<string>\"\n ],\n \"$slack\": [\n {\n \"email\": \"user@example.com\",\n \"access_token\": \"xoxb-XXXXXXXX\"\n }\n ],\n \"$ms_teams\": [\n {\n \"tenant_id\": \"c1981ab2-9aaf-xxxx-xxxx\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\",\n \"conversation_id\": \"19:c1524d7c-a06f-456f-8abe-xxxx\"\n }\n ],\n \"$locale\": \"en_GB\",\n \"$timezone\": \"<string>\"\n }\n ],\n \"properties\": {\n \"role\": \"developer\"\n }\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"properties": {
"department": "frontend"
},
"user": {
"distinct_id": "_distinct_id_",
"updated_at": "2025-04-05T10:33:33.629736+00:00"
},
"object": {
"id": "_object_id_",
"object_type": "_object_type_",
"subscriptions_count": 10,
"updated_at": "2025-04-06T11:00:24.257046+00:00"
},
"created_at": "2025-04-06T10:59:07.726336+00:00",
"updated_at": "2025-04-06T10:59:07.726336+00:00"
}
]
}{
"code": 404,
"message": "object 'object_type/id' not found"
}