Respondent APIs

Created: - Updated:

This article covers these topics:

Introduction to respondents APIs

Lumi Say respondent APIs can be used to automate respondent management. With the use of these APIs you can manage your respondents remotely without the need to access your Lumi Say dashboard.

Adding respondents in bulk

Please note: From 2.7 - Respondents APIs no longer require all sample fields to have a value set for each respondent in the JSON

This is a web service for adding respondents via an HTTP POST request that must be done over HTTPS (secure connection).

Essentially, the service can be used to automate adding respondents to your Lumi Say back-end from any other back-end. If you specify a callback url, an acknowledgement will be sent back. See callback response.

POSTs are directed to the Lumi Say instance server of your own project using a URL with the following format.

https://<branded_instance>.lumisay.com/reactor-webapp/pt/<project_name>/pn/lumicompass/api/add_respondent

The request should contain the following parameters

Name

Description

Value

user_name

A back-end user with the right permissions and company access

Your dashboard username

password

A correct password for the user, so we can authenticate

Your Dashboard password

respondents_json

A JSON String containing the participant data. See JSON string example below.

The to be added respondents in JSON string following the format shown in the example below

callback_url

Optional URL where the final results of the import will be POSTed once the import task is completed.

Could be your remote server url.

JSON Format

{
"no_password": "",
"group_id": "",
"overwrite": "",
"respondents": [
{
"username": "",
"phonenumber": "",
"email": "",
"sample_fields": [
{
"alias": "",
"value": ""
},
{
"alias": "",
"value": ""
}, ...
]
}, ...
]
}

JSON string parameters

Parameter name

Description

Value

Required

no_password

To allow respondents to set a password or leave it blank

true/false

Yes

group_id

The id of the list these respondents should be added to

List id

Yes

company_id

The id of the company these respondents should be under

Company id

Only if you have access to more than one company

overwrite

To allow overwriting conflicting respondents with new value

true/false

Yes

username

Respondent’s username to access the app

Should be unique across the instance

Yes

phonenumber

Respondent’s phone number

Mobile number with international code

Either Email or phonenumber is required

email

Respondent’s email address

email

Either Email or phonenumber is required

sample_fields

This should contain all the custom sample fields you want to specify for your respondents

Array of all custom sample fields

Only if you have custom sample fields in your company

alias

Alias of the sample field

 

Yes

value

Value of the sample field

Depends on the types of the sample fields

Yes

Return values

HTTP error responses

Code

Message

Reason

HTTP 400

Action not supported

Not a POST request

HTTP 403

Not supported

Not using HTTPS

A valid request (POST request over HTTPS) in the correct format will have a status that is either OK for successful request or error if the request has failed, the status is accompanied with a descriptive message that explains what went wrong according to the table below

Status Message Reason
ok Import started successfully success message, includes id parameter.
error Error missing required parameter. One of user_name/password/respondents_json is missing.
error Authentication failure. Failed to authenticate with given credentials.
error Could not fetch sample fields for user. Failed to get the respondent fields from survey storage.
error Field contains invalid data.; sample field X Respondent field is not the correct type (usually integer expected)
error Field cannot be empty.; sample field X A required respondent field was empty.
error Could not parse json parameter as a JSONObject. Parse error when parsing the respondents_json - not valid JSON string
error Import failed, Respondent ID must use only characters 'A-Z a-z 0-9 ._-@' Respondent username had unacceptable character or format.
error Import failed, Username must be specified. A respondent username is missing.
error Import failed, Phone number not valid. (Use only 0-9 and +). A respondent had an invalid phone number set.
error Import failed, Either phone number or e-mail must be specified! A respondent was missing both phone number and email.
error Import failed, Invalid e-mail! A respondent had an invalid email.
error Import failed, Too many respondents. A preview group can only contain a maximum of <N> respondents. The number of respondents in the list exceeds the config max number for a preview group.
error Could not start bulk import from API call. General exception message.

Callback response

The bulk import of respondents is run as an asynchronous task, the final results are posted to the callback url, which be HTTP or HTTPS, both are acceptable. The callback response is also a POST request that is UTF-8 encoded. The request contains Json string in the following format

{"status":"", "message":"", "id":""}

Parameter

Description

Value

Status

Gives the final result of the entire import operation

OK/error

Message

Result message containing errors of finish info

See next table

id

Timestamp of when the operation was completed

 

Message parameter values

Status

Message

Resason

ok

Responent import finished successfully. X of Y respondents imported.

OK message, contains a count of respondents that was imported out of the ones that passed all the initial validation steps.

error

Import was canceled by the server before finishing.

Import task was cancelled. Normally because the server plugins were reloaded or similar.

error

Could not overwrite respondent X, import stopped.

Error overwriting a respondent.

error

Could not import respondent X, aborting import. <exception details>

Import stopped because of an exception.

error

Could not flush database write queue, it is possible that not all respondents was imported. <exception details>

Database error, impossible to say if all respondents were imported or not.

Copying respondents between Lists

This is a web service for copying respondents to another list via an HTTP POST request that must be done over HTTPS (secure connection).

Essentially, the service can be used to automate copying respondents to your Lumi Say back-end from any other back-end.

POSTs are directed to the Lumi Say instance server of your own project using a URL with the following format.

https://<domain>/reactor-webapp/pt/<project>/pn/lumicompass/api/copy_respondents_to_list

The request should contain the following parameters

Name

Description

Value

user_name

A back-end user with the right permissions and company access

Your dashboard username

password

A correct password for the user, so we can authenticate

Your dashboard password

respondents_json

A JSON String containing the participant data. See JSON string example below.

The to be copied respondents in JSON string following the format shown in the example below

JSON format

{
"group_id": "",
"respondents": [
{
"username": "r1"
},
{
"username": "r2"
},

...
]
}

JSON string parameters

Parameter

Description

Value

Required

username

Respondent’s username to access the app

This is unique across the instance

Yes

respondents

Container of all the respondents to be copied

JSON string

Yes

group_id

The id of the list these respondents should be copied to

List id

Yes

company_id

The id of the company these respondents should be under

Company id

Only if you have access to more than one company

Returned values

HTTP error responses

Code

Message

Reason

HTTP 400

Action not supported

Not a POST request

HTTP 403

Not supported

Not using HTTPS

A valid request (POST request over HTTPS) in the correct format will have a status that is either OK for successful request or error if the request has failed, the status is accompanied with a descriptive message that explains what went wrong according to the table below

Status

Message

Reason

ok

Respondents copied to list X

success message

error

Error missing required parameter.

One of user_name/password/respondents_json is missing.

error

Authentication failure.

Failed to authenticate with given credentials.

error

Could not parse json parameter as a JSONObject. No respondents found!

Could not parse any respondent ids from the JSON.

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

Too many respondents. A preview group can only contain a maximum of <N> respondents

Failed because preview group contained more respondents than the config max limit.

error

Unable to assign respondents.

Error when storing the new group assignments.

error

Error copying respondents.

General exception message. 

Removing respondents from a List

This is a web service for removing respondents from their current list via an HTTP POST request that must be done over HTTPS (secure connection) 

Essentially, the service can be used to automate removing respondents from a list, thereby removing a respondent's access from any surveys assigned to that list.

POSTs are directed to the Lumi Say instance server of your own project using a URL with the following format.

https://<domain>/reactor-webapp/pt/<project>/pn/lumicompass/api/remove_respondents_from_list

The request should contain the following parameters

Name

Description

Value

user_name

A back-end user with the right permissions and company access

Your dashboard username

password

A correct password for the user, so we can authenticate

Your dashboard password

respondents_json

A JSON String containing the participant data. See JSON string example below.

The to be copied respondents in JSON string following the format shown in the example below

JSON Format

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

JSON string parameters

Parameter

Description

Value

Required

username

Respondent’s username to access the app

This is unique across the instance

Yes

group_id

The id of the list these respondents should be removed from

List id

Yes

company_id

The id of the company these respondents are under

Company id

Only if you have access to more than one company

Returned values

HTTP error responses

Code

Message

Reason

HTTP 400

Action not supported

Not a POST request

HTTP 403

Not supported

Not using HTTPS

A valid request (POST request over HTTPS) in the correct format will have a status that is either OK for successful request or error if the request has failed, the status is accompanied with a descriptive message that explains what went wrong according to the table below

Status

Message

Reason

ok

Respondents removed from list X

success message

error

Error missing required parameter.

One of user_name/password/respondents_json is missing.

error

Authentication failure.

Failed to authenticate with given credentials.

error

Could not parse json parameter as a JSONObject. No respondents found!

Could not parse any respondent ids from the JSON.

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

The following respondents could not be deleted from the list: [r1,r2,…]

Respondents have to belong to one list at least, this API should not delete respondents.