Push Notification API

Created: - Updated:

Send Notification API

Allows users to send push notifications to respondents via API.

Please note: Use this wisely as respondents may turn off the app notifications if they receive frequent notifications.

Request information

method="POST"

must be done over https

POST URL format: https://<branded_instance>/reactor-webapp/pt/<project_name>/pn/lumicompass/api/send_notifications

Parameters

Name

Value

Description

Required

user_name

String

A valid backend user's credentials

Yes

password

String

A valid backend user's credentials

Yes

respondents_json

String

A JSON String containing the participant data. See below.

No*

JSON Format

{"company_id":"","survey_id":"","group_id":"","message":"","respondents":[
    {"username":"r1"},
    {"username":"r2"},
    ...
]}

 

Parameter

Value

Description

Required

company_id

Integer

The id of the company the respondents belong to.

No, but the API call will fail if the user has access to more than one company if this variables isn't specified

survey_id

Integer

If specified the API will send a notification to all respondents belonging to this survey.

No*

group_id

Integer

If specified the API will send a notification to all respondents belonging to this group.

No*

message

String

The custom message to send to the respondents

No, if not specified the default "A new survey has been added for you" notification will be sent (translated according to the respondents language)

respondents

Json Array

Container for the respondent data

Yes

username

String

Respondent id/username

Yes

*) One of these parameters have to be specified. If more than one is specified, the system will prioritise in the following order: "respondents_json", "group_id", "survey_id"

 

Responses

HTTP error responses that are implemented

Response

Message

Reason

HTTP 400

Action not supported

Not a POST request

HTTP 403

Not supported

Not using HTTPS

JSON responses are given if the request passes the initial validation (i.e. if the HTTP errors do not apply)

Format: {"message":"","status":""}

Where message will contain a descriptive message string, and status is either "ok" if the upload succeeded or "error" if it failed.

 

Status

Message

Reason

ok

API sent notifications to <number_of_respondents> respondents

Success message.

error

Error missing required parameter.

One of user_name/password is missing.

error

Authentication failure.

Failed to authenticate with given credentials.

error

Could not parse json parameter as a JSONObject.

Parse error when parsing the respondents_json - not valid Json string

error

Could not validate respondents. Could not fetch respondent list.

Error when fetching respondents from storage.

error

Could not validate respondents. Respondent(s) does not exist! (...)

Failed because listed respondents were not found in storage.

error

No respondents found in group <group_id> please check the group id.

Failed because no respondents found in specified group id, possibly group does not exist.

error

No respondents assigned to survey <survey_id>, please check the survey id.

Failed because no respondents found in specified survey_id, possibly survey id does not exist.

error

No survey id, group id or respondents specified!

Missing parameter survey_id, group_id or respondents_json.

error

PushNotification API Could not sent standard notification to respondents

Storage exception on server.

error

PushNotification API Could not sent customer "message" notification to respondents

Storage exception on server.