API Reference

Get Satisfaction’s REST API provides a technical way to access community data, which lets third-party tools interact with our platform. The API follows REST conventions for URL construction, and can return data in JSON format. Acceptable use of the service and API are covered in our Terms of Service.

For general discussion about the API, please join the Get Satisfaction developer community at: /devcommunity. For direct contact, email support@getsatisfaction.com.

All calls to the API must be prepended with http://api.getsatisfaction.com, and can be appended with .json to choose JSON formatting for the API output. Errors are reported with standard HTML error codes, and results are paginated.

Topics

A topic is the general name for any new posting in a community. There are four varieties of topics: Questions, Ideas, Problems, and Praise. There is a fifth topic type available only to employees of communities, called "Company Update", which is used to make general announcements for the community.

Topic Data

The topic response payload contains the following data:

Getting Topic information using HTTP GET method

Sorting and Filtering Topic Data

Replies

Replies are made to topics or to other replies. Replies can be promoted when either users or community moderators decide that a reply represents the best answer to a particular question or problem. Users can promote a reply by awarding the topic at least three stars; community moderators (for communities with paid accounts) can elevate a reply to official status directly.

Reply Data

The Reply response payload contains the following data:

Getting Reply information using HTTP GET method

Filtering Reply Data

Comments

Comments are children of replies, posted in response to a reply in a topic. 

Comment Data

The Comment response payload contains the following data:

Getting Comment information using HTTP GET method

Companies

The companies object generally returns the following information. When a particular community is specified, all of this information is returned. When no particular community is specified in the API call, several of the elements are not included, as noted below with an asterisk:

Community Data

Getting Community information using HTTP GET method

Filtering Community Data

People

Finding People

Products

Product Data

Finding Products

Tags

Finding Tags

Posting and Modifying Topics

Topics can be created using the API using the POST method, and modified using the PUT method. All calls need to be authenticated using either Basic Auth or OAuth, depending on whether the community is public or private. Topics cannot be created or modified by a user other than the one whose credentials are validating the API call.

To create a topic on Get Satisfaction, submit an HTTP POST request to http://api.getsatisfaction.com/topics with the required subject parameter and any of the following optional parameters. Similarly, to modify a topic on Get Satisfaction, submit a PUT request with the parameters you want to modify.

Example Payload

                                  {
                                     "topic": 
                                              {
                                              "subject": "test for product affiliate", 
                                              "style": "praise", 
                                              "keywords": "keyword", 
                                              "additional_detail": "additional detail goes here",
                                              "products": "thingamajig",
                                              "emotitag":
                                                   {
                                                   "face": "happy",
                                                   "feeling": "very happy",
                                                   "intensity": 2
                                             		}
                                              }
                                   }
                            
                            

Posting replies

To post a reply to a topic, you make an HTTP POST to the replies sub-resource of a topic. To find this URL, you should look at the <link rel="replies"> element of a topic's Atom entry. Alternatively, if you know the URL of a topic, you can add "/replies" onto the end of it to manually form the URL.

Required POST parameters:

• reply[content]
  The text content of the reply.

Optional POST parameters:

• reply[emotitag][face]
  A value that describes the emoticon face to attach to this topic, either happy, sad, indifferent, or silly.
• reply[emotitag][feeling]
  A word or two describing in more detail how you are feeling. Examples include anxious, thankful, or frustrated.
• reply[emotitag][intensity]
  A rating of 0-3 that describes the intensity of how you are feeling, 3 being the most intense, 0 being the baseline.

Responses and Errors

All response codes are included in the HTTP Status response header. Possible status codes include:

Other HTTP verbs

Successful POST requests (e.g., to create a new record) will return a status code of 201, and include the JSON representation of the resource in the body of the response. Successful PUT requests (e.g., to update an existing record) will return a status code of 200, and include the JSON representation of the resource in the body of the response. Successful DELETE requests (e.g., to delete an existing record) will return a status code of 200 and no body.

Pagination

By default, all data that comes as a result of a GET request comes in a page load of thirty data objects. The following query parameters can be used to modify the page load or specify a particular page.