listSurveys

Returns list of Surveys the user has permission to view. List provides only the metadata about the survey, and does not include the questions for each survey.

Client Servlet Server Servlet HTTP Methods Supported Requires Authentication
CRSurveyAPI None. GET, POST No.

Client API Syntax

https://secure2.convio.net/organization/site/CRSurveyAPI?method=listSurveys &api_key=value &v=value [ &center_id=value ] [ &error_redirect=value ] [ &redirect=value ] [ &response_format=xml | json ] [ &sign_redirects=value ] [ &source=value ] [ &sub_source=value ] [ &success_redirect=value ] [ &suppress_response_codes=value ] &published_only=value [ &list_ascending=value ] [ &list_category_id=value ] [ &list_filter_column=value ] [ &list_filter_text=value ] [ &list_page_offset=value ] [ &list_page_size=value ] [ &list_record_offset=value ] [ &list_sort_column=value ]

Usage Notes

Use this client-only method to retrieve a list of all the surveys available to that user. The user must have permission to view a survey in order for it to be returned by this method.

Note: Unpublished surveys are not accessible outside of the Luminate Online Admin Interface, so you will almost always want to retrieve only the published surveys. For this reason the published_only parameter is optional and defaults to true.

Sorting or Filtering by Column:

To sort or filter the results, the list_sort_column and list_filter_column parameters accept the following values (case-sensitive):
  • surveyId
  • surveyName
  • surveyIntroduction
  • isAllowMultipleSubmission
  • isSecureSurvey
  • isNumberQuestions
  • state
  • publishedDate
  • stopDate

Client API Parameters

Common Client Parameters

See topic Common Parameters.

published_only

Required. Parameter indicating whether or not to list only published surveys. Default is true.

Type xsd:boolean.

Default is true.

list_ascending

Optional. Whether the list should be sorted in ascending order.

Type xsd:boolean.

Default is true.

list_category_id

Optional. Security Category filter.

Type xsd:integer.

list_filter_column

Optional. The database column that will be used to match the filter text (used with "list_filter_text").

Type xsd:string.

list_filter_text

Optional. The text that will be used to filter results.

Type xsd:string.

list_page_offset

Optional. The requested page number (used with "list_page_size"). The first page (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_page_size

Optional. The number of results in each page (used with "list_record_offset" or "list_page_offset").

Type xsd:integer.

Default is 25.

list_record_offset

Optional. The requested initial record number (used with "list_page_size"). The first record (default) is zero. Only one of "list_record_offset" or "list_page_offset" should be used in a request.

Type xsd:integer.

list_sort_column

Optional. The column to sort with (used with "list_ascending").

Type xsd:string.

Response

See topic HTTP Status Codes.

XML response 
<?xml version="1.0" encoding="UTF-8"?>
<listSurveysResponse 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">
  <pagingMetadata>
    <currentSize>3</currentSize>
    <isFinalSize>true</isFinalSize>
  </pagingMetadata>
  <surveys>
    <surveyId>1001</surveyId>
    <surveyName>New User Survey</surveyName>
    <viewSecurityCategory>
      <id>1</id>
      <label>General</label>
    </viewSecurityCategory>
    <reportSecurityCategory>
      <id>2</id>
      <label>Administrators Only</label>
    </reportSecurityCategory>
    <surveyIntroduction>Welcome to our site!  Please take a few moments to tell us about your experience:</surveyIntroduction>
    <resetButtonLabel>Clear Response</resetButtonLabel>
    <skipButtonLabel>No, Thanks</skipButtonLabel>
    <submitButtonLabel>Tell us</submitButtonLabel>
    <isAllowMultipleSubmission>false</isAllowMultipleSubmission>
    <isSecureSurvey>false</isSecureSurvey>
    <isNumberQuestions>true</isNumberQuestions>
    <submitSurveyUrl>http://www.yourdomain.org/site/PageServer?pagename=thank_you</submitSurveyUrl>
    <cancelSurveyUrl>http://www.yourdomain.org/site/PageServer</cancelSurveyUrl>
    <state>PUBLISHED</state>
    <publishedDate>2016-02-01T09:43:44.925-06:00</publishedDate>
    <stopDate>2021-02-01T09:43:44.925-06:00</stopDate>
  </surveys>
  <surveys>
    <surveyId>1002</surveyId>
    <surveyName>January 2009 User Engagement</surveyName>
    <viewSecurityCategory>
      <id>1</id>
      <label>General</label>
    </viewSecurityCategory>
    <reportSecurityCategory>
      <id>2</id>
      <label>Administrators Only</label>
    </reportSecurityCategory>
    <surveyIntroduction/>
    <resetButtonLabel>Clear Response</resetButtonLabel>
    <skipButtonLabel>No, Thanks</skipButtonLabel>
    <submitButtonLabel>Tell us</submitButtonLabel>
    <isAllowMultipleSubmission>false</isAllowMultipleSubmission>
    <isSecureSurvey>false</isSecureSurvey>
    <isNumberQuestions>true</isNumberQuestions>
    <submitSurveyUrl>http://www.yourdomain.org/site/PageServer?pagename=thank_you</submitSurveyUrl>
    <cancelSurveyUrl>http://www.yourdomain.org/site/PageServer</cancelSurveyUrl>
    <state>PUBLISHED</state>
    <publishedDate>2016-02-01T09:43:44.925-06:00</publishedDate>
    <stopDate>2021-02-01T09:43:44.925-06:00</stopDate>
  </surveys>
  <surveys>
    <surveyId>1003</surveyId>
    <surveyName>Fun Event Survey</surveyName>
    <viewSecurityCategory>
      <id>1</id>
      <label>General</label>
    </viewSecurityCategory>
    <reportSecurityCategory>
      <id>2</id>
      <label>Administrators Only</label>
    </reportSecurityCategory>
    <surveyIntroduction/>
    <resetButtonLabel>Clear Response</resetButtonLabel>
    <skipButtonLabel>No, Thanks</skipButtonLabel>
    <submitButtonLabel>Tell us</submitButtonLabel>
    <isAllowMultipleSubmission>false</isAllowMultipleSubmission>
    <isSecureSurvey>false</isSecureSurvey>
    <isNumberQuestions>true</isNumberQuestions>
    <submitSurveyUrl>http://www.yourdomain.org/site/PageServer?pagename=thank_you</submitSurveyUrl>
    <cancelSurveyUrl>http://www.yourdomain.org/site/PageServer</cancelSurveyUrl>
    <state>PUBLISHED</state>
    <publishedDate>2016-02-01T09:43:44.925-06:00</publishedDate>
    <stopDate>2021-02-01T09:43:44.925-06:00</stopDate>
  </surveys>
</listSurveysResponse>
JSON response 
{"listSurveysResponse":{"pagingMetadata":{"isFinalSize":"true","currentSize":"3"},"surveys":[{"stopDate":"2021-02-01T09:43:44.927-06:00","resetButtonLabel":"Clear Response","surveyIntroduction":"Welcome to our site!  Please take a few moments to tell us about your experience:","state":"PUBLISHED","surveyName":"New User Survey","submitSurveyUrl":"http://www.yourdomain.org/site/PageServer?pagename=thank_you","cancelSurveyUrl":"http://www.yourdomain.org/site/PageServer","skipButtonLabel":"No, Thanks","reportSecurityCategory":{"id":"2","label":"Administrators Only"},"submitButtonLabel":"Tell us","isAllowMultipleSubmission":"false","isNumberQuestions":"true","publishedDate":"2016-02-01T09:43:44.927-06:00","viewSecurityCategory":{"id":"1","label":"General"},"surveyId":"1001","isSecureSurvey":"false"},{"stopDate":"2021-02-01T09:43:44.927-06:00","resetButtonLabel":"Clear Response","surveyIntroduction":{},"state":"PUBLISHED","surveyName":"January 2009 User Engagement","submitSurveyUrl":"http://www.yourdomain.org/site/PageServer?pagename=thank_you","cancelSurveyUrl":"http://www.yourdomain.org/site/PageServer","skipButtonLabel":"No, Thanks","reportSecurityCategory":{"id":"2","label":"Administrators Only"},"submitButtonLabel":"Tell us","isAllowMultipleSubmission":"false","isNumberQuestions":"true","publishedDate":"2016-02-01T09:43:44.927-06:00","viewSecurityCategory":{"id":"1","label":"General"},"surveyId":"1002","isSecureSurvey":"false"},{"stopDate":"2021-02-01T09:43:44.927-06:00","resetButtonLabel":"Clear Response","surveyIntroduction":{},"state":"PUBLISHED","surveyName":"Fun Event Survey","submitSurveyUrl":"http://www.yourdomain.org/site/PageServer?pagename=thank_you","cancelSurveyUrl":"http://www.yourdomain.org/site/PageServer","skipButtonLabel":"No, Thanks","reportSecurityCategory":{"id":"2","label":"Administrators Only"},"submitButtonLabel":"Tell us","isAllowMultipleSubmission":"false","isNumberQuestions":"true","publishedDate":"2016-02-01T09:43:44.927-06:00","viewSecurityCategory":{"id":"1","label":"General"},"surveyId":"1003","isSecureSurvey":"false"}]}}

Examples

To retrieve a list of only published surveys: 

    	https://demo-secure.convio.net/demo829/site/CRSurveyAPI?method=listSurveys&v=1.0&api_key=MyAPIKey&published_only=true

To retrieve a list of published and unpublished surveys, perhaps if you are integrating with a 3rd party CMS and want to provide a means of embedding a survey using the getSurvey method, but you want the CMS administrator to see all surveys, including ones that users will not be able to take: 

    	https://demo-secure.convio.net/demo829/site/CRSurveyAPI?method=listSurveys&v=1.0&api_key=MyAPIKey&published_only=false
Parent topic: Survey API
Previous topic: getSurvey
Next topic: submitSurvey

Leave a Comment

Nickname
Comment
Enter this word:
Change