Our API is designed so that users can integrate SurveyGizmo’s features and campaign capabilities into their own applications (intranets, CMS, WordPress Blogs, etc) or create standalone applications such as widgets . It was specifically written for blog software authors and email service providers who want to offer top-notch surveys to their own customers from within their own application.

In order to create your own implementations using the API, you must contact SurveyGizmo support (support@sgizmo.com) to request a developer key so your app can access it. Your implementation will need to use this key in combination with a user’s personal key to gain access. You’ll also need to agree to our simple API Terms of Use. All that SurveyGizmo users will need to do to use your app is allow their account to be API accessible by activating it on their account page. In many cases, we can work with you to make this a seamless process.

What can I do with the SurveyGizmo API?

This is a beta version of the full API. The features are currently limited, but still advanced enough to do a lot:

1. Get a survey’s title, id, last response time stamp, and publishing status.
2. List surveys by publishing status – complete with # of responses (complete and partial), abandons, and surveys currently in progress.
3. Offer direct links to preview, reporting, and editing for each survey.
4. Embed the survey directly into articles, blog posts or web pages through our Javascript publishing option.
5. Register a campaign with SurveyGizmo’s tracking module so it can tell your application who on your customers mailing list has taken the survey, abandoned it, or never clicked through.

Calling the API

In a nutshell, the API is called through a URL with properly formatted parameters and returns the data formatted as XML.

Note: You must communicate to the API in SSL (HTTPS).

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 API Key (dk) – Your developer key specific to your project. Provided free of charge by SurveyGizmo customer support.

User API Key (uk) – The user’s personal key to access their data. We recommend users keep this as private as a password. Your implementation will either need to accept the User API key from the user or query our getRegistrationLink command. The user key always contains an * as the 3rd character.

Command (cmd) – the action you would like to take (see below)

Sample: https://app.sgizmo.com/http_api/plugin.php?dk=h5g37dyg6t6edrog286vaktw&uk=xs03csfj4*12&cmd=GETSURVEYLIST&status=Abandoned

If things go wrong

The API will return the word “Error” followed by an error message if something goes wrong with a request.

Questions about the API? Post them in the forum.

Using PHP? Download PHP sample code here.

Commands

getSurveyList

Returns: an XML list of surveys as well as the links to edit, preview, and reporting.

The file contains the following fields in order:

• Survey ID
• 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

This command also accepts a field called “status,” which can be any status shown above.

getResponseList

Returns: returns an xml document that lists responses for a survey

Each record of the return value consists of the following information

• ID
• Date
• IP
• Referer
• Status
• Language
• Query String
• sgGUID

Fields:

• sid (survey id)
• status (optional, it will return responses (Partial, Complete, Abandoned)
• DateRange (optional, it will return records within a specific date range format: YYYY-MM-DD:YYYY-MM-DD

getResponse

Returns: returns an xml document that contains the answers for a specific survey response.

The data is returned in question:answer pairs.

Like this -
<question sku=”234″ page=”3″ type=”CHECKBOX” >
<title>Which of the following ice creams do you like?</title>
<responses>
<response option_id=”2″ >Yes, I like Vanilla Ice Cream</response>
<response option_id=”7″ >Yes, I like Strawberry Ice Cream</response>
</responses>
</question>

Fields:

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

getRegistrationLink (in development, ask us about it!)

Returns: Customer Key, HTTP Link

This command doesn’t take any special variables. It returns a customized link that you can present to your customer. The link shows both our logo and yours. Plus, it prompts the customer to either create an account or to login and authorize the use of your service on an existing account.

Example Return Value: a23b8-61gh3-625, http://www.surveygizmo.com/register3rdparty.php?ident=G765LN

checkIsUserRegistered (in development, ask us about it!)

Returns: “TRUE” or “FALSE”

This command checks to see if a particular customer has already activated your service with their account

Fields: No Addition Parameters

registerCampaign (in development, ask us about it!)

Returns: campaign ID, Link Format

This function activates campaign tracking within SurveyGizmo and returns a formatted URL that your application can use when emailing personalized messages. SurveyGizmo will track who starts or abandons the survey from your message. That information can be obtained by calling getEmailCampaignRecords function.

The link you get back will look like this:

http://s-1562.sgizmo.com/?c237=

Your system should add a subscriber or email identifier after the equal sign for each email message. SurveyGizmo will track responses to a campaign so that you can email reminders to people who do not complete the survey.

Fields:

• sid - SurveyID
• cname - Campaign Name (for reporting, 125 char max)

getCampaignStatus (in development, ask us about it!)

Returns: CSV results of your campaign

This function returns summary information about the survey campaign your customer is running. It returns the following information in a single csv line:

• SurveyID
• Campaign Name
• Number of Abandoned
• Number of In Progress
• Number of Completed
• Number of Partial/Saved

Fields:• Cmp (campaign id)

getCampaignRecords (in development, ask us about it!)

Returns: csv records tracking IDs for subscribers who responded to the email campaign

Your application can use this function to return a list of tracking identifiers for a campaign. Through the process of elimination, your application can tell who did not respond at all, along with the identities of the people who abandoned the survey.

Each row of the return value consists of the following information

• Tracking Code
• Status
• Date & Time

Fields:

• Cmp (campaign id)
• Status (optional, it will return records with a specific status)
• DateRange (optional, it will return records within a specific date range format: YYYY-MM-DD:YYYY-MM-DD

getSurvey

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:

• SurveyID
• Optional Query String
• Optional Date & Time Range

submitSurveyResponse

This api call submits a survey response to SurveyGizmo as if a respondent has filled out a survey online. Common uses for this call is for Flash-based Survey publishing.

Returns: returns success/failure in the ’status’ element.

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:

values=questionid:answervalue[|][id:value]

Question/Value pairs are separated by pipe symbols.

Questions about the API? Post them in the forum.