Tutorial: Monkey Around with the SurveyGizmo API

SurveyGizmo Open API – Version 1.5

© 2006-2009 Widgix Software. All Rights Reserved

The Plug-in API is designed so developers such as yourself can integrate SurveyGizmo’s features & campaign capabilities into your own application. It was specifically written for CMS developers and email service providers who want to offer top-notch surveys to their own customers from within their own application. However it can also be used by anyone who wants to monkey around with their surveys and data behind the scenes.

In order to write applications that use the API, you must contact SurveyGizmo and receive a developer key (it’s free).

If creating a public interaction with the SurveyGizmo API, you’ll be able to use the functions defined in this document directly from your application or service. After activating your services from their SurveyGizmo account, your clients will also be able to click right into forms & sections of our survey building application without being prompted for additional logins and passwords.

Public API creations and interactions may require you to send us a little information, including two logo images that our application will use to co-brand the admin-side of things and agree to our terms and conditions to get your key. This is not required when using the API for private usage to access data for your company or personal needs. The header of our application can also be changed so your customers will see your logo next to ours, e.g.-”SurveyGizmo” via “XYZ Service”, as well as a customizable link back to your application added to the top navigation bar. This lets the customer feel as though they are still logged into your application.

What can I do with this API?

This is the first version of the API. Some of the features are currently limited, but are still advanced enough to give you a great benefit. Here are a few examples of how the API may be used:

1. Show your customers a complete list of running surveys they have built in SurveyGizmo – complete with # of current responses, abandons, and direct links to preview, view reporting or promote it.
2. Use the API to embed the survey directly into articles, blog posts or web pages through our JavaScript publishing option
3. Register an email campaign with SurveyGizmo’s tracking module so it can tell your application who on your customer’s mailing list have taken the survey, abandoned it, or never clicked through.
4. Search through response data and extract answers to survey questions and other tracking information, such as query string tokens, referrer, ip, language and geo-location.

Calling the API

The API functions are called over the web by submitting a properly formatted request to https://api.sgizmo.com/

Note: It is strongly recommended to communicate with the API in SSL (HTTPS).

Note: to prevent abuse the standard API does not allow more than one connection from the same IP address per application at the same time. This does not effect most applications, particularly distributed ones. However if you are downloading data in bulk, please design your applications to access data serially whenever possible to avoid this limitation and avoid requesting the same data repetitively. This is to prevent abuse. If you need an exception to this rule, please contact support.

IMPORTANT: Please send along your own custom User-Agent string on all requests, including version number, so we can help our customers out who might be using your application.

The API script takes 3 standard ‘get string’ variables, plus any fields associated with the current action you are going to take. They are:

• Developer Key (dk) – Your developer key, given to your from customer support
• User Key (uk) – Found under Account Settings > API tab, unique to each SurveyGizmo account
• Function – this is a shared ID for both accounts
• Command (cmd) – the action you would like to take (see below)

The first time you send a customer to a SurveyGizmo screen they will be prompted to activate your service for their account by logging in. If they don’t have an account they will be given the chance to create a free account and get started right away. After the initial authorization, your customer will be able to jump between our application and yours seamlessly.

Sample:

https://api.sgizmo.com/?dk=1445726-8127bsr5&uk=gat6615&cmd=getSurveyList&status=Abandoned

Return Values

To make life easy for your developers, the SurveyGizmo application returns three easy to understand type of values (depending on the API call). It returns the word “Error” followed by an error message if something is wrong with your request. Otherwise, it returns a block of text, and in the case of queries that are requesting tabular data, the result set is in CSV format (most languages have an easy way of parsing this data). Otherwise, it is a particular string or snippet of code you requested.

Commands

getSurveyList

Returns: an XML list of the surveys the customer is currently running as well as the links to edit, preview, promote and view reports. Limited to the most recent 30 surveys. Specify the ’status’ field to get a complete list for a particular status.

Fields:

• Status (optional: status= launched, closed or indesign)
• Team (optional: team=[team number], e.g. team=0)
• Survey ID (optional: surveyid=[surveyid], e.g. surveyid=12345) – retrieves the single survey specified
• Created By (optional: createdby=[emailaddress], e.g. createdby=support@sgizmo.com) – returns surveys created by the user, filtered by the user’s email address
• User (optional: user=[emailaddress], e.g. user=support@sgizmo.com) – returns all surveys the user has permissions to access

The file contains the following fields in order:

• Survey ID
• Survey Creator’s name
• Survey Creator’s email
• Team Number
• Survey Title
• Date Created
• Date of last activity
• Total Responses
• Survey Type
• Status (Launched, Closed, In Design)
• Count of surveys in progress
• Count of completed surveys
• Count of partially completed surveys
• Count of abandoned surveys
• Preview Link
• Reporting Link
• Editing Link
• JavaScript Embed Code for websites
• Response data graph

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgGetSurveyList

<apiResults apiversion="0.9" developerappversion="1.0.1">
	<status>success</status>
	<surveylist>
		<survey>
			<id>555555</id>
			<title LANGUAGE="English">can i grab a password from a login?</title>
			<date_created>2008-08-08 08:08:08</date_created>
			<date_lastactivity/>
			<survey_type>Standard Survey</survey_type>
			<status>In Design</status>
			<count_inprogress>0</count_inprogress>
			<count_complete>0</count_complete>
			<count_partial>0</count_partial>
			<count_overflow>0</count_overflow>
			<count_abandoned>0</count_abandoned>
<link_preview>
				http://www.surveygizmo.com/surveybuilder/preview_survey.php?id=555555
			</link_preview>
<link_reporting>
				http://www.surveygizmo.com/surveybuilder/form_survey_reporter.php?id=555555
			</link_reporting>
<link_edit>
				http://www.surveygizmo.com/surveybuilder/survey_overview.php?id=555555
			</link_edit>
<publish_link>http://s-igoqt-555555.sgizmo.com</publish_link>
			<js_embedingcode>
				<script src="http://www.sgizmo.com/s/survey_js2.php?id=srghrtoih48fh383dfg-555555" type="text/javascript" language="javascript" ></script>
			</js_embedingcode>
			<response_chart>
				http://www.surveygizmo.com/surveybuilder/charts/survey_response_rate.php?id=555555
			</response_chart>
		</survey>
	</surveylist>
</apiResults>

sgGetResponseList

Returns: XML record data (answers) for a particular survey. You can return a subset of information. As of version 1.5 it will only pull 500 records at a time, in descending order (most recent to oldest). Use the ‘count’ and ‘total_records’ attributes to loop through all records with multiple fetches, or use Date & Time filtering (or both!)

Fields:

• sid (Survey ID)
• start (optional, will pull up to 500 records from this offset, default is 0)
• status (optional: complete, partial or abandoned. Default is complete)
• fulldata [=true] – Optional, will return the full data for all responses, not just the response header list.
  Note: This will restrict the number of records returned to 100 rather than 500.
  • questions (available only when fulldata=true is used) – Can be provided with a single Question ID (sku) or a comma separated list of question IDs (sku) and it will only return those questions in the query.
    e.g. fulldata=true&questions=1,2,3
• DateRange (optional: it will return records within a specific date range format: YYYY-MM-DD:YYYY-MM-DD
  Note: If you do not specify a time, it will default to 23:59:59. To specify a time, use the format: YYYY-MM-DD HH:MM:SS|YYYY-MM-DD HH:MM:SS

Each row of the returned data consists of the following information

• Response ID
• IP Address
• Language Code
• Geo-Location (Country, Region, City) of Respondent
• Tracking Code (Query Token)
• Status (Submitted, Saved, or Abandoned)
• Date & Time

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgGetResponseList&fulldata=true&sid=555555

<apiResults apiversion="0.9" developerappversion="1.0.1" responsetime="0.0059189796447754">
	<status>success</status>
	<responselist  started_at="0" count="500" total_records="32011">
		<response>
			<responseid>5555555</responseid>
			<date>2008-08-08 08:08:08</date>
			<status>Abandoned</status>
			<ip>81.146.21.23</ip>
			<geo_country>United States</geo_country>
			<geo_region>Colorado</geo_region>
			<geo_city>Broomfield</geo_city>
			<geo_postal/>
			<geo_long>-155.0809</geo_long>
			<geo_lat>86.9147</geo_lat>
			<referer/>
			<language>en-us</language>
			<query_string/>
			<comments/>
			<sgGUID/>
                        <questions>[SURVEY DATA FOR THIS RESPONSE]</questions>
		</response>
	</responselist>
</apiResults>

sgGetResponse

Returns: an xml document that contains the answers for a specific survey response.
The data is returned in question:answer pairs.

Fields:

• sid (survey id) (required)
• sgRID (response id)

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgGetResponse&sid=555555&sgrid=5555555

<apiResults apiversion="0.9" developerappversion="1.0.1" responsetime="0.029428005218506">
	<status>success</status>
	<response>
		<ResponseID/>
		<questions>
			<question sku="2" page="1" type="CHECKBOX" >
 
				<responses>
					<response option_id="2" >Vanilla</response>
					<response option_id="7" >Strawberry</response>
				</responses>
			</question>
			<question sku="7" type="TEXTBOX" page="1" shortname="">
 
				<responses>
					<response option="">blah</response>
				</responses>
			</question>
			<question sku="5" type="INSTRUCTIONS" page="2" shortname="">
 
				<responses>
					<response option=""> </response>
				</responses>
			</question>
		</questions>
	</response>
</apiResults>

sgGetSurvey

Returns: the xml schema of the survey, plus aggregate data.
Your application can use this function to return the schema of the survey, complete with response counts for each question. Use this function if your application needs to know the layout of the survey, or needs to change if a survey changes.

Fields:

• sid (SurveyID)
• DateRange (optional: it will return records within a specific date range format: YYYY-MM-DD:YYYY-MM-DD

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgGetSurvey&sid=555555

<apiResults apiversion="0.9" developerappversion="1.0.1">
	<status>success</status>
	<surveydata>
		<id>555555</id>
 
		<date_created>2008-08-08 08:08:08</date_created>
		<date_lastactivity>2008-08-08 08:08:08</date_lastactivity>
		<survey_type>Standard Survey</survey_type>
		<status>Launched</status>
<pages>
<page>
 
				<description></description>
				<sku>1</sku>
				<questions>
					<question sku="2" type="CHECKBOX" required="false" orientation="VERT">
 
						<options>
							<option value="O2" responsecount="1"> Vanilla</option>
							<option value="O1" responsecount="0"> Chocolate</option>
							<option value="O3" responsecount="0"> RockyRoad</option>
							<option value="O7" responsecount="1"> Strawberry </option>
						</options>
					</question>
					<question sku="7" type="TEXTBOX" required="false">
 
						<options/>
					</question>
				</questions>
			</page>
<page>
 
				<description></description>
				<sku>1</sku>
				<questions>
					<question sku="5" type="INSTRUCTIONS" required="false">
 
						<options/>
					</question>
				</questions>
			</page>
		</pages>
	</surveydata>
</apiResults>

sgSubmitSurveyResponse

This api call submits a survey response to SurveyGizmo as if a respondent has filled out a survey online. Common uses for this call are for Flash-based Survey publishing.
Returns: returns success/failure in the ’status’ element.

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgSubmitSurveyResponse&sid=555555&values=2:Vanilla;Strawberry|7:blah

<apiResults apiversion="0.95" developerappversion="1.0">
<status responseid="30509497">success</status>
</apiResults>

Fields:

• sid (survey id)
• values (an encoded string of responses and question ids)
  The ‘values’ query string variable must be passed in the following format (Question/Value pairs are separated by pipe symbols):

  values=questionid:answervalue|questionid:answervalue

  For Multi-Answer questions a semicolon separates options.

  values=questionid:optionanswer1;optionanswer2;optionanswer3

  Multi-word response values should be URI encoded per RFC 3986

  value=First%20Last

sgCopySurvey (Not available at free level)

This API call clones an existing survey in your surveygizmo account changing key text.
Returns: returns success/failure in the ’status’ element, and the meta sata (including links) to your new survey

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgCopySurvey&title=New+Test+Survey&sid=13221

<apiResults apiversion="0.95" developerappversion="1.0.1">
<status>success</status>
<survey>
<id>15811</id>
<title LANGUAGE="English">New Test Survey</title>
<user_created>0</user_created>
<user_email/>
<team>1</team>
<date_created>2009-06-29 15:39:53</date_created>
<date_lastactivity/>
<survey_type>Standard Survey</survey_type>
<status>Launched</status>
<count_inprogress>0</count_inprogress>
<count_complete>0</count_complete>
<count_partial>0</count_partial>
<count_overflow>0</count_overflow>
<count_abandoned>0</count_abandoned>
<link_preview>
http://app.sgizmo.com/surveybuilder/preview_survey.php?id=15811
</link_preview>
<link_reporting>
http://app.sgizmo.com/surveybuilder/form_survey_reporter.php?id=15811
</link_reporting>
<link_edit>
http://app.sgizmo.com/surveybuilder/survey_overview.php?id=15811
</link_edit>
<publish_link>http://s-9s0o8-151811.sgizmo.com</publish_link>
<js_embedingcode>
<script src="http://www.sgizmo.com/s/survey_js2.php?id=9s0o8vtybjeafb53ngef67ae9-15811" type="text/javascript" language="javascript" ></script>
</js_embedingcode>
<response_chart>
http://app.sgizmo.com/surveybuilder/charts/survey_response_rate.php?id=151811
</response_chart>
</survey>
</apiResults>

Fields:

• sid (the surveyid to copy)
• title (survey title)
• status (optional, The status of the new survey ‘In Design’,'Closed’, or ‘Launched’ — defaults to Launched)
• closeon (optional, the date the survey should auto-close)
• team (optional, the team that should own this survey)
• template (optional, the ID of the custom Look’n Feel templatefor the survey)

sgAddContact (Personal+)

This API call adds or updates (“upserts”) a contact (email and contact information, + five custom fields) to an email invitation in SurveyGizmo, but does not send an email to them automatically. This call automatically de-dupes against existing contacts and contacts already added to the email invitation.
Returns: returns success/failure in the ’status’ element, a message and the contact id

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgAddContact&email=test@sgizmo.com&inviteid=11111

<apiResults apiversion="0.95" developerappversion="1.0">
<status>success</status>
<msg>Contact Upserted</msg>
<contactid>276435176345</contactid>
</apiResults>

Fields:

• inviteid (the invitation to attach the contact to (iid in the invite editing screen url)
• email (the email address to add)
• fname (optional)
• lname (optional)
• org (optional)
• phone (optional)
• addr (optional)
• city (optional)
• state (optional)
• postal (optional)
• country (optional)
• c1 (optional)
• c2 (optional)
• c3 (optional)
• c4 (optional)
• c5 (optional)

sgSingleSend (Personal+)

This API call adds or updates (“upserts”) a contact (email and contact information, + five custom fields) to an email invitation in SurveyGizmo and triggers the initial invitation email. Reminders and Thank You emails can be sent to them normally after this. Note: This call automatically de-dupes against existing contacts and contacts already added to the email invitation as well as does not add them if they are marked as ‘unsubscribed’ within the account.
Returns: returns success/failure in the ’status’ element, a message and the contact id

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgAddContact&email=test@sgizmo.com&inviteid11111

<apiResults apiversion="0.95" developerappversion="1.0">
<status>success</status>
<msg>Contact Upserted, Email Sent</msg>
<contactid>276435176345</contactid>
</apiResults>

Fields:

• inviteid (the invitation to attach the contact to (iid in the invite editing screen url)
• email (the email address to add)
• fname (optional)
• lname (optional)
• org (optional)
• phone (optional)
• addr (optional)
• city (optional)
• state (optional)
• postal (optional)
• country (optional)
• c1 (optional)
• c2 (optional)
• c3 (optional)
• c4 (optional)
• c5 (optional)

sgCreateSurvey (Enterprise+)

This API call creates a survey in your account – it’s limited to basic question types: (Instructions, Textbox, Radio, Checkbox, Essay, Multi-Textbox, Menu and Hidden question types). The call also requires activation for your API key.
Returns: returns success/failure in the ’status’ element, and the ID of the survey created

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgCreateSurvey&title=Test+Survey&surveyxml=<survey><page><question type="radio"><title>What+is+your+favorite+color?</title><options><option>Option+1</option><option>Option+2</option><option>Option+3</option></options></question></page><page><question type="instruction"><title>Thank+you+for+your+response</title></question></page></survey>

<apiResults apiversion="0.95" developerappversion="1.0">
<status>success</status>
<survey id="177633">
<link>http://s-177633-w2w3g.sgizmo.com</link>
</survey>
</apiResults>

Fields:

• title (survey title, POST data is accepted for this parameter)
• team (the team # the survey belongs top, POST data is accepted for this parameter)
• template (optional, the ID of the custom Look’n Feel templatefor the survey)
• surveyxml (surveyXML to describe the survey, POST data is accepted for this parameter)

sgSetSurveyStatus (Enterprise+)

This api call launches and closes a survey.
Returns: returns success/failure in the ’status’ element, and the link of the survey modified

Example:

https://api.sgizmo.com/?dk=asdfiuh48y23h4fhvo43&uk=fg5tfwtr52*65&cmd=sgCreateSurvey&sid=14552&status=Closed

<apiResults apiversion="0.95" developerappversion="1.0">
<status link="http://s-14552-f263g.sgizmo.com">success</status>
</apiResults>

Fields:

• sid (survey id)
• status (‘Closed’,'Launched’)

Sample PHP Code

We’ve put together some sample PHP code to help you get started. Recently updated to v1.5 and to be more inline with PHP 5.3 syntax and API v1.5. Click here to download it.

Questions about the API? Post them in the forum.