This article covers these topics:

Introduction to respondents APIs

QMob 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 QMob dashboard.

Adding respondents in bulk

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 QMob 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 QMob instance server of your own project using a URL with the following format.

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

URL parameters

<branded_instance>

The first word of your Dashboard URL, e.g. "dashboard"

<project_name>

You can find this at the top right corner of your dashboard, please note this field is case sensitive

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 custom sample fields you want to specify	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	Reason
ok	Respondent 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 from one list to another in your QMob back-end from any other back-end.

POSTs are directed to the QMob 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

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 QMob 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

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.

Articles in this section

Respondent APIs

Introduction to respondents APIs

Adding respondents in bulk

URL parameters

JSON Format

JSON string parameters

Return values

Callback response

Message parameter values

Copying respondents between Lists

JSON format

JSON string parameters

Returned values

Removing respondents from a List

JSON Format

JSON string parameters

Returned values

Articles in this section

Introduction to respondents APIs

Adding respondents in bulk

URL parameters

JSON Format

JSON string parameters

Return values

Callback response

Message parameter values

Copying respondents between Lists

JSON format

JSON string parameters

Returned values

Removing respondents from a List

JSON Format

JSON string parameters

Returned values

Related articles