Filters - Version 5

 Help Us Improve Our API Documentation!

We're beginning an initiative to improve our API docs. We would love your help!

Please take this quick 4-question survey to help us out! Thank you in advance for your time!

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 FieldsExampleAssociated 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)date_submittedsurveyresponse
Is Test Datais_test_datasurveyresponse
Contact IDcontact_idsurveyresponse
Statusstatussurveyresponse, survey, surveycampaign
Time of Creationdate_createdsurvey
Time of Last Modificationdate_modifiedsurvey
Survey Titletitlesurvey
Type of Project (Survey, Quiz, Form, Poll)typesurvey
Team Survey Belongs Toteamsurvey
Link IDidsurveycampaign
Typetypesurveycampaign
Link Typelink_typesurveycampaign
Name of Linknamesurveycampaign
Secure / Unsecure Linksslsurveycampaign
Date Link was Createddate_createdsurveycampaign
Date Link was Last Modifieddate_modifiedsurveycampaign
Email Address
semailaddress
surveycontact
statusActive, Disabled, allaccountuser
emailemail@email.comaccountuser

*URL Encode the square brackets and the double quotes.

Operators

OperationSyntaxRequires 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 BlankIS NOT NULLFalse
Is Not Answered / Is BlankIS NULLFalse
In Comma Separated ListinTrue

Filtering Examples

This query would return responses with question-id 2 answered yes.

https://restapi.surveygizmo.com/v5/survey/123456/surveyresponse?filter[field][0]=[question(2)]&filter[operator][0]==&filter[value][0]=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.

https://restapi.surveygizmo.com/v5/survey/123456/surveyresponse?filter[field][0]=date_submitted&filter[operator][0]=>=&filter[value][0]=2011-02-23+13:23:28&filter[field][1]=status&filter[operator][1]==&filter[value][1]=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.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/123456/surveycontact?filter[field][0]=semailaddress&filter[operator][0]==&filter[value][0]=test.test@test.com

Browsing Survey Responses

Returns default to 50 results for page. Use the page and resultsperpage parameters to customize your return for these calls.

ParameterExampleAssociated Objects
pagepage=3survey, 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/v5/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/v5/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/v5/survey/123456/surveyresponse?page=3&resultsperpage=100