API Reference

List of URLs into the API and what they represent. All calls to the API must be prepended with http://api.getsatisfaction.com

Note: In several of the URLs we have used examples to more easily show you how the URL works.

Companies

URL Resource
/companies All of the companies in Get Satisfaction
/companies?sort=recently_active Companies sorted by most recently active.
/companies?sort=recently_created Companies sorted by most recently created.
/companies?sort=alpha Companies sorted alphabetically.
/companies?page=3&limit=10 Goes to page 3 of the company list, showing 10 companies. (A limit of 30 is max.)
/companies?query=Moo Full text search for Moo. Search disables the sort parameter.
/people/scott/companies Companies created by scott
/people/scott/followed/companies Companies scott is following
/products/apple_ipod/companies Companies related to the iPod
/tags/foo/companies Companies tagged foo
/flagged/companies Companies that have been flagged

Sample XHTML Response

Annotated Company hCard

People

People lists are represented as an XHTML unordered list of hCards.

(Not valid outside of a company's scope)
URL Resource
/people All of the people in Get Satisfaction
/people?page=3&limit=10 Goes to page 3 of the people list, showing 10 people. (A limit of 30 is max.)
/companies/timbuk2/employees Employees of timbuk2
/companies/timbuk2/people People who have been to timbuk2 's site
/companies/timbuk2/people?filter=contributors
/companies/timbuk2/people?role=employee (Not valid outside of a company's scope)
/companies/timbuk2/people?role=company_admin (Not valid outside of a company's scope)
/people?query=kim Full text search for kim.
/people/scott/followed/people People scott is following (not implemented yet)
/products/apple_ipod/people People following the iPod
/topics/openid_support/people People participating in the OpenId Support topic
/flagged/people People that have been flagged

Sample XHTML Response

Products

Product lists are represented as an unordered list of hProduct items

URL Resource
/products All of the products in Get Satisfaction
/products?page=3&limit=10 Goes to page 3 of the product list, showing 10 products. (A limit of 30 is max.)
/products?sort=recently_created Products sorted by most recently created.
/products?sort=most_popular Products sorted by most popular.
/products?sort=least_popular Products sorted by least popular.
/products?sort=alpha Products sorted alphabetically.
/products?query=macbook Full text search for macbook. (Only available in global scope)
/companies/timbuk2/products Products that timbuk2 is related to
/people/scott/products Products scott created
/people/scott/followed/products Products scott is following
/tags/foo/products Products tagged foo
/topics/openid_support/products Products that the OpenId Support topic is about
/flagged/products Products that have been flagged

Sample XHTML Response

Tags

URL Resource
/tags All of the tags in Get Satisfaction
/tags?page=3&limit=10 Goes to page 3 of the tag list, showing 10 tags. (A limit of 30 is max.)
/companies/timbuk2/tags Tags that have been applied to timbuk2
/people/scott/followed/tags Tags scott is following (not implemented yet)
/products/apple_ipod/tags Tags applied to the iPod
/topics/openid_support/tags Tags applied to the OpenId Support topic

Topics

Topics have one of 4 styles: Question, Idea, Problem, and Praise. They form the basis of all communication that takes place in Get Satisfaction. In the Get Satisfaction API, topics are represented as an Atom feed, with at least 1 entry. This first entry of a topic feed is the content for the topic itself. Every entry after the first is a reply to the original topic.

URL Resource
/topics All of the tags in Get Satisfaction
/topics?page=3&limit=10 Goes to page 3 of the topic list, showing 10 topics. (A limit of 30 is max.)
/topics?sort=recently_created Topics sorted by most recently created.
/topics?sort=recently_active Topics sorted by most recently active.
/topics?sort=most_flagged Topics sorted by most flagged.
/topics?sort=unanswered Topics sorted by unanswered.
/topics?style=problem All problems posted to Get Satisfaction
/topics?query=foo Full text search for foo.
/companies/apple/topics?active_since=1250526482 All topics that have been replied to since a given timestamp (Specified in the number of seconds since epoch, in the UTC timezone)
/companies/timbuk2/topics Topics posted to timbuk2
/companies/timbuk2/products/timbuk2_blogger/topics Topics posted to timbuk2 about the Blogger
/companies/timbuk2/tags/foo/topics Topics posted to timbuk2 that have the foo tag applied to them
/people/scott/topics Topics scott posted
/people/scott/followed/topics Topics scott is following
/products/apple_ipod/topics Topics related to the iPod
/tags/foo/topics Topics tagged foo
/topics/openid_support/related Occasionally related topics to the OpenId Support topic
/flagged/topics Topics that have been flagged

Annotated Atom Response

Posting Topics

To create a topic on Get Satisfaction, you will perform a HTTP POST to http://api.getsatisfaction.com/topics with a set of required and optional parameters. You can look at http://api.getsatisfaction.com/topics/new to see a mock HTML form that describes the parameters that are available.

Required parameters:

  • topic[company_id]
    The Get Satisfaction specific record ID of the company that you are posting this topic to. The is the <span class="id" /> tag in a company hCard. Use either this option or topic[company_domain] to set the company, but not both.
  • topic[company_domain]
    Is an alternative to using topic[company_id] and allows you to specify the owning company of topic using its name. A company's domain is the first element of the URL path in the main Get Satisfaction API. For example Twitter's address on Get satisfaction is http://getsatisfaction.com/twitter so its domain is 'twitter'
  • topic[style]
    Specifies the topic's style — either question, idea, problem, or answer.
  • topic[subject]
    The single-sentence summary of a topic that shows up in topic listings.
  • topic[additional_detail]
    A full description of the topic.

Optional parameters:

  • topic[keywords]
    A comma-separated list of tags that are to be associated with topic.
  • topic[products]
    A comma-separated list of product names that should be associated with this topic.
  • topic[emotitag][face]
    A value that describes the emoticon face to attach to this topic, either happy, sad, indifferent, or silly.
  • topic[emotitag][feeling]
    A word or two describing in more detail how you are feeling. Examples include anxious, thankful, or frustrated.
  • topic[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.

Replies

Replies are made to topics or other replies. Similar to topics, they are represented as Atom entries. Replies do not exits at the global level.

URL Resource
/topics/openid_support/replies All replies for OpenID Support
/topics/openid_support/replies?page=3&limit=10 Goes to page 3 of the reply list, showing 10 replies. (A limit of 30 is max.)
/topics/openid_support/replies?sort=most_useful Replies sorted by most useful.
/topics/openid_support/replies?sort=recently_created Replies sorted by most recently created.
/topics/openid_support/replies?filter=best Best replies.
/topics/openid_support/replies?filter=star_promoted Starred replies.
/topics/openid_support/replies?filter=company_promoted Replies promoted by company.
/topics/openid_support/replies?user=13 All replies by user 13.
/people/scott/replies Replies scott created
/flagged/replies Replies that have been flagged

Annotated ATOM Response

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.