Notifications

Not to be confused with messages, notifications inform an end user of an event. Only certain types of notifications can be manually generated by applications built on the Spark platform.

This service requires an OAuth 2 key.

  1. Supported Roles
  2. Available Services
    1. Notifications
    2. Specified Notifications
    3. Unread Notifications
  3. Notifications Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads? Writes?
IDX No No
VOW No No
Private Yes Yes
More information about roles may be found here.

Available Services

Notifications

URI: /<API Version>/notifications

HTTP Method Description Notes
GET Returns the notifications sent to the current user
POST Creates a notification with the active user as the recipient. SenderApplication will automatically be set to your application's name.
PUT Returns HTTP 405 (Method Not Allowed) Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:
Parameter Required
Pagination No

GET Response

{
  "D": {
    "Results": [{
      "Id":                "20100000000000000000000000",
      "Type":              "OperationComplete",
      "SenderApplication": "My Application",
      "SenderId":          "20100000000000000000000001",
      "RecipientId":       "20100000000000000000000002",
      "Message":           "Your PDF generation has completed!",
      "BrowserUri":        "http://myapplication.com/cmas/19581825.pdf",
      "ResourceUri":       "http://myapplication.com/cmas/19581825.json",
      "Read":              false,
      "CreatedTimestamp":  2011-11-18T16:35:43,
      "ReadTimestamp":     null
    }],
    "Success": true
  }
}

POST Request

Request body: 
{
    "D": {
      "Type":              "OperationComplete",
      "Message":           "Your PDF generation has completed!",
      "BrowserUri":        "http://myapplication.com/cmas/19581825.pdf",
      "ResourceUri":       "http://myapplication.com/cmas/19581825.json"
    }
}

POST Response

The standard success/fail response is returned.

Specified Notifications

URI: /<API Version>/notifications/<Id>[,<Id>...]

HTTP Method Description Notes
GET Returns HTTP 405 (Method Not Allowed) Not implemented
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Marks one or more specified notifications as read
DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

PUT Request

Request body: 
{
    "D": {
        "Read": true
    }
}

PUT Response

The standard success/fail response is returned.

Unread Notifications

URI: /<API Version>/notifications/unread

HTTP Method Description Notes
GET Returns pagination information, including the overall count, for unread notifications.
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Returns HTTP 405 (Method Not Allowed) Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:
  • None

GET Response

See the GET request section for for the pagination block.

Notification Description

Attribute Data Type Writeable? Required? Description
Id Character No No The unique id for the notification.
Type Character Yes Yes The type of notification. See the table below for the various types.
SenderApplication Character No No Set if the notification was directly created by a third party application. This is set automatically.
SenderId Character No No Present if a notification was triggered directly by the action of an end-user, such as when one user sends a Message to another.
ResourceUri Character Yes No An optional Uri to the resource corresponding to the event that triggered the notification. Intended for non-browser software consumption.
BrowserUri Character Yes No An optional Uri to the resource corresponding to the event that triggered the notification. Intended for browser consumption.
Message Character Yes Yes A brief description of the event. 140 characters max. Usually omitted for system generated notifications, but required for third-party notifications.
Read Boolean Yes No
ReadTimestamp Timestamp No No The time when the notification was flagged as Read.
CreatedTimestamp Timestamp No No The time when the notification was generated.

Below are the existing notification types. Note that Manual notification types can be created by applications built on the API; all other types are generated automatically, and can only be retrieved and flagged as Read.

Type Manual? Generation Event Description
General Yes n/a Any notification that doesn't fall under an existing notification type.
OperationComplete Yes n/a Informs a user that a background task has been completed.
Message No Message creation. Informs a user that they have received a new message.

Expansions

None.

API Explorer

The API Explorer does not currently support this service.