Developer API Documentation

This version of the API is no longer supported.

Please see documentation for V2 of our API

Feel free to contact us at info@fluidsurveys.com

Usage

All calls to the developer API will be done so through http://app.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://app.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://app.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://app.fluidsurveys.com/surveys/me/my-survey/</publishURL>
			<publishLink><a href="http://app.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://app.fluidsurveys.com/surveys/me/another-survey/</publishURL>
			<publishLink><a href="http://app.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://app.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://app.fluidsurveys.com/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://app.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://app.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.

Optional arguments: created_at_min=[date/time] and created_at_max=[date/time] to limit responses to certain date ranges.

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://app.fluidsurveys.com/surveys/me/my-survey/</publishURL>
		<publishLink><a href="http://app.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://app.fluidsurveys.com</referrer>
				<responses question="Question 1">
					<response>
						Yes!
					</response>
				<responses>
			</group>
			
			<group>
				<completed>false</completed>
				<completionTime></completionTime>
				<IPAddress>127.0.0.1</IPAddress>
				<language>en</language>
				<referrer>http://app.fluidsurveys.com</referrer>
				<responses>
					<response question="Question 2">
						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',
				'question': 'Question 1'
			}]
		}]
	}
}
getSingleResponse
Description: Returns a single response from a survey.
Usage: http://app.fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&&response=[Response Key]&action=getSingleResponse
Return format (JSON): 
'fsApiResult': {
	'response' : {
		'_completed': false,
		'_completion_time': '',
		'_ip_address': '127.0.0.1',
		'_language': 'en',
		'_referrer': 'http://fluidsurveys.com'
	}
}
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://app.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://app.fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=createSurvey

POST format must be multipart/form-data encoded with a single parameter "survey" containing JSON-encoded data in the following format: 
{
	"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>
	<success>
		true
	</success>
	<survey id="101" />
</chideAPIResults>
JSON 
'fsApiResult': {								
	'success': 'true',
	'survey': 68
}
createResponse
Description: Create a new response to a survey.
Usage: http://app.fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&action=createResponse

POST format: 
survey: <survey identifier>

That should return something like this:

XML 
			
<?xml version="1.0" encoding='UTF-8'?>
<chideAPIResults query="userid" param="56">
	<response key="key" url="http://..." />
</chideAPIResults>
JSON 
'fsApiResult': {								
	'key': 'key',
	'url': 'http://...'
}
exportToCSV
Returns the survey's dataset as CSV.
Usage: http://app.fluidsurveys.com/api/surveys/?key=[Your API Key]&uk=[Your API User Key]&survey=[Survey ID]&action=exportToCSV
Optional parameters:
split_csv=true|false
score_based=true|false
include_labels=true|false
show_titles=true|false
escape_newline=true|false
Questions?

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