Developer API Documentation

Before you can get started with the FluidSurveys Developer API, you will need an API key.

Feel free to contact us at info@fluidsurveys.com to acquire one.

Usage

All calls to the developer API will be done so through http://fluidsurveys.com/api/surveys/?key=[Your API Key]

You can also provide a "lang" paramater that will translate strings as required to the culture code provided. eg: http://fluidsurveys.com/api/surveys/?key=[Your API Key]&lang=fr will translate all translatable strings to French.

This API also accepts a "format" paramater which can either be "xml" or "json". Result formats will default to XML.

You should also note that values will be wrapped in CDATA where appropriate. This will occur when generating fields that can contain HTML.

Methods
getSurveyList
Description: Returns information about all surveys a user has created.
Usage: http://fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=getSurveyList

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="user" param="1">
	<surveys>
		<survey id="3">
			<name>My Survey</name>
			<title>My survey's title</title>
			<description>My survey's description</description>
			<publishURL>http://fluidsurveys.com/surveys/me/my-survey/</publishURL>
			<publishLink><a href="http://fluidsurveys.com/surveys/me/my-survey/">My Survey</a></publishLink>
		<survey>
			
		<survey id="7">
			<name>Another Survey</name>
			<title>Another survey's title</title>
			<description>Another survey's description</description>
			<publishURL>http://fluidsurveys.com/surveys/me/another-survey/</publishURL>
			<publishLink><a href="http://fluidsurveys.com/surveys/me/another-survey/">My Survey</a></publishLink>			
		<survey>
	</surveys>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	surveys: [{
		'id': 3,
		'name': 'My Survey',
		'title': 'My survey\'s title'
		'description': 'My survey\'s description'
		'publish_url': "http://fluidsurveys.com/surveys/me/my-survey/"
	}, {
		'id': 7,
		'name': 'Another Survey',
		'title': 'Another survey\'s title'
		'description': 'Another survey\'s description'
		'publish_url': "http://fluidsurveys.com/surveys/me/my-survey/"
	}]
}
getSurvey
Description: Returns information about a survey.
Usage: http://fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=getSurvey

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="survey" param="68">
	<survey id="68">
		<name>My Survey</name>
		<title>My survey's title</title>
		<description>My survey's description</description>
		<creator>
			<name>
				My Name
			</name>
			<email>
				my@email.com
			</email>
		</creator>
		<publishURL>http://fluidsurveys.com/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://fluidsurveys.com/surveys/me/my-survey/">My Survey</a></publishLink>
		<numberOfPages>1</numberOfPages>
		<numberOfQuestions>1</numberOfQuestions>
		<numberOfResponses>1</numberOfResponses>
		<completion>%50</completion>
		<live>True</live>
		<pages>
			<page>
				<question>
					<title>Isn't this fun?</title>
					<description></description>
					<type>boolean-choice</type>
					<id>DF754DFG</id>
				</question>
			</page>
		</pages>
	</survey>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	'survey_id': 68,
	'survey': {
		'name': 'My Surveys',
		'title': 'My surveys\'s title',
		'description': 'My surveys\'s description',,
		'num_pages': 1,
		'creator_name': 'My Name',
		'creator_email': 'my@email.com',
		'completion': 50,
		'live': "True",
		'num_responses': 1,
		'num_questions': 1,
		'publish_url': 'http://fluidsurveys.com/surveys/me/my-survey/',				
		'pages': [{
			'questions': [{
				'title': 'Isn\'t this fun?',
				'description': '',
				'type': 'boolean-choice',
				'id': DF754DFG
			}]
		}]
	}
}
getResponseList
Description: Returns a list of responses to a survey.
Usage: http://fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=getResponseList

Note that 'group' represents all responses collecting within one survey-taking session.

Return format (XML): 
<?xml version="1.0" encoding='UTF-8'?>
<fsAPIResults query="survey" param="68">
	<survey id="68">
		<name>My Survey</name>
		<title>My survey's title</title>
		<description>My survey's description</description>
		<publishURL>http://fluidsurveys.com/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://fluidsurveys.com/surveys/me/my-survey/">My Survey</a></publishLink>
		<sessions>
			<group>
				<completed>false</completed>
				<completionTime></completionTime>
				<IPAddress>127.0.0.1</IPAddress>
				<language>en</language>
				<referrer>http://fluidsurveys.com</referrer>
				<responses>
					<response>
						Yes!
					</response>
				<responses>
			</group>
			
			<group>
				<completed>false</completed>
				<completionTime></completionTime>
				<IPAddress>127.0.0.1</IPAddress>
				<language>en</language>
				<referrer>http://fluidsurveys.com</referrer>
				<responses>
					<response>
						Not at all.
					</response>
				<responses>
			</group>
		</sessions>
	</survey>
</fsAPIResults>
Return format (JSON): 
'fsApiResult': {
	'survey_id': 68,
	'survey' : {
		'name': 'My Survey',
		'title': 'My survey\'s title',
		'description': 'My survey\s description',
		'publish_url': 'http://fluidsurveys.com/surveys/me/my-survey/',
		'responses': [{
			'completed': 'false',
			'completion_time': '',
			'ip_address': '127.0.0.1',
			'language': 'en',
			'referrer': 'http://fluidsurveys.com',
			'group': [{
				'response': 'Not at all'
			}]
		}]
	}
}
Logging In

You can use the API to log into our system and create user accounts on the fly (account creation is only available to priviledged API keys).

To do so, create a form similar to the following: 

<form action="http://fluidsurveys.com/api/login/" method="POST">
	<div>
		<label>Username: <input type="text" name="username" /></label>
	</div>
	<div>
		<label>Email: <input type="text" name="email" /></label>
	</div>
	<div>
		<label>Password: <input type="password" name="password" /></label>
	</div>
	<div>
		<label>Group: <input type="text" name="group" /></label>
	</div>
	
	<input type="hidden" name="key" value="[Your developer key]" />;	

	<div>
		<input type="submit" value="OK" />
	</div>
</form>

When done through AJAX, the following will be returned:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults query="authenticate" param="my-user-name">
	<success>
		true
	</success>
</chideAPIResults>
JSON 
'fsApiResult': {		
	'success': 'true',
	'user': 'my-username'
}

If the user was found in our system, they will be logged in and redirected to their account. If the user was not found, an account will be created.

Note that the group field is optional. If it is provided, the user will be added to a group of the given name (this group will be created if it does not yet exist).

createSurvey
Description: Create a new survey.
Usage: http://fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&&action=createSurvey

POST format (must be JSON): 
survey: {
	name: "My Survey",
	title: "My Survey",
	description: "This is my survey",
	pages: [{
		questions: [{
			title: "A question",
			description: "",
			type: "single-choice",
			choices: ["Yes", "No"] 
		}, {
			title: "Another question",
			type: "text-response"
		}]

	}, {
		questions: [{
			title: "A checkbox question",
			description: "",
			type: "multiple-choice",
			choices: ["Yes", "No"]
		}]
	}]
}

That should return something like this:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults query="userid" param="56">
	<success>
		true
	</success>
	<survey id="101" />
</chideAPIResults>
JSON 
'fsApiResult': {								
	'success': 'true',
	'survey': 68
}
Questions?

If you have any problems or questions about this API, feel free to send them to support@fluidsurveys.com