Skip to main content
API docs by Redocly

Engagespot API (3.0.0)

Our REST API allows you to send notifications to users on your app, and to do actions like Fetch Notifications, Delete Notification etc on behalf of them.

Base URL

Base URL of this API is https://api.engagespot.co/v3/

Authentication

This API should be authenticated in two ways.

Authenticate using API-KEY and API-SECRET

This mode is required when you want to authenticate as your Engagespot app and send a notification to one or more recipients. The credentials can be found in your Engagespot dashboard.

Authenticate using API-KEY and USER-ID

This mode should be used when you want to authenticate as your user and want to perform actions on behalf of them. For example, reading the notification inbox of a user, deleting a notification from a user's inbox etc.

These authentication parameters should be passed via headers.

Header Parameter Description
X-ENGAGESPOT-API-KEY Your Engagespot API Key. You can see this on your Engagespot dashboard.
X-ENGAGESPOT-API-SECRET Your Engagespot API Secret. You can see this on your Engagespot dashboard.
You should never use this secret on any front-end apps.
X-ENGAGESPOT-USER-ID Your user's unique identifier such as their email id that you used to register them on Engagespot.
X-ENGAGESPOT-USER-SIGNATURE This is optional. You need this param only if you have turned on HMAC Authentication for your app in Engagespot Dashboard.

Your user's HMAC signature can be generated in your server as follows -
createHmac('sha256', Your_API_Secret).update(user_Id, 'utf8').digest('base64');

Notifications

End points to manage notifications in your app.

/notifications

Sends a new notification to one or more recipients.

Who is a Recipient?

A recipient is any User identified in your Engagespot app. You should specify the unique ids of the users whom you want send notifications to them. To learn more about creating your app users in Engagespot, read User

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx

Your Engagespot app's api key which can be found in your dashboard.

X-ENGAGESPOT-API-SECRET
required
string
Example: 7rd9fahc6f5tam9ccdrig3h7j15b6cd0jc79708d4814j7ia

Your Engagespot app's api secret which can be found in your dashboard.

Request Body schema: application/json
required
object
recipients
required
Array of strings

Unique id's of your users to send this notification to. Read Who is a User?

category
string

Category identifier to tag this notification. If category specified doesn't exist, it will be created. For templated notifications, no need to use this field because category can be specified when you create the template using Engagespot dashboard.

data
object

Add any key value pair or meta data to be passed along with this notification. This will also be used to replace the placeholders (if you're using templates)

object

Override delivery preferences configured in your account.

Responses

Request samples

Content type
application/json
{
  • "notification": {
    },
  • "recipients": [
    ],
  • "data": {
    },
  • "override": {
    }
}

/notifications

This API returns list of notifications for the given user.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

string

Responses

Response samples

Content type
application/json
{
  • "unreadCount": 0,
  • "pagination": {
    },
  • "data": [
    ]
}

/notifications/:notificationId

Gets the details of a notification. This will also mark the notification as seen

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/markAllNotificationsAsSeen Deprecated

Marks the first 15 unseen notifications as seen for the given user.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/notifications/:id/click

Marks a notification as clicked.

path Parameters
id
required
integer
Example: 428152

Notification ID

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/notifications/:id/views

Marks a notification as Unseen.

path Parameters
id
required
integer
Example: 428152

Notification ID

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/notifications/:id/reads

Marks a notification as Unread.

path Parameters
id
required
integer
Example: 428152

Notification ID

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/notifications/:id

Deletes a notification

path Parameters
id
required
integer
Example: 428152

id of notification to be deleted.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: shiynklpz18l3ktqyy6d9a
X-ENGAGESPOT-USER-ID
required
string
Example: yourUser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

Profile

/profile

Sets one or more key value pairs to User's profile. This method expects array of JSON Patch rules as mentioned in JSON Patch syntax to do complex operations the existing user object.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: jYt501jhd736hcbcGt34D6HyCxdFrEhkskpurgs36bbK6Xxzl1Lp

Required If HMAC Authentication is Turned On for your app.

Request Body schema: application/json
Array
object

JSON Patch Operation as mentioned in JSON Patch

Responses

Request samples

Content type
application/json
[
  • {
    }
]

/profile

Sets one or more key value pairs to User's profile. Simply pass the JSON profile object of the user, and we'll update the existing profile.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: jYt501jhd736hcbcGt34D6HyCxdFrEhkskpurgs36bbK6Xxzl1Lp

Required If HMAC Authentication is Turned On for your app.

Request Body schema: application/json
object

Key value pairs for the user's profile

Responses

Request samples

Content type
application/json
{
  • "name": "Jack",
  • "email": "jack@titanic.com"
}

/profile

Gets a user's profile.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

Preferences

/preferences

Gets a user's profile.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

/preferences

Set notification delivery preference on notification categories and channels.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER_SIGNATURE

Required If HMAC Authentication is Turned On

Request Body schema: application/json
required
Array of objects
Array
categoryId
required
number

Category Id. (You'll get this from GET categories API)

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "preference": [
    ]
}

Category

Lists all categories in this app.

/categories

Lists all categories in the app.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/categories

Create a new category.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-SECRET-KEY
required
string
Example: Ht410rCJ09Hy8Uyzwpsm6s4jjqmlx
Request Body schema: application/json
identifier
required
string

A unique identifier for the new category (Example - comment_replies)

name
required
string

A name for the new category (Example - Comment Replies). This will be shown to your users.

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "identifier": "string"
}

/categories/:id

Deletes a category.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-SECRET-KEY
required
string
Example: Ht410rCJ09Hy8Uyzwpsm6s4jjqmlx

Responses

SDK

/sdk/connect

API to authenticate your app user with Engagespot. This API is called from every front-end SDK's initialization step. If you're using a front-end platform that do not have a native SDK support from Engagespot, you can simply use this API.

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-USER-ID
required
string
Example: youruser@example.com
X-ENGAGESPOT-DEVICE-ID
required
string
Example: Any value

Any unique id to identify your user's device / app installation.

X-ENGAGESPOT-USER-SIGNATURE
string
Example: USER-SIGNATURE

Required If HMAC Authentication is Turned On

Request Body schema: application/json
deviceType
required
string

Should be any value from - "browser", "android", "ios"

Responses

Request samples

Content type
application/json
{
  • "deviceType": "string"
}

Response samples

Content type
application/json
{
  • "unreadCount": 0,
  • "app": {
    }
}

Users

/users

API to create a new user

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-API-SECRET
required
string
Example: Xt41rizwprizwpqmlxkriZwpk7huInx
Request Body schema: application/json
identifier
required
string

Any identifier to uniquely identify your user.

profile
object

Any key value pair that will be attached to the user's profile

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "profile": { }
}

/users/:identifier

Create or update a User with profile data

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-API-SECRET
required
string
Example: Xt41rizwprizwpqmlxkriZwpk7huInx
Request Body schema: application/json
object

Any key value pair to be attached to this user's profile

Responses

Request samples

Content type
application/json
{ }

/users/:identifier

Deletes a user from app

header Parameters
X-ENGAGESPOT-API-KEY
required
string
Example: at410rizwpsm6s4jjqmlx
X-ENGAGESPOT-API-SECRET
required
string
Example: Xt41rizwprizwpqmlxkriZwpk7huInx

Responses