Accepts responses to a single, active (published and not expired) survey and stores the responses, including creating or updating the constituent record if appropriate.
| Client Servlet | Server Servlet | HTTP Methods Supported | Requires Authentication |
|---|---|---|---|
| CRSurveyAPI | None. | POST | Yes. |
Use this client-only method to submit a user's response to a single survey. To retrieve the survey, see the getSurvey method. Since this method can create and update constituent records it can only be used from trusted sources and requires an auth_token be passed in as the auth parameter.
Submitting Responses To Questions
Submitting a response to a question is done by building a parameter using the question's ID and the prefix question_. For Example, to submit an answer of "test" to a question with the ID of 1002, you would use: "question_1002=test".
Constituent Registration Information (CRI) Questions
These questions are made up of multiple fields, and each field must be stored separately within Luminate Online. For this reason, each field within a CRI question has it's own parameter that you use to submit the response for that field.
The processing of responses to CRI questions through the survey is the same as the processing through the normal Survey application. The question's configuration determines whether to automatically log users in, how to handle cases where the user's responses match an existing constituent, etc.
Post-Submission Handling
Submitting a survey can login the user submitting the survey, you should refresh your auth token after submission.
This method will not automatically redirect to the URL specified in the Survey's configuration as the "Survey Submitted Page". The response will contain that URL as the nextUrl parameter if you do want to redirect the user there.
The response also contains the Survey Thank You Page content that taking a survey directly (not through the API) would normally display. This is not a page that is possible to configure through the Luminate Online Admin Interface, nor is it something that can be linked to directly, but if you want to provide the same user-experience through the API as what the user would see when taking a survey not through the API, this is the thank you page content they would see if there is no "Survey Submitted Page" set for the survey.
A successful response to this method will also contain the user's responses to questions that they can provide a meaningful answer to. The response will contain an array of userResponses that contain the questionID, Question Text, and the responseValues that a user provided to that question. This will let you build a custom thank you page that can echo back to the user the answers that they provided, or create branching functionality based on their answers in the event of a successful submission.
See topic Common Parameters.
Required. The ID of the survey you are accessing.
Type xsd:nonNegativeInteger.
Optional. Parameter containing the value of the Birth Date field when submitting a survey containing a Constituent Registration Information Question, formatted per the ISO 8601 specification.
Type xsd:dateTime.
Optional. Parameter containing the value of the City field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Country field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the County field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Email field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Preferred Email Format field when submitting a survey containing a Constituent Registration Information Question. Default value if not provided is '0' indicating the user has no preferred format.
Type xsd:nonNegativeInteger.
Default is 0.
Optional. Parameter indicating the Email Opt In choice of a user when submitting a survey containing a Constituent Registration Information (CRI) Question. True indicates the constituent should be opted in, false indicates they should be opted out.
Type xsd:boolean.
Optional. Parameter containing the value of the Employer field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the First Name field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Gender field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Last Name field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Middle Name field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Occupation field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Password field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Phone Number field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter indicating the Postal Mail Opt In choice of a user when submitting a survey containing a Constituent Registration Information (CRI) Question. True indicates the constituent should be opted in, false indicates they should be opted out.
Type xsd:boolean.
Optional. Parameter containing the value of the Professional Suffix field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Confirm / Re-enter Password field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the State field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Street 1 field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Street 2 field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Street 3 field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Suffix field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Title field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the User name field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter containing the value of the Zip / Postal Code field when submitting a survey containing a Constituent Registration Information Question.
Type xsd:string.
Optional. Parameter indicating that the submission should NOT be accepted. This is a weak method of preventing scripts from submitting spam via your surveys by including a text input field that is hidden using Cascading Style Sheets (CSS). Do not use a hidden input field for this, as most spam-scripts do not auto-populate hidden inputs. If a script automatically fills in that field and submits the survey, the submission will not be processed. It is recommended that you provide a label indicating that humans should not fill in this field so that humans using a screen reader know to leave that field empty.
Type xsd:string.
Optional. This parameter is not used by itself, but is used in conjunction with the Question's Id to create a Question Indicator Parameter. You must append a question's question Instance ID after the underscore, at which point this parameter indicates the answer to that question. Ex: 'question_1001=hello' would indicate that the question with the id 1001 is being submitted with an answer of 'hello'. When providing answers to a DateQuestion question, this parameter must be a date string formatted per the ISO 8601 specification. When providing answers to a NumericValue question this parameter must be a numeric value. For all other question types, this parameter is a string. Note: This type of Question Indicator Parameter is not used for Constituent Registration Information questions.
Type xsd:string.
Optional. Parameter indicating that the system should remember the user after logging them in (if the question is configured to log new users in).
Type xsd:boolean.
Optional. Parameter indicating that user clicked the cancel/skip button. Submitting a value of 'true' indicates that the user has cancelled and the API will return a response indicating that the submission was successful and that the user cancelled. The response will include URL to redirect to based on the survey configuration (if any). Does not perform an automatic redirect.
Type xsd:boolean.
Default is false.
Optional. You must provide either this parameter or the sso_auth_token parameter. If using this parameter, you must specify an auth token generated by an embedded [[S86]] session tag in a Convio web page.
Optional. You must provide either this parameter or the auth parameter. If using this parameter, you must specify a valid session authentication token returned by login, authenticateUser, or getSingleSignOnToken.
See topic HTTP Status Codes.
XML response
<?xml version="1.0" encoding="UTF-8"?>
<submitSurveyResponse xsi:schemaLocation="http://convio.com/crm/v1.0 http://service.convio.net/xmlschema/crm.public.v1.xsd" xmlns="http://convio.com/crm/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<success>true</success>
<userCanceled>false</userCanceled>
<nextUrl xsi:nil="true"/>
<thankYouPageContent><![CDATA[<div class="appArea"><p>Thank you for taking the Tell us A Little About You survey. Your input is very valuable to us in designing our program.</p><p>This organization often shares survey results with registered users. There are many benefits to being a registered user, and you can help us serve you more effectively by registering.</p><p><a href="http://yourdomain.org/site/ConsProfileUser">Click here to register and receive personalized content and email updates.</a></p></div><div class="appArea"><form action="http://yourdomain.org/site/PageServer" method="post"><p><input type="submit" name="go" id="go" value="Home" class="Button" /></p><input type="hidden" name="SURVEY_ID" id="SURVEY_ID" value="1001" /></form></div>]]></thankYouPageContent>
<userResponses>
<questionId>1001</questionId>
<questionText>What is your favorite color?</questionText>
<responseValue>Blue</responseValue>
</userResponses>
<userResponses>
<questionId>1010</questionId>
<questionText>When did you first visit our site?</questionText>
<responseValue>Jan 10 2010</responseValue>
</userResponses>
<userResponses>
<questionId>1010</questionId>
<questionText>What types of content are you interested in?</questionText>
<responseValue>1003</responseValue>
<responseValue>1028</responseValue>
</userResponses>
</submitSurveyResponse>
JSON response
{"submitSurveyResponse":{"thankYouPageContent":"<div class=\"appArea\"><p>Thank you for taking the Tell us A Little About You survey. Your input is very valuable to us in designing our program.<\/p><p>This organization often shares survey results with registered users. There are many benefits to being a registered user, and you can help us serve you more effectively by registering.<\/p><p><a href=\"http://yourdomain.org/site/ConsProfileUser\">Click here to register and receive personalized content and email updates.<\/a><\/p><\/div><div class=\"appArea\"><form action=\"http://yourdomain.org/site/PageServer\" method=\"post\"><p><input type=\"submit\" name=\"go\" id=\"go\" value=\"Home\" class=\"Button\" /><\/p><input type=\"hidden\" name=\"SURVEY_ID\" id=\"SURVEY_ID\" value=\"1001\" /><\/form><\/div>","nextUrl":null,"userCanceled":"false","userResponses":[{"questionId":"1001","questionText":"What is your favorite color?","responseValue":"Blue"},{"questionId":"1010","questionText":"When did you first visit our site?","responseValue":"Jan 10 2010"},{"questionId":"1010","questionText":"What types of content are you interested in?","responseValue":["1003","1028"]}],"success":"true"}}
The example is for a survey with an ID of 1024 and contains the following questions:
| Question ID | Question Type | Question Text | User's Response |
|---|---|---|---|
| 1000 | Constituent Registration Information | Please provide your name and email: | Kelly, Constituent, devnull+kconstituent@convio.com |
| 1001 | Short Text | What is your favorite Color? | Blue |
| 1010 | Numeric Value | How many hours per week do you spend online (personal and business)? | 40 |
| 1024 | Hidden True/False Update | Example Note: question is hidden, so there is no text | TRUE |
| 1030 | Multiple Choice, Multiple Response | What days do you use the internet the most? | Wednesday, Friday |
The following string should be submitted using a POST method:
https://demo-secure.convio.net/demo829/site/CRSurveyAPI?method=submitSurvey&v=1.0&api_key=MyAPIKey&survey_id=1024&question_1001=Blue&question_1010=40&question_1024=TRUE&question_1030=Wednesday&question_1030=Friday&cons_first_name=Kelly&cons_last_name=Constituent&cons_email=devnull+kconstituent@convio.com
Comments