Dispatch API

Add
Answer Callback
Delete
Update
Get

https://host/socrates/restModule/dispatch/add

Creates a dispatch job on the system. Other methods in this API with partially suceed (for example add 3 out or 4 respondents to a group). This is not the case with dispatch as it involves actually starting a questionnaire.

dispatch_name = myDispatch - the name of the dispatch. Also used as the keyword in SMS surveys. Will be forced to lower case.(REQUIRED)

questionnaire_name = myQuestionnaire - the name of the questionnaire to dispatch (ONE OF EITHER questionnaire_name OR questionnaire_id IS REQUIRED)

questionnaire_id = 1 - the id of the questionnaire to dispatch (ONE OF EITHER questionnaire_name OR questionnaire_id IS REQUIRED)

group_names = myGroup1,myGroup2 - a ',' separated list of groups to dispatch to (AT LEAST ONE OF group_names OR group_ids IS REQUIRED)

group_ids = 1,2 - a ',' separated list of groups to dispatch to (AT LEAST ONE OF group_names OR group_ids IS REQUIRED)

expiry_time = 2006-04-22 13:12 GMT- the time when the dispatch expires. Defaults to no expiry.(OPTIONAL)

dispatch_time = 2006-04-22 1:12 GMT- the time when the dispatch should be dispatched. Defaults to now.(OPTIONAL)

dispatch_type = SMS|BROWSER|APP - the type of interaction with the respondent. Uses the default type set up for the respondent if not specified (OPTIONAL)

allow_multiple = true|false - whether to allow multiple responses from each respondent to the dispatch. Defaults to false. (OPTIONAL)

reminder_frequency = 120 - the number of minutes after which a reminder text will be sent. Defaults to no reminders.(OPTIONAL)

reminder_sms_text = Remember to respond! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

reminder_browser_text = Remember to look at your WAP page! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

reminder_app_text = Remember to start you suyvey application! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

sms_intro_text = "Please respond with the keyword dispatch_name to take part in a survey." If not specified then no introduction text is sent.(OPTIONAL)

sms_expect_intro_response = true|false - whether to wait until an answer with the keyword in to send out the first question. Defaults to true, but is ignored if sms_intro_text is not specified.(OPTIONAL)

sms_keywordless_repeat = true|false - whether to expect a keyword to start off the next itteration of an SMS questionnaire when using mulitple response. Defaults to false.(OPTIONAL)

sms_resend_first_question = true|false - whether to send out the first question again for sms when using multiple responses. Defaults to true. Ignored if sms_keywordless_repeat is true.(OPTIONAL)

browser_intro_text = "Follow link to new survey" If not specified then no introduction text is sent.(OPTIONAL)

app_intro_text = "Start the socrates app for a new survey" If not specified then no introduction text is sent.(OPTIONAL)

sms_provider = the prefered provider for sending SMS messages, if omitted messages are send by default provider (OPTIONAL)

http_callback = http://somehost.com - the address that should be called when results come in. No callback it performed if this is not set. See section below for Answer Callback Parameters. (OPTIONAL)

Errors:

DispatchExistsError
QuestionnaireDoesNotExistError
RespondentGroupDoesNotExistError
InvalidSyntaxError
UnknownTimeFormatError
UnknownDisptachTypeError
UnknownReminderFrequencyFormatError
HTTPCallbackFormatError

Answer Callback Parameters

The parameters returned with the http_callback URL are:

respondent - The phone number of the respondent.

respondent_id - The respondent id.

time - The time the answer was received. In the form 'yyyy-MM-dd HH:mm z'.

response - The response index number, 0 for the first time the question is answered, 1 for the second, etc.

answers - The answer provided to the question. A question with multiple answers (e.g. choose many) will generate a '|' separated list of answers.

answer_names - The associated answer names for the answers. Also a '|' separated list for multiple answers.

dispatch_name - The dispatch name.

dispatch_id - The dispatch id.

questionnaire_name - The questionnaire name.

questionnaire_id - The questionnaire id.

question_name - The name of the question.

end - If the question answered here is the last question of the questionnaire of the survey. It's value is 'true' or it's not provided. 'True' means that the respondent has anwserved all reveleant questions and reached the end, regardless of whether or not the dispatch allows the respondent to answer the questionnaire multiple times. If the end parameter is not provided, then this is not the end.

For example:

http://somehost.com/?dispatch_name=dispatch1&dispatch_id=1&questionnaire_name=AllQuestionTypes&questionnaire_id=1&respondent_id=
1&question_name=youbought&respondent=4152445808&time=2006-07-28+17%3A10+PDT&response=0&answers=yes&

https://host/socrates/restModule/dispatch/delete

Remove an existing dispatch job from the system.

dispatch_names = myDispatch,myDispatch2 - a ',' separated list of the names of the dispatches to be deleted.(AT LEAST ONE OF dispatch_names OR dispatch_ids IS REQUIRED)

dispatch_ids = 1,2 - a ',' separated list of the ids of the dispatches to be deleted.(AT LEAST ONE OF dispatch_names OR dispatch_ids IS REQUIRED)

Errors:

DispatchDoesNotExistError
InvalidSyntaxError

https://host/socrates/restModule/dispatch/update

Update (read replace - the old values will be gone) the parameters of an existing dispatch job in the system.

dispatch_name = myDispatch - the name of the dispatch. Also used as the keyword in SMS surveys. (ONE OF EITHER dispatch_name OR dispatch_id IS REQUIRED)

dispatch_id = myDispatch - the id of the dispatch. (ONE OF EITHER dispatch_name OR dispatch_id IS REQUIRED)

new_dispatch_name = myNewDispatch - the new name of the dispatch. Will be forced to lower case. (OPTIONAL)

questionnaire_name = myQuestionnaire - the name of the questionnaire to dispatch (OPTIONAL BUT ONLY ONE OF questionnaire_name OR quesitonnaire_id CAN BE SPECIFIED)

questionnaire_id = 1 - the id of the questionnaire to dispatch (OPTIONAL BUT ONLY ONE OF questionnaire_name OR quesitonnaire_id CAN BE SPECIFIED)

group_names = myGroup1,myGroup2 - a ',' separated list of groups to dispatch to (OPTIONAL)

group_ids = 1,2 - a ',' separated list of groups to dispatch to (OPTIONAL)

expiry_time = 2006-04-22 13:12 GMT - the time when the dispatch expires. Defaults to no expiry.(OPTIONAL)

dispatch_time = 2006-04-22 13:12 GMT - the time when the dispatch should be dispatched. Defaults to now.(OPTIONAL)

dispatch_type = SMS|BROWSER|APP - the type of interaction with the respondent. Uses the default type set up for the respondent if not specified (OPTIONAL)

allow_multiple = true|false - whether to allow multiple responses from each respondent to the dispatch. Defaults to false. (OPTIONAL)

reminder_frequency = 120 - the number of minutes after which a reminder text will be sent. Defaults to no reminders.(OPTIONAL)

reminder_sms_text = Remember to respond! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

reminder_browser_text = Remember to look at your WAP page! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

reminder_app_text = Remember to start you suyvey application! - the text to send in the reminder text. Ignored if reminder_frequency is not specified. (REQUIRED if reminder_frequency is specified)

sms_intro_text = "Please respond with the keyword dispatch_name to take part in a survey." If not specified then no introduction text is sent.(OPTIONAL)

sms_expect_intro_response = true|false - whether to wait until an answer with the keyword in to send out the first question. Defaults to true, but is ignored if sms_intro_text is not specified.(OPTIONAL)

browser_intro_text = "Follow link to new survey" If not specified then no introduction text is sent.(OPTIONAL)

app_intro_text = "Start the socrates app for a new survey" If not specified then no introduction text is sent.(OPTIONAL)

sms_provider = the prefered provider for sending SMS messages, if omitted messages are send by default provider (OPTIONAL)

http_callback = http://somehost.com - the address that should be called when results come in. No callback it performed if this is not set. See section above for Answer Callback Parameters. (OPTIONAL)

Errors:

DispatchUnderwayError - dispatch_type, dispatch_name and questionnaire cannot be changed once the dispatch is under way.
DispatchDoesNotExistError
NewDispatchExistsError
QuestionnaireDoesNotExistError
RespondentGroupDoesNotExistError
InvalidSyntaxError
UnknownTimeFormatError
UnknownDisptachTypeError
UnknownReminderFrequencyFormatError
HTTPCallbackFormatError

https://host/socrates/restModule/dispatch/get

Fetch an existing dispatch job.

dispatch_names = myDispatch,myDispatch2 - a ',' separated list of the names of the dispatches. All will be returned if neither dispatch_names or dispatch_ids is specified. (OPTIONAL)

dispatch_ids = 1,2 - a ',' separated list of the ids of the dispatches. All will be returned if neither dispatch_names or dispatch_ids is specified. (OPTIONAL)

Errors:

DispatchDoesNotExistError
InvalidSyntaxError