Developers

Integrate Surveytown into your application

Access

Welcome to the Surveytown REST API.

In order to start using the API you will first need a valid Surveytown account (sign up for a free trial or paid Surveytown account).  Once your account is created, login and create an API key by going to Settings > API Key.

Once that is done you can access the REST API via the following URL:

https://api.surveytown.com/2/REST/

Here’s an example using the Survey_Find call to find all of your currently active Surveys:

http://api.surveytown.com/2/REST/?method=Survey_Find&key=YOUR_API_KEY&optionalParameters[status]=active

NOTE: API calls that contain non-required variables, the optional parameters are added to the URL using the string “optionalParameters” with the parameter name inside the bracket [] and then it equaling a value.

Our keys are assigned to users. When you sign up for a SurveyTown account, your username is considered the first user, is permanent and has all permissions.  Other users can be assigned a subset of permissions and any API keys assigned to that user will be limited by the permission constraints of that user.  For example if a user in the application was limited to seeing just the reporting of certain surveys then any API Key created for that user would also be limited to seeing just those survey reports.

API Reference

Survey

Survey_Find()

Find surveys based on specific criteria

Survey_Get_Questions()

Retrieves the questions for a particular survey

Survey_Get_Response_Count()

Counts how many responses a survey has

Survey_Get_Responses()

Retrieve responses a specific contact has entered

Survey_Get_Responses_By_Email()

Retrieve responses a specific contact has entered

Survey_List()

Get a listing of surveys

Survey_Start()

Start a survey

Survey_Stop()

Stop a survey

Survey_Add_Tag()

Add a tag to a survey

Survey_Remove_Tag()

Remove a tag from a survey

Tag

Tag_Create()

Create a new tag

Tag_Update()

Update an existing tag

Tag_Delete()

Delete a tag

Tag_List()

Get a listing of tags

Response

Response_Create()

Create a new response

Response_Update()

Update an existing response

Response_Delete()

Delete a response

 

Webhooks

Webhooks allow you to receive real-time updates for various events that occur within your SurveyTown account.  When these events trigger, we’ll call a web-accessible URL you specify and tell you what happened.

To set up your webhooks, log into your account and go to Settings -> Webhooks.  Here you can set up the events you wish to receive alerts about and under which conditions these events were triggered. Our system will then send these webhook alerts via HTTP POST at a URL that you provide.

 

Survey Status Changed (survey_status_changed)

Fires when a surveys status has changed (started, stopped and completed)

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event survey_status_changed
updated_via The Webhook Trigger System
survey_id The ID of the survey that was changed 1
old_status The old status of the survey draft
new_status The new status of the survey active
survey_type The type of survey survey
tags The tags associated with the survey [{“tagId”:”1″,”name”:”my tag”}]
sent webhook sent date 2010-10-29 11:33:56

Survey Created (survey_created)

Fires when a survey is created.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event survey_created
updated_via The Webhook Trigger System
survey_id The ID of the survey that was changed 1
status The status of the survey draft
survey_type The type of survey survey
tags The tags associated with the survey [{“tagId”:”1″,”name”:”my tag”}]
sent webhook sent date 2010-10-29 11:33:56

Survey Deleted (survey_deleted)

Fires when a survey is deleted.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event survey_deleted
updated_via The Webhook Trigger System
survey_id The ID of the survey that was changed 1
status The status of the survey active
survey_type The type of survey survey
tags The tags associated with the survey [{“tagId”:”1″,”name”:”my tag”}]
sent webhook sent date 2010-10-29 11:33:56

Response Changed (response_changed)

Fires when a response is changed.  It will contain the answers given in a response.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event response_changed
updated_via The Webhook Trigger System
survey_id The ID of the survey that was responded to 1
response A struct containing the survey response response[isComplete]: 1

response[responseId]: 3

response[responseStart]: 2015-10-07 15:49:16

response[responseComplete]: 2015-10-07 16:55:28

response[66][questionId]: 66

response[66][questionText]: hello world

response[66][response][responseValue]: hi

response[66][isRequired]: 0

survey_type The type of survey (either: survey or event) survey
tags The tags associated with the survey [{“tagId”:”1″,”name”:”my tag”}]
sent Webhook sent date 2015-10-07 16:55:28

Response Deleted (response_deleted)

Fires when a response is deleted.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event response_deleted
updated_via The Webhook Trigger System
tag_id The ID of the tag 1
name The name of the tag my tag
sent webhook sent date 2010-10-29 11:33:56

Tag Created (tag_created)

Fires when a tag is created.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event tag_created
updated_via The Webhook Trigger System
tag_id The ID of the tag 1
name The name of the tag my tag
sent webhook sent date 2010-10-29 11:33:56

Tag Changed (tag_changed)

Fires when a tag is changed.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event tag_changed
updated_via The Webhook Trigger System
tag_id The ID of the tag 1
name The name of the tag your tag
sent webhook sent date 2010-10-29 11:33:56

Tag Deleted (tag_deleted)

Fires when a tag is deleted.

Parameter Description Example Value
id The Webhook ID 1288370036.3304
key Your Webhook key amazinglysecurekey
type The Webhook Event tag_deleted
updated_via The Webhook Trigger System
tag_id The ID of the tag 1
name The name of the tag my tag
sent webhook sent date 2010-10-29 11:33:56