Professional Documents
Culture Documents
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?
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.
<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:
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)
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";
Create(object)
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:
$result = $proxy->create($obj);
Update (object)
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)
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.
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/>”;
}
}
}
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.