Introduction
Information Model
API Interfaces
XML Schema For Questionnaires
Method Errors
Method Parameters
Inbound SMS URL Parameters
Outbound SMS URL Parameters
Information Model
Respondents - a respondent the object that represents an end user that will complete surveys from the system.
Groups - a group is a container for respondents. A respondent can be in any number of groups.
Questionnaire - a questionnaire is a definition of a series of questions. It is fully defined in an XML Schema for the XML format and at http://www.triple-s.org/ for triple s.
Dispatch - a dispatch is a number of groups and a questionnaire. Interaction with respondents is initiated when a dispatch is created.
Results - results represent answers to dispatches from respondents.
API Interfaces
The MSurvey API includes the following interfaces:
Respondent API
Group API
Questionnaire API
Dispatch API
Results API
XML Schema For Questionnaires
XSD Schema
Method Errors
If no error occurs then HTTP 200 OK is sent back. If an expected system error occurs then HTTP 202 ACCEPTED is sent back along with an XML document detailing the errors. The document will look like this:
<errors xmlns="http://www.embracemobile.com/socrates/1.0" >
<error id="theErrorID" >Any relevant info here</error>
<error id="theErrorID2" >Any relevant info here</error>
</errors>
Method Parameters
All method parameters include the following:
user = username - the username of the account, (REQUIRED).
password = password - the password of the account, (REQUIRED).
Possible errors from these paramters (or lack thereof) are:
UserDoesNotExistError
InvalidUserDetailsError
In addition, all calls can result in a InvalidSyntaxError if the proper parameters are not passed in. English error desciptions are added where ever possible.
Inbound SMS URL Parameters
from - The phone number of the respondent from whom the SMS message is from. e.g. 15556667777 or 44787888999
modem - The phone number of the modem to which the message was sent. e.g. as above.
message - The text message received. e.g. Hello Bob!
e.g. http://somehost:port/socrates2sms?from=123&modem=456&message=hey+there
Outbound SMS URL Parameters
Currently as per the Clickatell interface specification:
to - The phone number of the respondent to whom the SMS message is from. e.g. 15556667777 or 44787888999
from - The phone number of the modem from which the message is to be send sent. e.g. as above.
text - The text message to be sent. e.g. Hello Bob!
e.g. http://somehost:port/?to=123&from=456&text=hey+there
|
