SuprSend Object API
The Object API from SuprSend — 8 operation(s) for object.
OpenAPI Specification
openapi: 3.1.1
info:
title: SuprSend Broadcast Object API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Object
paths:
/v1/object/{object_type}/{id}/:
post:
summary: Create / Update Objects
security:
- BearerAuth: []
description: API to upsert (create if not exists, update if exists) object by providing a unique object ID and type.
operationId: create-update-objects
parameters:
- name: id
in: path
description: Unique identifier of the object in your system
schema:
type: string
required: true
- name: object_type
in: path
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
schema:
type: string
required: true
requestBody:
content:
application/json:
example:
department: Engineering
$email:
- devs@example.com
$slack:
- channel: CXXXXXXXX
access_token: xoxb-XXXXXX
schema:
properties:
$email:
type: array
items:
type: string
format: email
description: List of email addresses.
$sms:
type: array
items:
type: string
description: List of phone numbers for SMS
$whatsapp:
type: array
items:
type: string
description: List of phone numbers for WhatsApp
$inbox:
type: array
items:
type: string
description: List of inbox identifiers
$androidpush:
type: array
items:
type: string
description: List of Android Push tokens
$iospush:
type: array
items:
type: string
description: List of iOS Push tokens
$slack:
type: array
description: Slack channel configuration
items:
oneOf:
- type: object
title: Slack using email
required:
- email
- access_token
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: Slack using member ID
required:
- user_id
- access_token
properties:
user_id:
type: string
description: Slack user ID (U/WXXXXXXXX format)
example: U/WXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using channel
required:
- channel
- access_token
properties:
channel:
type: string
description: Slack channel ID (CXXXXXXXX format)
example: CXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Slack incoming webhook URL
example: https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX
$ms_teams:
type: array
description: Microsoft Teams channel configuration
items:
oneOf:
- type: object
title: MS Teams using conversation ID
required:
- tenant_id
- service_url
- conversation_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
conversation_id:
type: string
description: Microsoft Teams conversation ID
example: 19:c1524d7c-a06f-456f-8abe-xxxx
- type: object
title: MS Teams using user ID
required:
- tenant_id
- service_url
- user_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type: string
format: uri
description: Microsoft Teams service URL
example: https://smba.trafficmanager.net/amer
user_id:
type: string
description: Microsoft Teams user ID
example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx
- type: object
title: MS Teams using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Microsoft Teams incoming webhook URL
example: https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX
$timezone:
type: string
description: Object's timezone in [IANA format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)
example: America/New_York
$locale:
type: string
description: Object's locale for [translating](https://suprsend.com/docs/translations) template content in SuprSend.
example: en_GB
responses:
'201':
description: 201 - Created
content:
application/json:
examples:
Result:
value:
object_type: departments
id: engineering
subscriptions_count: 0
properties:
$locale: en_GB
department: Engineering
created_at: '2025-04-06T10:00:37.893892+00:00'
updated_at: '2025-04-06T10:00:37.893892+00:00'
$email:
- value: devs@example.com
status: active
perma_status: active
$slack:
- value:
email_id: user@example.com
access_token: xoxb-...
status: active
perma_status: active
$inbox:
- value: pO7w6x_HFZxCs30N4SHab05e3QIdB1e0xT2r4vQWjvM
id_provider: suprsend
status: active
perma_status: active
schema:
type: object
properties:
id:
type: string
description: unique identifier of the object
example: engineering
object_type:
type: string
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
example: departments
subscriptions_count:
type: integer
description: number of users/child objects subscribed to the object
example: departments
properties:
type: object
description: all user properties in key-value pair. SuprSend reserved properties start with $
created_at:
type: string
format: date-time
description: Timestamp when the object was created.
example: 2025-04-04 09:55:12.397856+00:00
updated_at:
type: string
format: date-time
description: Timestamp when the object was last updated.
example: 2025-04-04 09:55:12.422388+00:00
$<channel>:
type: array
description: List of active communication channels for the object.
items:
type: object
properties:
value:
type: string
description: channel value
status:
type: string
description: Current status of the channel (active or inactive).
example: active
perma_status:
type: string
description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel.
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
code: 400
message: invalid_request_error
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
description: Error message describing the missing resource.
deprecated: false
tags:
- Object
get:
summary: Fetch Object by id
security:
- BearerAuth: []
description: API to fetch Object details by passing object type and ID.
operationId: get-object-by-id
parameters:
- name: id
in: path
description: Unique identifier of the object in your system
schema:
type: string
required: true
- name: object_type
in: path
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
schema:
type: string
required: true
responses:
'200':
description: 200 - OK
content:
application/json:
examples:
Result:
value:
object_type: departments
id: engineering
subscriptions_count: 0
properties:
$locale: en_GB
created_at: '2025-04-06T10:00:37.893892+00:00'
updated_at: '2025-04-06T10:00:37.893892+00:00'
$inbox:
- value: pO7w6x_HFZxCs30N4SHab05e3QIdB1e0xT2r4vQWjvM
id_provider: suprsend
status: active
perma_status: active
schema:
type: object
properties:
id:
type: string
description: unique identifier of the object
example: engineering
object_type:
type: string
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
example: departments
subscriptions_count:
type: integer
description: number of users/child objects subscribed to the object
example: departments
properties:
type: object
description: all user properties in key-value pair. SuprSend reserved properties start with $
created_at:
type: string
format: date-time
description: Timestamp when the object was created.
example: 2025-04-04 09:55:12.397856+00:00
updated_at:
type: string
format: date-time
description: Timestamp when the object was last updated.
example: 2025-04-04 09:55:12.422388+00:00
$<channel>:
type: array
description: List of active communication channels for the object.
items:
type: object
properties:
value:
type: string
description: channel value
status:
type: string
description: Current status of the channel (active or inactive).
example: active
perma_status:
type: string
description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel.
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: object 'obj_type/obj_id' not found
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
description: Error message describing the missing resource.
deprecated: false
tags:
- Object
delete:
summary: Delete an Object
security:
- BearerAuth: []
description: API to permanently delete an object by passing `object_type` and `id`.
operationId: delete-object
parameters:
- name: id
in: path
description: Unique identifier of the object in your system
schema:
type: string
required: true
- name: object_type
in: path
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
schema:
type: string
required: true
responses:
'204':
description: 204 - No Content
content:
application/json:
examples:
Result:
value: null
'404':
description: 404 - Not Found
content:
application/json:
examples:
Result:
value:
code: 404
message: object 'object_type/object_id' not found
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
description: Error message indicating object_id and type combination is not found
deprecated: false
tags:
- Object
patch:
summary: Edit Object Profile
security:
- BearerAuth: []
description: API to edit (add/remove) properties and communication-channels for an object.
operationId: edit-object-profile
x-codeSamples:
- lang: cURL
source: "curl -X PATCH \"https://hub.suprsend.com/v1/object/{object_type}/{id}/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"operations\": [\n {\n \"$set\": {\n \"name\": \"Engineering Department\",\n \"$locale\": \"en_GB\",\n \"$timezone\": \"America/New_York\"\n }\n },\n {\n \"$append\": {\n \"$email\": [\"team@example.com\"]\n }\n }\n ]\n }'\n"
parameters:
- name: object_type
in: path
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
required: true
schema:
type: string
- name: id
in: path
description: Unique identifier of the object in your system
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
operations:
type: array
description: 'You can use the following operations to edit user profile.
- `$set` to add/update a property
- `$unset` to delete property/channel
- `$append` to insert values in property/channel array
- `$remove` to remove values from property/channel array
- `$set_once` to remove immutable properties
- `$increment` to increase/decrease integer values on further update
'
items:
type: object
properties:
$set:
type: object
description: 'Use this to set user properties like name, location, locale, etc.
Example: `{"team":"Engineering","$locale":"en_GB","$timezone":"America/New_York"}`
'
additionalProperties:
type: string
$unset:
type: array
description: 'Use this to delete channels or properties from user profile.
Channels: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams`
Example: `["$sms", "$whatsapp", "name"]`
'
items:
type: string
$append:
type: object
description: 'Use this to add communication channels or update array properties in user profile. Available channel keys: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams`
Example: `{"$email":"team@example.com"}`
'
additionalProperties:
type: string
$remove:
type: object
description: 'Use this to remove communication channels or remove values from an array in user profile. Available channel keys: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams`
Example: `{"$email":"team@example.com"}`
'
additionalProperties:
type: string
$set_once:
type: object
description: 'Use this to set properties which are not set once and not changed on further updates.
Example: `{"first_login_at":"2025-01-01T14:00:00Z"}`
'
additionalProperties:
type: string
$increment:
type: object
description: 'Use this to increase / decrease integer values on further updates
Example: `{"login_count":1}`
'
additionalProperties:
type: string
responses:
'200':
description: 200 - OK
content:
application/json:
examples:
Result:
value:
object_type: departments
id: engineering
subscriptions_count: 0
properties:
$locale: en_GB
created_at: '2025-04-06T10:00:37.893892+00:00'
updated_at: '2025-04-06T10:00:37.893892+00:00'
$inbox:
- value: pO7w6x_HFZxCs30N4SHab05e3QIdB1e0xT2r4vQWjvM
id_provider: suprsend
status: active
perma_status: active
schema:
type: object
properties:
id:
type: string
description: unique identifier of the object
example: engineering
object_type:
type: string
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
example: departments
subscriptions_count:
type: integer
description: number of users/child objects subscribed to the object
example: departments
properties:
type: object
description: all user properties in key-value pair. SuprSend reserved properties start with $
created_at:
type: string
format: date-time
description: Timestamp when the object was created.
example: 2025-04-04 09:55:12.397856+00:00
updated_at:
type: string
format: date-time
description: Timestamp when the object was last updated.
example: 2025-04-04 09:55:12.422388+00:00
$<channel>:
type: array
description: List of active communication channels for the object.
items:
type: object
properties:
value:
type: string
description: channel value
status:
type: string
description: Current status of the channel (active or inactive).
example: active
perma_status:
type: string
description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel.
'400':
description: 400 - Bad Request
content:
application/json:
examples:
Result:
value:
code: 400
message: Request body must not be empty
deprecated: false
tags:
- Object
/v1/object/{object_type}/{id}/subscription/:
post:
summary: Add Subscription
security:
- BearerAuth: []
description: API to add subscribers (users/child objects) to a given object, to notify subscribers when workflow is triggered on the parent object.
operationId: add-object-subscription
x-codeSamples:
- lang: cURL
source: "curl -X POST \"https://hub.suprsend.com/v1/object/{object_type}/{id}/subscription/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"recipients\": [\"user123\",\"user456\"],\n \"properties\": {\n \"role\": \"developer\"\n }\n }'\n"
parameters:
- name: id
in: path
description: Unique identifier of the object in your system
schema:
type: string
required: true
- name: object_type
in: path
description: Used to group similar objects together. Give plural namespace like teams, organizations, and roles.
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
recipients:
type: array
description: 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.
items:
oneOf:
- type: object
title: Add user
description: '**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.'
required:
- distinct_id
properties:
distinct_id:
type: string
description: unique identifier of the user
default: id1
$email:
type: array
description: List of email addresses.
items:
type: string
$sms:
type: array
description: List of SMS numbers.
items:
type: string
$whatsapp:
type: array
description: List of WhatsApp numbers.
items:
type: string
$inbox:
type: array
description: List of Inbox numbers.
items:
type: string
$androidpush:
type: array
description: List of Android Push tokens.
items:
type: string
$iospush:
type: array
description: List of iOS Push tokens.
items:
type: string
$slack:
type: array
description: Slack channel configuration
items:
oneOf:
- type: object
title: Slack using email
required:
- email
- access_token
properties:
email:
type: string
format: email
description: User email address
example: user@example.com
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXXXX
- type: object
title: Slack using member ID
required:
- user_id
- access_token
properties:
user_id:
type: string
description: Slack user ID (U/WXXXXXXXX format)
example: U/WXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using channel
required:
- channel
- access_token
properties:
channel:
type: string
description: Slack channel ID (CXXXXXXXX format)
example: CXXXXXXXX
access_token:
type: string
description: Slack bot access token
example: xoxb-XXXXXX
- type: object
title: Slack using incoming webhook
required:
- incoming_webhook
properties:
incoming_webhook:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Slack incoming webhook URL
example: https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX
$ms_teams:
type: array
description: Microsoft Teams channel configuration
items:
oneOf:
- type: object
title: MS Teams using conversation ID
required:
- tenant_id
- service_url
- conversation_id
properties:
tenant_id:
type: string
description: Microsoft Teams tenant ID
example: c1981ab2-9aaf-xxxx-xxxx
service_url:
type:
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/suprsend/refs/heads/main/openapi/suprsend-object-api-openapi.yml