Introduction

EngagementHQ (EHQ) provides online citizen engagement tools. The application provides a white labelled website, for each client within which a client may create one or more online consultations (projects) which can contain one or more tools, widgets and other resources. Each client site has its own URL and works in a self contained manner.

The EHQ API is REST based and user JSON for serialisation and Basic Authentication over SSL for authentication and encrypted communication. The access credentials of any admin user in the EHQ site in question can be used to access the API. Non - admin access is at present not available.

The API URL

The base URL for the API is the base URL of the site.

The full path of the API call would be as follows

http://
Base domain of the site
The API version number - v1
The action
.json extension

An example API, say to request a list of projects would look like this -

https://example.com/v1/projects.json

Each call would throw a basic authentication challenge and would require that the user name and password of an administrator user of the site be passed in.

Using CURL our example request would look like -

curl -u <admin username>:<password> https://example.com/v1/projects.json

Users

A user is anyone that has participated on our site.

Get all users

GET /users.json will return a list of all the users of the site.

curl -u myadmin_login:mypassword "https://example.com/v1/users.json"

The above command returns JSON structured like this:

{
  "users":
  [
    {
      "id": 1,
      "login": "user1",
      "email": "user1@example.com"
    },
    {
      "id": 247,
      "login": "user2",
      "email": "user2@example.com"
    }
  ]
}

Get details of a specific user

GET /users/<id>.json will return the details of a specific user.

curl -u <admin username>:<password> https://example.com/v1/users/1.json

The above command returns JSON structured like this:

{
  "user": {
    "address": {
      "optional": false,
      "deleted": false,
      "value": "Sydney, NSW, Australia",
      "hidden": false
    },
    "joined": "2010/02/08 16:39:59 +1100",
    "suburb": {
      "optional": false,
      "deleted": false,
      "value": null,
      "hidden": false
    },
    "role": "client",
    "blocked": null,
    "id": 1,
    "last_visit": "2012/09/27 14:27:41 +1000",
    "activated": true,
    "login": {
      "optional": false,
      "deleted": false,
      "value": "user1",
      "hidden": false
    },
    "email": {
      "optional": false,
      "deleted": false,
      "value": "user1@example.com",
      "hidden": false
    }
  }
}

Get a users profile

GET /users/<id>/profile.json will return the profile details of a specific user.

curl -u <admin username>:<password> https://example.com/v1/users/1/profile.json

The above command returns JSON structured like this:

{
  "user_profile":{
    "user_id":1,
    "created_at":"2014-11-20T00:21:48+11:00",
    "updated_at":"2014-11-28T14:59:55+11:00",
    "response":[{
      "answer":"Hello world",
      "question_id":7
    }]
  }
}

Our platform supports the addition of custom fields in the registration form, that the users that sign up can fill. These fields can be hidden from showing up in the registration form, deleted or made optional - these settings for the user object are returned as boolean along with the field value. If a particular field is not filled in by the user a NULL value will be displayed. Our platform supports the following user roles - admin , client, project, participant, preview_user, blocked_user

Team Members

Team members are users that have been added to a particular project in the site.

GET /team_members.json will return a list of all the team members of the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/team_members.json

{
  "team_members":
    [
        {
          "user_screen_name": "Ray Scanlan",
          "id": 86
        },
        {
          "user_screen_name": "Crispin Butteriss",
          "id": 104
        },
        {
          "user_screen_name": "Matt Crozier",
          "id": 133
        },
        {
          "user_screen_name": "Karthik Reddy",
          "id": 134
        }
    ]
}

Projects

Projects are the core building blocks of an EngagementHQ site. Typical community consultations consist of one or two projects grouped together. Projects contain the various tools and widgets configured for a particular page in the site.

Get a list of projects

GET /projects.json will return a list of all the project on the site.

curl -u <admin username>:<password> https://example.com/v1/projects.json

{
  "projects": [
    {
      "id": 1,
      "name": "Demonstration Site",
      "description": "<p>This site is being used to demonstrate EngagementHQ to clients.",
      "archived": false,
      "state": "draft",
      "published_at": "2012-05-04 19:25:32 +1100",
      "created_at": "2010-02-08 22:09:44 +1100",
      "last_updated_at": "2010-02-08 22:09:44 +1100"
    },
    {
      "id": 46,
      "name": "From Hair to Eternity",
      "description": "Your thoughts about hair and your favourite products are important to us.",
      "archived": false,
      "state": "published",
      "published_at": "2012-03-28 14:16:32 +1100",
      "created_at": "2012-07-03 10:48:09 +1100",
      "last_updated_at": "2012-07-03 14:16:32 +1100"
    }
  ]
}

Get details of a specific project

GET /projects/<id>.json will return the details of a specific projects id.

curl -u <admin username>:<password> https://example.com/v1/projects/1.json

{
  "project": {
    "name": "Demonstration Site",
    "created_at": "2010/02/08 22:09:44 +1100",
    "photos": {
    "url": "https://example.com/v1/projects/1/photos.json",
    "count": 4
  },
  "guestbook": {
    "url": "https://example.com/v1/projects/1/guestbook.json"
  },
  "surveys": {
    "url": "https://example.com/v1/projects/1/surveys.json",
    "count": 2
  },
  "videos": {
    "url": "https://example.com/v1/projects/1/videos.json",
    "count": 4
  },
  "documents": {
    "url": "https://example.com/v1/projects/1/documents.json",
    "count": 7
  },
  "qandas": {
    "url": "https://example.com/v1/projects/1/qandas.json",
    "count": 1
  },
  "topics": {
    "url": "https://example.com/v1/projects/1/topics.json",
    "count": 5,
    "forum_title": "Sample Forum"
  },
  "archived": false,
  "id": 1,
  "forms": {
    "url": "https://example.com/v1/projects/1/forms.json",
    "count": 1
  },
  "keydates": {
    "url": "https://example.com/v1/projects/1/keydates.json",
    "count": 5
  },
  "posts": {
    "url": "https://example.com/v1/projects/1/posts.json",
    "blog_title": "Site News",
    "count": 8
  },
  "faqs": {
    "url": "https://example.com/v1/projects/1/faqs.json",
    "count": 16
  },
  "published_at": null,
  "description": "<p>This site is being used to demonstrate EngagementHQ to clients. The site is populated with illustrative material and most comments and community content is invented for the purposes of illustrating the platform. It is also worth noting that we have switched on all of the functionality for the software on one page. In reality we would never recommend this because it may be completely overwhelming for the viewer.<br />Feel free to sign up and have a play with the functions of the site.</p> <p>However, if you want to trial the client functionality please email admin@bangthetable.com in order to arrange access to our full demo site.</p>",
  }
}

Topics

Topics refer to the discussion topics on the forum tool. There can be one forum tool associated to each project but each forum can have multiple discussion topics. Each discussion topic in turn can have several comments.

GET /projects/<id>/topics.json will return a list of discussion topics of a projects forum tool.

curl -u <admin username>:<password> https://example.com/v1/projects/1/topics.json

{
  "topics": [
  {
    "name": "This is a sample discussion topic.",
    "created_at": "2011/05/17 21:24:55 +1000",
    "comments": {
      "url": "https://example.com/v1/projects/1/topics/147/comments.json",
      "count": 19
    },
    "moderation_state": "ham",
    "id": 147,
    "description": "<p>EngagementHQ <a href="https://example.com/your-say-cafe?module=forum">forums</a> can be supported by text or any form of embeddable rich media - like maps, videos, slideshows or flickr shows. You pose as many questions as you like in each forum, but we generally recommend around six to concentrate the discussion. The discussion topics can be ordered to your preference. You can decide who creates new discussion topics.</p>"
  },
  {
    "name": "This is a sample discussion topic.",
    "created_at": "2011/09/29 14:03:46 +1000",
    "moderation_state": "awaiting_moderation",
    "comments": {
      "url": "https://example.com/v1/projects/1/topics/152/comments.json",
      "count": 6
    },
    "id": 152,
    "description": "<p>You can add supporting text here or embed rich content such as video, slideshows or maps. This helps to make the experience both more compelling and more accessible, encouraging more thoughtful comments, responses and dialogue.</p>
  <p> </p>"
  }
  ]
}

Get a list of comments for a topic

GET /projects/<id>/topics/<id>/comments.json will return a list of the comments for a single discussion topic.

curl -u <admin username>:<password> https://example.com/v1/projects/1/topics/147/comments.json

{
  "comments": [
  {
    "comment": "This is a sample comment.",
    "created_at": "2012/03/13 17:21:31 +1100",
    "user_screen_name": "John Citizen",
    "id": 1419,
    "user_id": 176,
    "parent_id": 1317,
    "comment_level": 2,
    "spam": false,
    "ham": true,
    "moderation_state": "ham",
    "agrees": 0,
    "replies": 0,
    "disagrees": 0
  },
  {
    "comment": "We call the EngagementHQ forums Smart Forums for a few reasons...",
    "created_at": "2011/05/19 09:46:57 +1000",
    "user_screen_name": "Crispin Butteriss",
    "id": 1317,
    "user_id": 104,
    "parent_id": 1314,
    "comment_level": 1,
    "spam": false,
    "ham": false,
    "moderation_state": "awaiting_moderation",
    "agrees": 1,
    "replies": 9,
    "disagrees": 1
  }
  ]
}

This includes the position of the comment (comment_level) and an indication of whether the comment has been approved (ham) or marked as spam or awaiting moderation

Surveys

A project can have multiple surveys. A survey consists of multiple questions. We record the responses for each survey that is submitted by a user. It is possible for a survey to allow users to respond anonymously (i.e. without having to register or login to the site). In this case responses will be associated to a system generated dummy user.

GET /projects/<id>/surveys.json will return a list of the surveys created in the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/surveys.json

{
  "surveys": [
  {
    "responses": {
      "url": "https://example.com/v1/projects/1/surveys/1/responses.json",
      "count": 0
    },
    "created_at": "2011/04/20 20:22:17 +1000",
    "questions": {
      "url": "https://example.com/v1/projects/1/surveys/1/questions.json",
      "count": 8
    },
  "title": "Survey",
  "id": 1,
  "introduction": "<p>The onsite Survey is a straightforward survey tool with a few major benefits. First, your site visitors no longer have to leave your website to fill in the survey. Secondly, the survey respondents still have access to all of the rich content available on your website so that they can be better informed when framing their responses. Thirdly, the survey branding is completely integrated with your corporate branding - no more ugly surveys!</p>"
  },
  {
    "responses": {
      "url": "https://example.com/v1/projects/1/surveys/37/responses.json",
      "count": 0
    },
    "created_at": "2012/04/20 16:10:12 +1000",
    "questions": {
      "url": "https://example.com/v1/projects/1/surveys/37/questions.json",
      "count": 1
    },
    "title": "Sample Survey 4",
    "id": 37,
    "introduction": "<p>Intro text</p>"
  }
  ]
}

Get a list of questions for a survey

GET /projects/<id>/surveys/<id>/questions.json will return a list of the questions that are part of a particular survey.

curl -u <admin username>:<password> https://example.com/v1/projects/1/surveys/1/questions.json

{
	survey_questions: [
		{
			created_at: "2010/12/14 15:51:49 +1100",
			published: true,
			deleted: false,
			id: 9,
			answer_type: "radio_buttons",
			question: "To what extent did the demo meet your needs?",
			options: [
				{
				value: "Entirely",
				id: 10
				},
				{
				value: "Mostly",
				id: 11
				},
				{
				value: "Not really",
				id: 12
				},
				{
				value: "Not at all",
				id: 13
				}
			],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:52:33 +1100",
			published: true,
			deleted: false,
			id: 10,
			answer_type: "check_boxes",
			question: "How clear was your presenter?",
			options: [
				{
				value: "Very",
				id: 14
				},
				{
				value: "Not very",
				id: 15
				},
				{
				value: "As mud",
				id: 16
				}
			],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:53:05 +1100",
			published: true,
			deleted: false,
			id: 11,
			answer_type: "number",
			question: "How many minutes did the presentation take",
			options: [ ],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:53:27 +1100",
			published: true,
			deleted: false,
			id: 12,
			answer_type: "essay",
			question: "Tell us what else you would have liked to have learned",
			options: [ ],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:53:49 +1100",
			published: true,
			deleted: false,
			id: 13,
			answer_type: "single_line",
			question: "Any other comments?",
			options: [ ],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:54:34 +1100",
			published: true,
			deleted: false,
			id: 14,
			answer_type: "date",
			question: "When was the presentation?",
			options: [ ],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:54:58 +1100",
			published: true,
			deleted: false,
			id: 15,
			answer_type: "file",
			question: "Attach a photo that describes your feelings",
			options: [ ],
			hidden: false,
			dependent: false
		},
		{
			created_at: "2010/12/14 15:55:50 +1100",
			published: true,
			deleted: false,
			id: 16,
			answer_type: "dropdown",
			question: "Choose which of these you would most like for dinner",
			options: [
				{
				value: "Peas",
				id: 17
				},
				{
				value: "Rasberry Jelly",
				id: 18
				},
				{
				value: "Cheese",
				id: 19
				},
				{
				value: "Goulash",
				id: 20
				}
			],
			hidden: false,
			dependent: false
		}
	]
}

Intelligent Questions

A survey question can be configured to show up dynamically based on user’s choice for another question.ie, you can configure a question ‘A’ to show up only if a particular option is selected/unselected for question ‘B’.

Each question in the api will have a field dependent which has a boolean value.This will be true if the question depends on any other question.In that case, there will be an extra field depends_on that has three fields

No	Field	Description
1	`question_id`	id of question ‘B’
2	`option_id`	id of option in question ‘B’
3	`show_when`	This field can have only two values - ‘selected’ or ‘unselected’.It tells when to show the question

In the sample api given below question ‘Age’ will show up only if we select option ‘Male’ for the question ‘Genre’

{

        survey_questions: [
        {
            created_at: "2013-05-30T17:29:27+10:00",
            published: true,
            deleted: false,
            id: 65,
            answer_type: "singleline",
            question: "First Name:",
            options: [ ],
            hidden: false,
            dependent: false
        },
        {
            created_at: "2013-05-30T17:30:02+10:00",
            published: true,
            deleted: false,
            id: 67,
            answer_type: "singleline",
            question: "Last name:",
            options: [ ],
            hidden: false,
            dependent: false
        },
        {
            created_at: "2013-05-30T17:33:22+10:00",
            published": true,
            deleted: false,
            id: 72,
            answer_type: "radio_buttons",
            question: "Genre",
            options: [
                {
                    value: "Male",
                    id: 22
                },
                {
                    value: "Female",
                    id: 23
                }
            ],
            hidden: false,
            dependent: false
        },
        {
            created_at: "2013-05-30T17:30:37+10:00",
            published: true,
            deleted: false,
            id": 68,
            answer_type: "singleline",
            question: "Age:",
            options: [ ],
            hidden: false,
            dependent: true,
            depends_on: {
                question_id: 72,
                option_id: 22,
                show_when: "selected"
            }
        }
 }

Questions with multiple responses options will contain an array with the id and the value for the options.

GET /projects/<id>/surveys/<id>/responses.json will return the responses submitted for a particular survey.

curl -u <admin username>:<password> https://example.com/v1/projects/<id>/surveys/<id>/responses.json

{
responses: [
	{
	user_id: 89,
	user_type: "UnverifiedUser",
	user_screen_name: "user1",
	response: [
		{
			answer: [
			10
			],
			question_id: 9
		},
		{
			answer: [
			14
			],
			question_id: 10
		},
		{
			answer: 1,
			question_id: 11
		},
		{
			answer: "I'd love a cup of tea.",
			question_id: 13
		},
		{
			answer: "How to make brownies",
			question_id: 12
		},
		{
			answer: "2010/12/14",
			question_id: 14
		},
		{
			answer: "https://example.com/survey_tool/download_file/7",
			question_id: 15
		},
		{
			answer: [
			18
			],
			question_id: 16
		}
		]
	},
	{
	user_id: 140,
	user_type: "User",
	user_screen_name: "csmillie",
	response: [
		{
			answer: [
			10
			],
			question_id: 9
		},
		{
			answer: [
			14
			],
			question_id: 10
		},
		{
			answer: null,
			question_id: 11
		},
		{
			answer: null,
			question_id: 13
		},
		{
			answer: null,
			question_id: 12
		},
		{
			answer: null,
			question_id: 14
		},
		{
			answer: null,
			question_id: 15
		},
		{
			answer: null,
			question_id: 16
		}
		]
	},
	{
	user_id: 140,
	user_type: "User",
	user_screen_name: "csmillie",
	response: [
		{
			answer: [
			10
			],
			question_id: 9
		},
		{
			answer: [
			14
			],
			question_id: 10
		},
		{
			answer: null,
			question_id: 11
		},
		{
			answer: null,
			question_id: 13
		},
		{
			answer: null,
			question_id: 12
		},
		{
			answer: null,
			question_id: 14
		},
		{
			answer: null,
			question_id: 15
		},
		{
			answer: null,
			question_id: 16
		}
		]
	}
	]
}

Responses made by anonymous users (if the survey is configured to allow anonymous users to take the survey) would be shown with the screen name as “anonymous” and the userid set as null. If the question has multiple answer options then the answer would be shown in an array.

GET /signup_form_questions.json returns a list of signup form questions

{
  "signup_form_questions":[{
    "id":44455,
	"deleted":false,
	"answer_type":"check_boxes",
	"question":"test quest",
	"options":[
	  {
	    "value":"one ",
	    "id":63235
	  },
	  {
	    "value":"two",
		"id":63236
	  },
	  {
	    "value":"three ",
		"id":63237
	  },
	  {
	    "value":"four ",
	    "id":63238
	  },
	  {
	    "value":"five",
	    "id":63239
	  }
    ],
	"created_at":"2014-12-12T19:33:40+11:00",
	"hidden":false
	}]
}

Forms

A form is similar to a Survey except that it is configured for anonymous use by default. Like a survey it consists of multiple fields and records responses of various users.

Get a list of forms in a project

GET /projects/<id>/forms.json will return a list of the forms created in the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/forms.json

{
  "forms": [
  {
    "submissions": {
      "url": "TODO: this isn't implemented correctly yet.",
      "count": 0
    },
    "created_at": "2012/02/02 22:06:18 +1100",
    "form_fields": {
      "url": "https://example.com/v1/projects/1/forms/25/form_fields.json",
      "count": 6
    },
    "title": "FormName",
    "id": 25,
    "introduction": ""
  }
  ]
}

Get a list of fields in a form

GET /projects/<id>/forms/<id>/form_fields.json will return a list of the fields configured in a particular form.

curl -u <admin username>:<password> https://example.com/v1/projects/1/forms/25/form_fields.json

{
  "form_fields": [
  {
    "created_at": "2012/02/02 22:06:18 +1100",
    "published": true,
    "id": 124,
    "question": "Address"
  },
  {
    "created_at": "2012/02/02 22:06:19 +1100",
    "published": true,
    "id": 125,
    "question": "Name"
  },
  {
    "created_at": "2012/02/02 22:06:19 +1100",
    "published": true,
    "id": 129,
    "question": "Email"
  }
  ]
}

Get a list of responses for a form

GET /projects/<id>/forms/<id>/responses.json will return the a list of the responses submitted for a particular form.

curl -u <admin username>:<password> https://example.com/v1/projects/<id>/forms/<id>/responses.json

{
 "responses":
 [
 {
		"user_screen_name": "nikhil1",
		"user_id": 162,
		"response":
 [
 {
		    "question_id": 267,
		    "answer": "This is a test"
		   },
		   {
		     "question_id": 268,
		     "answer": "https://example.com/survey_tool/download_file/251"
		   }
		 ]
	 }
 ]
}

Responses made by anonymous users would be shown with the screen name as “anonymous” and the userid set as null.

Posts

These are the posts in the blog section of a project. Posts are also known as News Articles or the News Feed. A project can have multiple posts. They are used primarily as a means of broadcasting information to the audience of the project.

GET /projects/<id>/posts.json will return a list of the news articles (posts) for a project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/posts.json

{
  "posts": [
  {
    "created_at": "2010/12/14 16:39:02 +1100",
    "title": "Smart Forums encourage intelligent dialogue and debate",
    "created_by": "admin",
    "id": 78,
    "content": "<p>The Smart Forum is generally used for projects when the communication goal includes active community discussion of the issues. We call them Smart Forums, rather than dumb forums, for lots of reasons. You can surround the forum with lots of information to give it real context; you can embed rich content right into the forums to help raise awareness about the critical issues and inform a better quality debate; you can easily follow the flow of the discussion because of the multi-threaded structure of the forum; and you easily analyse the content with the built in qualitative analysis and quantitative reporting tools.</p>",
    "image_url": "http://s3.amazonaws.com/ehq-v2-develop/4b88f9d3ffcaa89511804442d7f42af8816e6db4/themes/banners/000/000/002/banner/sad-robot-2.jpg?1493184765",
    "url": "http://dev.ehq.dev/kingdom-in-the-north/news_feed/smart-forums-encourage-intelligent-dialogue-and-debate"
  },
  {
    "created_at": "2012/02/28 15:44:16 +1100",
    "title": "News article",
    "created_by": "admin",
    "id": 192,
    "content": "<p>This is a news article</p>",
    "image_url": "http://s3.amazonaws.com/ehq-v2-develop/4b88f9d3ffcaa89511804442d7f42af8816e6db4/themes/banners/000/000/002/banner/sad-robot.jpg?1493184765",
    "url": "http://dev.ehq.dev/kingdom-in-the-north/news_feed/news-article"
  }
  ]
}

Key Dates

Key dates (sometimes called events) are a widget associated to a project. Key dates are typically used as a sort of calendar to communicate dates for various events.

GET /projects/<id>/keydates will return a list of the key dates associated to an event.

curl -u <admin username>:<password> https://example.com/v1/projects/1/keydates.json

{
  "key_dates": [
  {
    "created_at": "2011/05/17 20:09:59 +1000",
    "keydate": "2007/06/01 00:00:00 +1000",
    "id": 12,
    "description": "Bang the Table established",
    "keydate_end": null
  },
  {
    "created_at": "2011/05/17 20:11:11 +1000",
    "keydate": "2007/11/01 00:00:00 +1100",
    "id": 13,
    "description": "First online consultation launched",
    "keydate": null
  },
  {
    "created_at": "2011/05/17 20:12:17 +1000",
    "keydate": "2009/02/01 00:00:00 +1100",
    "id": 14,
    "description": "EngagementHQ brand launched",
    "keydate": null
  },
  {
    "created_at": "2011/05/17 20:13:49 +1000",
    "keydate": "2008/06/01 00:00:00 +1000",
    "id": 15,
    "description": "First "white label" site launched",
    "keydate": null
  },
  {
    "created_at": "2012/01/18 14:47:03 +1100",
    "keydate": "2012/01/04 00:00:00 +1100",
    "id": 17,
    "description": "Big Bang",
    "keydate": "2012/01/08 00:00:00 +1000",
  }
  ]
}

FAQs

Frequently Asked Questions (FAQs) are a widget associated to a project. Typically this is used as way to help the audience get up to speed regarding a particular consultation.

GET /projects/<id>/faqs.json will return the list of FAQs associated to a particular project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/faqs.json

{
  "faqs": [
  {
    "position": 0,
    "created_at": "2011/05/17 20:29:02 +1000",
    "id": 17,
    "question": "How does the moderation work?",
    "answer": "<p>Public forums on EngagementHQ are moderated by the Bang the Table moderation team on a <em>post hoc </em>basis.</p>
  <p>We read EVERY SINGLE comment that is made on one of our forums.</p>
  <p>We guarantee to moderate all comments within two hours 24 hours a day seven days a<br />week. In practice we generally review all comments within one hour. We can do<br />this because we have a team of moderators, aggregation software to allow us to<br />gather comments from all of our sites to one place, and a mobile enabled<br />moderator portal. We also have people in Perth, Vancouver and the UK help us<br />cover the clock.</p>
  <p>When we remove a comment from a site it is replaced with a statement from the<br />moderator explaining the rationale for the removal of the comment. The User is<br />automatically notified by email about the removal of the comment and the rationale<br />for its removal. They are invited to contact the moderator directly to<br />challenge the decision.</p>
  <p>We have noticed that the vast majority of users of our sites are very constructive<br />and do not require any moderation. The comments we do remove generally fall<br />into one of three categories; 1) duplicates, 2) disrespectful or hectoring, and<br />3) mild bad language. We have NEVER had to remove any comments that could be<br />considered "high impact". We believe that this is because community users are<br />aware that the site is being independently and consistently monitored and<br />moderated.</p>"
  },
  {
    "position": 15,
    "created_at": "2011/09/28 09:32:55 +1000",
    "id": 32,
    "question": "How does this work?",
    "answer": "<p>It's really easy.</p>"
  }
  ]
}

Photos

Photos are a widget that allows clients to upload a set of images for a project. This is then displayed in the project page for user to browse through.

GET /projects/<id>/photos.json will return the list of photos associated to a particular project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/photos.json

{
    photos: [
        {
            id: 24,
            caption: 'Crispin',
            filename: 'Crispin.jpg',
            url: 'http://s3.amazonaws.com/ehq-v2-develop/photos/images/000/000/024/original/Crispin.jpg?1369634028',
            size: 38257,
            content_type: 'image/jpeg',
            created_at: '2013-05-27T15:53:56+10:00'
        },
        {
            id: 25,
            caption: 'Matt',
            filename: 'Matt.jpg',
            url: 'http://s3.amazonaws.com/ehq-v2-develop/photos/images/000/000/025/original/Matt.jpg?1369634030',
            size: 40382,
            content_type: 'image/jpeg',
            created_at: '2013-05-27T15:53:57+10:00'
        },
        {
            id: 26,
            caption: 'Karthik',
            filename: 'Karthik.jpg',
            url: 'http://s3.amazonaws.com/ehq-v2-develop/photos/images/000/000/026/original/Karthik.jpg?1369634029',
            size: 41331,
            content_type: 'image/jpeg',
            created_at: '2013-05-27T15:53:57+10:00'
        },
        {
            id: 30,
            caption: 'Hear from Your Community',
            filename: 'GettyImages_94897548.jpg',
            url: 'http://s3.amazonaws.com/ehq-v2-develop/photos/images/000/000/030/original/GettyImages_94897548.jpg?1369635151',
            size: 544028,
            content_type: 'image/jpeg',
            created_at: '2013-05-27T16:12:36+10:00'
        }
        ]
}

Videos

Videos are a widget that allows clients to upload a set of videos for a project. This is then available on the project page for the user to watch.

GET /projects/<id>/videos.json will return a list of videos associated to a particular project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/videos.json

{
  "videos": [
  {
    "created_at": "2011/05/17 21:04:03 +1000",
    "id": 20,
    "caption": "Matthew Crozier",
    "video_link": "http://www.youtube.com/watch?v=9B247eefcyY"
  },
  {
    "created_at": "2011/05/17 21:04:47 +1000",
    "id": 21,
    "caption": "Matthew Crozier on moderation",
    "video_link": "http://www.youtube.com/watch?v=LcJy8NN0OJs"
  },
  {
    "created_at": "2011/05/19 13:12:41 +1000",
    "id": 22,
    "caption": "Guestbook Video",
    "video_link": "http://btt_ankoder_videos.s3.amazonaws.com/123562_73299_6ec6ee0721cf6e2480ede1f39f74d946cbda21f1_73299.flv"
  },
  {
    "created_at": "2011/05/19 13:22:38 +1000",
    "id": 23,
    "caption": "Surveys",
    "video_link": "http://btt_ankoder_videos.s3.amazonaws.com/123566_73300_73b871dfe4a2f28d204102eca26a7ed1cd3e59f3_73300.flv"
  }
  ]
}

Documents

Documents are a widget that allows clients to upload files that may be needed for a project. These files are then available for download on the project page.

GET /projects/<id>/documents.json will return a list of documents that are associated to a particular project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/documents.json

{
  "documents": [
        {
            "id": 16,
            "name": "Online Consultation Guidebook",
            "filename": null,
            "url": "http://s3.amazonaws.com/ehq-v2-develop/documents/attachments/000/000/018/original/Getting_the_best_out_of_EngagementHQ_planning_worksheets.pdf?1369631312",
            "size": null,
            "created_at": "2013-05-27T15:06:47+10:00"
        },
        {
            "id": 17,
            "name": "Tips to Writing Engaging Questions",
            "filename": null,
            "url": "http://s3.amazonaws.com/ehq-v2-develop/documents/attachments/000/000/017/original/Questions.pdf?1369631312",
            "size": null,
            "created_at": "2013-05-27T15:07:29+10:00"
        }
    ]
}

Guestbook

A guest book is a tool that lets users leave a general comment regarding a project. There can be only one guest book for a project.

GET /projects/<id>/guestbook.json will return the details of the guest book associated to the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/guestbook.json

{
  "guestbook": {
    "total_score": 48,
    "name": "Guest Book",
    "id": 71
  }
}

Q and A

The Q and A (Question and Answer) tool is a way for the client to allow the audience to ask questions directly to the people the are driving a particular consultation (project). Allows anyone to ask a question and provides an interface for the project administrators to manage and answer the questions either privately or publicly.

GET /projects/<id>/qandas.json will return the details of the Q and A associated to the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/qandas.json

{
  qandas: [
  {
    name: "Q&A",
    created_at: "2011/11/16 19:31:09 +1100",
    id: 162,
    description: ""
  }
  ]
}

GET /projects/<id>/qandas/<id>/questions.json will return the questions associated to a particular Q and A in the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/qandas/162/questions.json

{
 	qanda_questions: [
 {
		 	created_at: "2012/03/28 15:50:17 +1100",
		 	user_screen_name: "admin",
		 	id: 1439,
		 	user_id: 1,
		 	state: "newly_added",
		 	question: "DO you like qanda ?",
		 	permalink: "https://example.com/your-say-cafe?module=qanda&qn_id=1439#single_question_1439"
	 	},
 {
		 	created_at: "2012/03/28 16:07:56 +1100",
		 	user_screen_name: "tracey",
		 	id: 1442,
		 	user_id: 148,
		 	state: ""privately_answered",
		 	question: "I would like to find out more about Q&A. Can you answer questions privately?",
		 	permalink: null
	 	},
 {
		 	created_at: "2012/03/28 16:10:45 +1100",
		 	user_screen_name: "tracey",
		 	id: 1443,
		 	user_id: 148,
		 	state: "privately_answered",
		 	question: "This is another question about publicly answered questions. Do they work too?",
		 	permalink: "https://example.com/your-say-cafe?module=qanda&qn_id=1443#single_question_1443"
	 	},
		{
		 	created_at: "2012/09/21 22:46:50 +1000",
		 	user_screen_name: "anonymous",
		 	id: 1562,
		 	user_id: null,
		 	state: "publicly_answered",
		 	question: "Pleasing to find smoenoe who can think like that",
		 	permalink: "https://example.com/your-say-cafe?module=qanda&qn_id=1562#single_question_1562"
	 	},
 {
		 	created_at: "2012/09/22 03:44:29 +1000",
		 	user_screen_name: "anonymous",
		 	id: 1564,
		 	user_id: null,
		 	state: "publicly_answered",
		 	question: "That insight sovels the problem. Thanks!",
		 	permalink: "https://example.com/your-say-cafe?module=qanda&qn_id=1564#single_question_1564"
	 	}
 	]
}

GET /projects/<id>/qandas/<id>/answers.json will return the answers associated to a particular Q and A in the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/qandas/162/answers.json

{
 	qanda_answers: [
 {
		 	question_id: 1439,
		 	created_at: "2012/03/28 15:50:42 +1100",
		 	user_screen_name: "admin",
		 	public: false,
		 	private: true,
		 	id: 1440,
		 	user_id: 1,
		 	answer: "yes"
	 	},
 {
		 	question_id: 1439,
		 	created_at: "2012/03/28 15:50:52 +1100",
		 	user_screen_name: "admin",
		 	public: true,
		 	private: false,
		 	id: 1441,
		 	user_id: 1,
		 	answer: "is it working?"
	 	},
 {
		 	question_id: 1442,
		 	created_at: "2012/03/28 16:11:44 +1100",
		 	user_screen_name: "admin",
		 	public: false,
		 	private: true,
		 	id: 1445,
		 	user_id: 1,
		 	answer: "Yes that is possible and it stays completely private."
	 	},
		{
		 	question_id: 1462,
		 	created_at: "2012/03/28 18:21:21 +1100",
		 	user_screen_name: "admin",
		 	public: true,
		 	private: false,
		 	id: 1465,
		 	user_id: 1,
		 	answer: "Of course it does. "
	 	},
 {
		 	question_id: 1463,
		 	created_at: "2012/03/28 18:20:49 +1100",
		 	user_screen_name: "admin",
		 	public: true,
		 	private: false,
		 	id: 1464,
		 	user_id: 1,
		 	answer: "You can use the Q&A tool throughout your project."
	 	}
 	]
}

Maps

The Map is a tool that allows the audience to place pins on the map and answer questions set by the Admins. A Project can have multiple maps. It is possible for a map to allow users to respond anonymously (i.e. without having to register or login to the site). In this case responses will be associated to a system generated dummy user.

GET /projects/<id>/maps.json will return a list of the maps created in the project.

curl -u <admin username>:<password> https://example.com/v1/projects/1/maps.json

{
  "maps": [
    {
      "markers": {
        "url": "https://example.com/v1/projects/1/maps/1/markers",
        "count": 2
      },
      "title": "Map 1",
      "id": 1,
      "description": "<p>Map description</p>",
      "lat": -37.8142,
      "lng": 144.963,
      "created_at": "2016-07-27 14:50:48",
      "categories": [
        {
          "name": "Marker"
        }
      ],
      "questions": {
        "url": "https://example.com/v1/projects/1/maps/1/questions",
        "count": 3
      }
    },

{
      "markers": {
        "url": "https://example.com/v1/projects/1/maps/2/markers",
        "count": 2
      },
      "title": "Map 2",
      "id": 2,
      "description": "<p>Map description</p>",
      "lat": -37.8142,
      "lng": 144.963,
      "created_at": "2016-07-28 14:50:48",
      "categories": [
        {
          "name": "Marker"
        }
      ],
      "questions": {
        "url": "https://example.com/v1/projects/1/maps/2/questions",
        "count": 3
      }
    }
  ]
}

GET /projects/<id>/maps/<id>/questions.json will return a list of the questions that are part of a particular map.

curl -u <admin username>:<password> https://example.com/v1/projects/1/maps/1/questions.json

{
    map_questions: [
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 9,
            answer_type: "radio_buttons",
            question: "Would you want a water fountain here?",
            options: [
                {
                value: "Yes",
                id: 10
                },
                {
                value: "Good to have",
                id: 11
                },
                {
                value: "Not really",
                id: 12
                },
                {
                value: "Not at all",
                id: 13
                }
            ]
        },
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 10,
            answer_type: "check_boxes",
            question: "How clean is the area?",
            options: [
                {
                value: "Very",
                id: 14
                },
                {
                value: "Not very",
                id: 15
                },
                {
                value: "As mud",
                id: 16
                }
            ]
        },
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 12,
            answer_type: "essay",
            question: "Tell us what else you would have liked to have?",
            options: [ ]
        },
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 13,
            answer_type: "single_line",
            question: "Any other comments?",
            options: [ ]
        },
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 15,
            answer_type: "file",
            question: "Attach a photo that describes your feelings",
            options: [ ]
        },
        {
            created_at: "2016/07/27 15:51:49 +1100",
            id: 16,
            answer_type: "dropdown",
            question: "Choose which of these you would most like for dinner",
            options: [
                {
                value: "Peas",
                id: 17
                },
                {
                value: "Rasberry Jelly",
                id: 18
                },
                {
                value: "Cheese",
                id: 19
                },
                {
                value: "Goulash",
                id: 20
                }
            ]
        }
    ]
}

Questions with multiple responses options will contain an array with the id and the value for the options.

GET /projects/<id>/maps/<id>/markers.json will return the markers submitted for a particular map.

{
  "markers": [
    {
      "id": 1,
      "category": "Marker",
      "lat": "-37.80463017025873",
      "lng": "144.9631404876709",
      "created_at": "2016-07-29T01:44:01+10:00",
      "user_screen_name": "btt_admin",
      "user_id": 1,
      "responses": [
        {
          "answer": [
            "check box option 1"
          ],
          "question_id=": 1
        },
        {
          "answer": "Dropdown option 1",
          "question_id=": 2
        },
        {
          "answer": "Essay Answer",
          "question_id=": 3
        },
        {
          "answer": "file_name.png",
          "question_id=": 4
        },
        {
          "answer": "Radio Button 1",
          "question_id=": 5
        },
        {
          "answer": "Single Answer ",
          "question_id=": 6
        }
      ]
    },
    {
      "id": 2,
      "category": "Marker",
      "lat": "-37.81432712106107",
      "lng": "144.9623680114746",
      "created_at": "2016-07-29T18:39:11+10:00",
      "user_screen_name": "btt_admin",
      "user_id": 1,
      "responses": [
        {
          "answer": [
            "check box option 1",
            "check box option 2"
          ],
          "question_id=": 1
        },
        {
          "answer": "Dropdown option 1",
          "question_id=": 2
        },
        {
          "answer": "Essay Answer",
          "question_id=": 3
        },
        {
          "answer": null,
          "question_id=": 4
        },
        {
          "answer": "Radio Button 2",
          "question_id=": 5
        },
        {
          "answer": "Single Answer",
          "question_id=": 6
        }
      ]
    }
  ]
}

Introduction

The API URL

Users

Get all users

Get details of a specific user

Get a users profile

Team Members

Projects

Get a list of projects

Get details of a specific project

Topics

Get a list of comments for a topic

Surveys

Get a list of questions for a survey

Intelligent Questions

Signup Form Questions

Forms

Get a list of forms in a project

Get a list of fields in a form

Get a list of responses for a form

Posts

Key Dates

FAQs

Photos

Videos

Documents

Guestbook

Q and A

Maps