Note: The following information referes to versions 4 and under of the API. Access version 5 filtering information here.
Filtering can be used in conjunction with the GET method on the following objects and sub-objects: survey, surveycampaign, surveyresponse, and accountuser. Filtering is not supported in the PUT, POST or DELETE methods.
Basic Structure
A filter is actually made up of three separate parameters - the field, the operator, and the value. These are accessed using array notation:
filter[field], filter[operator] and filter[value]
Because you can specify multiple filters on the same API call, there is an index added on to each parameter. These are 0-indexed, so your first filter would be made up of:
filter[field][0], filter[operator][0] and filter[value][0]
Put together, you'll end up with the following:
filter[field][0]=___&filter[operator][0]=___&filter[value][0]=___
If you have multiple conditions it should look like so:
filter[field][0]=value&filter[operator][0]=value&filter[value][0]=value&filter[field][1]=value&filter[operator][1]=value&filter[value][1]=value&filter[field][2]=value&filter[operator][2]=value&filter[value][2]=value
Alternative Structure
If you are having trouble filtering, try this alternative method! Use the query string parameter altfilter and url encode your filter parameters.
altfilter=filter%5Bfield%5D%5B0%5D%3Dvalue%26filter%5Boperator%5D%5B0%5D%3Dvalue%26filter%5Bvalue%5D%5B0%5D%3Dvalue
Fields
| Possible Fields | Example | Associated Objects |
|---|---|---|
| Question | [question(2)] | surveyresponse |
| Question Option | [question(2), option(10001)] | surveyresponse |
| URL Variable | [url("variablename")]* | surveyresponse |
| Date Submitted datesubmitted (EST/EDT or GMT -5/GMT -4) | datesubmitted | surveyresponse |
| Is Test Data | istestdata | surveyresponse |
| Contact ID (v4 & v5 API only) | contact_id | surveyresponse |
| Status | status | surveyresponse, survey, surveycampaign |
| Time of Creation | createdon | survey |
| Time of Last Modification | modifiedon | survey |
| Survey Title | title | survey |
| Type of Project (Survey, Quiz, Form, Poll) | subtype | survey |
| Team Survey Belongs To | team | survey |
| Type of Link | _type | surveycampaign |
| Name of Link | name | surveycampaign |
| Secure / Unsecure Link | ssl | surveycampaign |
| Date Link was Created | datecreated | surveycampaign |
| Date Link was Last Modified | datemodified | surveycampaign |
| Email Address | semailaddress | contact |
| status | Active, Disabled, all | accountuser |
| email@email.com | accountuser |
*URL Encode the square brackets and the double quotes.
Operators
| Operation | Syntax | Requires a Value |
|---|---|---|
| Is Equal To | = | True |
| Is Not Equal To | <> or != | True |
| Less Than or Equal To | <= | True |
| Greater Than or Equal To | >= | True |
| Is Answered / Is Not Blank | IS NOT NULL | False |
| Is Not Answered / Is Blank | IS NULL | False |
| In Comma Separated List | in | True |
Filtering Examples
This query would return responses with question-id 2 answered yes.
This query would return responses with submission times greater than or equal to 2011-02-23 13:23:28 and with the status of Complete.
This query would return the specified contact record (by email) within the given campaign. If no contacts are found for the given email address, total_count of '0' will be displayed.
Browsing Survey Responses
Returns default to 50 results for page. Use the page and resultsperpage parameters to customize your return for these calls.
| Parameter | Example | Associated Objects |
|---|---|---|
| page | page=3 | survey, surveyresponse, surveycampaign, surveyquestion, surveypage, contact |
| resultsperpage* | resultsperpage=100 (max=500) | survey, surveyresponse |
*Note: The limit for resultsperpage is 500 (subject to change), if set over the limit it will default back to the limit.
Browsing Examples
To view a different page of results use the page parameter. The below call would return results 101-150 as results are displayed 50 per page.
https://restapi.surveygizmo.com/v4/survey/123456/surveyresponse?page=3
To view more results per page use the resultsperpage parameter. The below call would return results 1-100.
https://restapi.surveygizmo.com/v4/survey/123456/surveyresponse?resultsperpage=100
Use the page and resultsperpage parameters in conjunction. This below call would return results 201-300.
https://restapi.surveygizmo.com/v4/survey/123456/surveyresponse?page=3&resultsperpage=100