SurveyGizmo Integration Guide v1.

The SurveyGizmo API comes in several flavors: SOAP, REST and JSON. Using any one of
these three options provides you with everything you need to access your surveys, responses, re-
ports, contacts, invites and account. Pretty incredible, huh?

So here is the basic rundown of the SurveyGizmo API.

1. The API is free and available for all account levels.

2. If you can do something in the application, you can likely do it through the API
3. SurveyGizmo API usage is monitored -- so make sure you read our API Acceptable Uses
Policy.

API Basics

All the 'flavors' of the SurveyGizmo API follow use the same model for interacting with the ap-
plication.

The first step in any API session is to authenticate a 'session'. This is done with the login com-
mand. This returns an authentication string you can use over the course of many requests. A
session with the SurveyGizmo API lasts 10 minutes from the last API request made.

What you do next is, well, up to you. Remember, you can do almost anything with the API. So
use your powers for good, use them wisely -- and have fun!

SOAP

The SOAP version of the API allows you to easily connect to SurveyGizmo over a secure con-
nection. If you have support for a SOAP client on your development platform then this one of
the quickest options to get up and running with SurveyGizmo.

First off, you need the SurveyGizmo WSDL.

This can be downloaded from -- https://app.sgizmo.com/webservice/sg_wsdl.wsdl

<sample code>

$wsdl = SoapClient("sg_wsdl.wsdl");
$proxy = $wsdl->getProxy();

$result = $proxy->login($username,$password,$apikey);
if($result->Status == false)
{
die("Grrr. Couldn't Login. Message:" .$result->Reason );
}
echo "Login successful -- begin conquering the world!";
</sample code>

That's all that's needed for bare-minimum integration. Of course it doesn't do anything other
than authenticate (btw: if you fail to authenticate more than 'x' number of times the user account
will be disabled and we'll send the user an email).

Before you go off an get all fancy we should discuss the SOAP-API basic objects.

Every function call to SurveyGizmo is going to return an SGResults object. This is a wrapper
that basically tells you if everything went as planned, or if it went to pot. As you can see in the
example above, the 'Status' function will be 'true' (boolean) if the API call completed with out
errors. If there is an Error you can access the 'ErrorCode' and 'Reason' member variables to get
details about your mistake... I mean "the problem".

If everything goes well (or at least as expected) then any objects returned by the function call
will be in the 'Results' member variable. If your call returns more than one record the Results
will be an array and there will also be a ResultCount > 1.

SurveyGizmo objects all share two common member variables. You can count on these variables
to describe the objects you request (and to create new ones). These are _type and _id. _type tells
you which type of SurveyGizmo object you are dealing with. Here are the all the SurveyGizmo
question types:

Account - Your account with SurveyGizmo

User - A user in your account
Survey - This is a survey object. It contains a collection of Page objects
SurveyPage - A survey page. It contains a collection of Question/Actions
Theme - A survey theme
LibraryTheme - A survey theme that's part of the global library
File - An uploaded file (image, etc)
Contact - A contact from your address book
Invite - An email invite campaign or follow up message
List - A Panel/List from your contact manager
SurveyLink - A customized surveyclink
Response - A response to a survey (all the answers collected for a person)
Report - A SurveyGizmo report
 Chart - A chart of response data
Feed - A survey feed
SGObject - A general object for non-standard or calculated responses.
QueryResult - The result of a query made to the API

Okay, next I suppose you want to 'do something'. Well, now it's time for you to pick a function.
The functions are listed below:

AccountDetails()

Parameters: None.
Returns: Account object

This function returns an Account object. This object contains all the details about your ac-
count in SurveyGizmo.

ObjectDetails(typename)

Parameters: object type (string)

Returns: SGObject

This function returns an SGObject with that describes a SurveyGizmo object in greater de-
tail. The Fields array contains subobjects describing each member of the object requested.
The Actions array contains a list of any actions that are available for the object.

Example:

$return = $proxy->ObjectDetails("Account");

/* list fields */
echo "Object Name:" . $return->Result->ObjectName;
echo "Object Properties:\n";

foreach ($return->Result->Fields as $field)

{
echo "Field: {$field->Name}, Required: {$field->Required}";
}

Create(object)

Parameters: object to be created

Result: SGObject with the ID of the newly created object
This is the function you call when you want to create an object in SurveyGizmo. From Sur-
veys, Questions in a survey, etc.

An obvious question with this function is 'how the !$#@$ do I create nested objects' after
all, surveys contains pages and pages contain questions. The answer is pretty straight for-
ward: nested objects contain the ID of their parent. That's how the initial relationship is
formed.

Tip: Make sure you set the _type member of the object you are passing. That's how Survey-
Gizmo knows which type of object to create!

Example:

$obj = new stdClass();

$obj->_type = "User";
$obj->UserName = "John Smith";
$obj->EmailAddress = "johnsmith@acmeco.com";
$obj->Password = "jehehehehehehe";
$obj->Team = 1;
$obj->Permissions = array("Administrator" => true);

$result = $proxy->create($obj);

Update (object)

Parameters: object -- the object to update

The update function allows you to update an object (and optionally any nested objects).
Simple update the object instance, then pass it back to the function. Be careful not to re-
move the _type or _id fields -- as they are used to identify the records.

Sample Code:

$result = $proxy->fetch("User",$id);

if($result->resultOK)
{

$User = $result->result;
$User->UserName = "Christian Vanek";
 $result = $proxy->update($User);
}

Fetch (objecttype,id)

Parameters: objecttype (String) - the type of object you are fetching

id (string) - the id of the object to fetch.

The fetch command looks up and returns a single object from the account. This is the
smplest form of lookup -- but you need to know both the object type and the ID.

See 'Update' for sample usage.

Query (fields,objecttype[,whereclause][,orderby][,returncount][,startat])

Parameters:
fields (String) this is a comma-separated list of fields you want returned
objecttpe (string) the type of object you are searching for
whereclause (string) a SQL like criteria statement for the results
orderby (string) which fields and in which order to return results
returncount (int) how many items to return at once (default 10)
startat (int) the starting offset in the set for returncount number of results
Returns: QueryResult object

The query function allows you to search for objects in your account that you do not know
the ID for. It works very similar to a SQL SELECT statement, in fact the where clause sup-
ports most SQL statement conditions including nested conditions and pattern matching.

Sample Code:
 $response = $proxy->query(“*”,”Survey”,”Status = ‘Launched’ and (PublicTitle LIKE
‘%Demo%’ or PublicTitle LIKE ‘%Testing%’)”,”DatePublished DESC”,10);

if($response->resultOK)
{
$queryresult = $response->result;

$total_matching_surveys = $queryresult->size;
$number_returned = $queryresult->count;

if($number_returned > 0)
{
foreach($queryresult->results as $survey)
{
echo $survey->PublicTitle . “<br/>”;
}
}
}

[API Acceptable Uses Policy]

You are free to use SurveyGizmo's API for non-commercial, private/internal purposes.

Prohibited Uses: You may not create a public (paid or free) application from the SurveyGizmo
API without a sub-licence from SurveyGizmo. If you are interested in a sub-licence, please con-
tact sales@surveygizmo.com a SurveyGizmo account manager will help you get started.