Get Satisfaction Education Center

Home > Reference Guide > API > API Resources

API Resources

 

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 use the “Ask a Question” tab on the left side of this page.

All calls to the API must be prepended with https://api.getsatisfaction.com, and can be appended with .json to choose JSON formatting for the API output.

Results are paginated.

Response codes and errors are reported with standard HTML status codes.

 

Topics

A topic indicates a main post (the one that initiates a thread) in a community. A topic can be a Question, Idea, Problem, Praise, or Update. Only community moderators can post Updates.

Topic Data

Data Object Description
"at_sfn": URL for the topic page
"follower_count": The number of people following the topic
"created_at": The date and time topic was created
"last_active_at": The date and time of last topic activity
"status": The topic status. Values are:

  • "null"
  • "pending"
  • "active"
  • "complete"
  • "rejected"
"user_defined_code": The private tag if there is one. If there isn’t one, it returns “false”
"most_recent_activity": The most recent action taken on the topic. Values are “create”, “comment”, and “follow”.
"employee": Whether the topic was created by an employee or not. Returns “true” or “false”.
"champion:" Whether the topic was created by a champion or not. Returns “true” or “false”.
"subject": The subject line for the topic
"company_id": The id for the company in Get Satisfaction
"emotitag":
"feeling": The text associated with the emoticon face.
"face": The emoticon face. Values are “happy”, “silly”, “indifferent”, and “sad”
"intensity": The intensity of the emoticon on a scale of 0 to 4, as follows:

  • 0 – hides the emoticon
  • 1 – shows the emoticon
  • 2 – shows the emoticon with one exclamation mark
  • 3 – shows the emoticon with two exclamation marks
  • 4 – shows the emoticon with two exclamation marks
"author": Returns the following data block for the author of the post (see the people object for more information):

"at_sfn": The URL path to the user’s profile page
"champion": Whether the user is a champion. Returns “true” or “false”
"employee": Whether the user is an employee. Returns “true” or “false”
"canonical_name": The slug for the user’s Get Satisfaction profile: (/profile/[canonical name])
"avatar_url_small": The URL path to small sized avatar image
"avatar": The URL path to the full size image the user uploaded for their avatar
"avatar_url_medium": The URL path to medium sized avatar image
"url": The API path to the user’s information
"avatar_url_mini": The URL path to a mini sized avatar image
"avatar_url_large": The URL path to large sized avatar image
"name": The nickname of the user (not the “canonical name”)
"id": The ID for the user
"has_promoted_replies": Whether the topic has any replies promoted, either through stars or as a company answer. Returns “true” or “false”
"content": The body of the topic
"style": The type of topic: possible values are “question”, “problem”, “praise”, “idea”, and “update”.
"url": The API endpoint that returns the topic object
"slug": The URL slug for the particular topic
"following": Whether the topic is being followed by the user who is authenticating the API call. Returns “true” or “false”
"me_too": The URL slug for the particular topic
"me_too_count": The count of people who have clicked the +1 button (including the original poster)
"id": The topic ID
"reply_count": The number of replies and comments for this topic
“active_replies”: The number of replies (but not comments) that are associated with the topic and have not been archived or deleted.
"is_closed": Boolean to show if the topic has been closed. True if closed, False if not closed.
“closed_at”: A timestamp of when the topic was closed. This property only exists if “is_closed” is True.

 

Getting Topic information using HTTP GET method

Data API Endpoint
Get a specific topic /topics/[topic slug or id]
Get all topics in all public Get Satisfaction communities /topics
Get all topics in a particular community /companies/[community_name or ID]/topics
Get all topics related to a specific product in a particular community /companies/[community_name or ID]/products/[product_name]/topics
Get all topics tagged with a specific tag within a particular community /companies/[community_name or ID]/tags/[tag]/topics
Get all topics that a particular user has posted (*there is a question about how these numbers are calculated) /people/[user ID]/topics
Get all topics that a particular user is following /people/[user ID]/followed/topics
Get all topics identified with a specific product /products/[product name]/topics

 

Sorting and Filtering Topic Data

Search
Search for a particular string ?query=[search string] or ?q=[search string]
Sort
Sort by the most recently created topic ?sort=recently_created
Sort topics by most recent activity ?sort=recently_active
Sort by the highest number of topic replies ?sort=most_replies
Sort by the highest number of me too votes ?sort=most_me_toos
Filter out all answered questions ?sort=unanswered
Style
Filter by style
  • ?style=question
  • ?style=problem
  • ?style=praise
  • ?style=idea
  • ?style=update
Community Activity
Filter by the time of the last activity in the community. Time is set in seconds since epoch. ?active_since=[epoch time]
User
Filter by user ID ?user=[user ID]
Company
Filter by company ID ?company=[company ID]
Product
Filter by product name in API queries where the company is specified (for example, /companies/[company name or company ID]/topics) ?product=[product name] or use a comma separated list (?product=[product1],[product2]) for filtering by multiple products.
Tag
Filter by tag ?tag=[tag]
Status
Filter by status ?status=[status] or use a comma separated list (?status=[status1],[status2]) for filtering by multiple statuses.Status filter values are “none”, “pending”, “active”, “complete”, and “rejected”. These apply to Problem, Idea, and Question topics. Praise and Updates have a status of “None.”

These statuses map to different properties for different kinds of topics:

None — No Status

Rejected– Not a Problem, Doesn’t need Answer, Not Planned,

Pending — Acknowledged, Under Consideration

Active — In Progress, Planned

Complete — Solved, Answered, Implemented

Private Tag
Filter by Private Tags ?user_defined_code=[UDC] or use a comma separated list (?user_defined_code=[UDC1],[UDC2]) for filtering by User Defined Codes.
Archived Topics
Filter by Archived Topics ?include_archived=true

 

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 3-legged OAuth. 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 https://api.getsatisfaction.com/topics with the required subject and company_domain parameters, 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.

 

Required Parameters for the /topics endpoint
subject The subject line for the topic
company_domain The community slug for the topic
Optional Parameters for the /topics endpoint
style Specifies the type of topic: possible values are “question”, “problem”, “praise”, “idea”, and “update”.
keywords A comma-separated list of tags that are to be associated with topic. Using the PUT command will add the keyword(s) to the list of tags associated with the topic. To overwrite the existing keyword(s), the keywords list needs to be followed with "overwrite_keywords": true.
additional_detail A full description of the topic. The same as the topic content.
products Array of product/services canonical names that should be associated with this topic.
emotitag
"feeling": The text associated with the emoticon face.
"face": The emoticon face. Values are “happy”, “silly”, “indifferent”, and “sad”
"intensity": The intensity of the emoticon on a scale of 0 to 4, as follows: · 0 – hides the emoticon · 1 – shows the emoticon · 2 – shows the emoticon with one exclamation mark · 3 – shows the emoticon with two exclamation marks · 4 – shows the emoticon with two exclamation marks

 

Example Payload

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

 

Replies

Replies are children of topics, posted in response to a Topic.
Replies can be “community promoted” when users award that reply three or more stars. Replies are “company promoted” when community moderators set the reply as the official response of the topic.

Reply Data

The Reply response payload contains the following data:

Data Object Description
"created_at:" The date and time reply was created
"employee:" Whether the reply was created by an employee or not. Returns “true” or “false”.
"champion:" Whether the reply was created by a champion or not. Returns “true” or “false”.
"author:" Returns the following data block for the author of the reply:

"at_sfn": The URL path to the user’s profile page
"champion": Whether the user is a champion. Returns “true” or “false”
"employee": Whether the user is an employee. Returns “true” or “false”
"canonical_name": The slug for the user’s Get Satisfaction profile: (/profile/[canonical name])
"avatar_url_small": The URL path to small sized avatar image
"avatar": The URL path to the full size image the user uploaded for their avatar
"avatar_url_medium": The URL path to medium sized avatar image
"url": The API path to the user’s information
"avatar_url_mini": The URL path to a mini sized avatar image
"avatar_url_large": The URL path to large sized avatar image
"name": The nickname of the user (not the “canonical name”)
"id": The ID for the user
"url:" The API endpoint that returns the reply object.
"content:" The body of the reply.
"star_count:" The number of stars the reply has earned.
"star_promoted:" Whether the reply has been promoted by earning 3 stars from users. Returns “true” or “false”.
"starred:" Whether the reply has been starred by the user who is authenticating the API call. Returns “true” or “false”
"topic_id:" The ID of the associated topic
"company_promoted:" Whether the reply has been promoted manually by a company employee. Returns “true” or “false”
"comment_count:" The number of comments that are associated with this reply.
"comments_url" The URL to query for all comments associated with this reply.
"id:" The reply ID.

 

Getting Reply information using HTTP GET method

Data API Endpoint
Get all replies from the specified topic /topics/[topic ID or slug]/replies
Get all replies that a particular user has posted /people/[user ID]/replies

 

Filtering Reply Data

Filter
Return promoted replies (both star promoted and company chosen replies) ?filter=best
Return only star promoted replies ?filter=star_promoted
Return only company promoted replies ?filter=company_promoted
Return all company and star promoted replies ?type=flat_promoted
Exclude comments from the returned replies ?include_comments=false

 

Posting replies

To post a reply to a topic, you make an HTTP POST to the /topics/[topic ID or slug]/replies endpoint.

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.

 

Sample PHP Code to Post a Reply

require_once "HTTP/Request2.php";
$endpoint = 'https://api.getsatisfaction.com/topics/3645549/replies.json';
$request = new HTTP_Request2($endpoint, HTTP_Request2::METHOD_POST);
$request->setAuth(USER, PASSWORD, HTTP_Request2::AUTH_BASIC);
 
$newBody = '{"reply": { "content" :"my test reply"}}';
 
$newHeader = 'Content-type: application/json';
$request->setHeader($newHeader);
$request->setBody($newBody);

$response = $request->send();

 

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:

Data Object Description
"created_at:" The date and time comment was created
"employee:" Whether the comment was created by an employee or not. Returns “true” or “false”.
"champion:" Whether the comment was created by a champion or not. Returns “true” or “false”.
"author:" Returns the following data block for the author of the comment:

"at_sfn": The URL path to the user’s profile page
"champion": Whether the user is a champion. Returns “true” or “false”
"employee": Whether the user is an employee. Returns “true” or “false”
"canonical_name": The slug for the user’s Get Satisfaction profile: (/profile/[canonical name])
"avatar_url_small": The URL path to small sized avatar image
"avatar": The URL path to the full size image the user uploaded for their avatar
"avatar_url_medium": The URL path to medium sized avatar image
"url": The API path to the user’s information
"avatar_url_mini": The URL path to a mini sized avatar image
"avatar_url_large": The URL path to large sized avatar image
"name": The nickname of the user (not the “canonical name”)
"id": The ID for the user
"url:" The API endpoint that returns the comment object.
"content:" The body of the comment.
"topic_id:" The ID of the associated topic
"id:" The comment ID.

 

Getting Comment information using HTTP GET method

Data API Endpoint
Get all comments from the specified topic /topics/[topic ID or slug]/comments
Get all comments from the specified reply /replies/[reply ID or slug]/comments

 

Companies

Company is the API name for a community. When a particular community is specified in the API call, all the following 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

Data Object Description
"description": * The Description from the basic information description field.
"people": The API endpoint for people in the community
"products": The API endpoint for products related to the company
"logo": The URL path to the company’s uploaded logo image
"topics": The API endpoint for company topics
"url": The API endpoint for the company information
"featured_people": * The featured people object contains people and topic information for the people who appear in the “community members” area in most communities. This includes information for both a new user’s first topic and also information for a user who answered a recent topic. More detail about the information in each block can be found in the person object and the topic object.
"approximate_topic_count:" The number of topics in the community
"approximate_people_count": The number of people in the community
"name": The community name
"domain": The community domain
"id": The community id
"approximate_employee_count": The number of employees in the community

 

Getting Community information using HTTP GET method

Data API Endpoint
Get all the public Get Satisfaction communities /companies
Get all the public Get Satisfaction communities created by the specified user /people/[user name or ID]/companies
Get all the public Get Satisfaction communities related to the specified product /products/[product name or ID]/companies
Get the date and time of the last activity in the specified community /companies/[company name or ID]/last_activity_at

 

Filtering Community Data

Search
Search for a particular string ?query=[search string] or ?q=[search string]
Show
Show communities that are indexable by search engines, and that also have activity ?show=public
Show all communities that are indexable by search engines ?show=not_hidden
Show communities that are either not indexable by search engines, or that have no activity ?show=private
Show all communities ?show=not_hidden
Sort
Sort by the most recently created community ?sort=recently_created
Sort topics by most recent activity ?sort=recently_active
Sort alphabetically by the name of the community ?sort=alpha

 

 

People

Finding People

URL Resource
/people?page=3&limit=10 Goes to page 3 of the people list, showing 10 people. (A limit of 30 is max.)
/companies/community_id/employees Employees of [community_name]
/companies/community_id/people People who have been active in the [community_name] community
/people?fastpass_id={external_id} User associated with the given fastpass id. This is a 2-legged API request that must be signed with the fastpass key and secret
/topics/openid_support/people People participating in the OpenId Support topic

 

Products

Product Data

Data Object Description
"links": Returns the following data block for each of the links that are related to the product:

"label": The name of the link as it appear on the page
"created_at": When the link was created
"url": The URL path for the link
"id": The ID for the link
"created_at": The date and time that the product was created
"description": The product description
"company": The company name as it appears in the URL slug
"name": The product name
"url": The API endpoint for the product
"image": The url for the image associated with the product
"id": The product id

 

Finding Products

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.
/companies/[community_name]/products Products in the [community_name] community
/people/scott/products Products scott created
/topics/openid_support/products Products that the OpenId Support topic is about

 

Tags

Finding 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.)
/topics/[topic name or ID]/tags Tags applied to the specified topic
/companies/[company name or ID]/tags Return all the tags used on topics in the community

 

Detailed Example for Editing Tags for Topics

Note: This API flow works only for topics you have permissions to change the tags on. This will generally be topics you create or announcements in a community you are an admin for.

To create a new topic that contains tags, use this syntax:

  • Method: POST
  • Endpoint: /topics
  • Payload: { “topic”: { “keywords”: “tag1, tag2, tag3”, “subject” … } }

To add an additional new tag to an existing topic:

  • Method: PUT
  • Endpoint: /topics/[topic_id]
  • Payload: { “topic”: { “keywords”: “tag4” } }

To remove all existing tags and add a new tag to an existing topic:

  • Method: PUT
  • Endpoint: /topics/[topic_id]
  • Payload: {“keywords”: “tag5”, “overwrite_keywords”: true } }

To remove all tags from a topic:

    • Method: PUT
    • Endpoint: /topics/[topic_id]
    • Payload: { “topic”: { “keywords”: null } }

 

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.

Pagination
Show the data from the specified page. In general, there are 30 data blocks per page, by default. ?page=[n]
Limiting
Set the limit for data blocks per page. ?limit=[n]

 

Response codes and rate limiting

The Get Satisfaction API has a built-in rate limiting mechanism restricting the number of API calls that can be made per minute with a facility to allow brief bursts of activity that exceed the aggregate rate limits. Excessive API calls will receive a 42x HTTP response code which you should treat as a warning that you need to reduce the rate at which you are making API calls. If your application is getting a 42x response code please contact us to discuss your API usage. We reserve the right to block any user of our API based on excess activity, unusual load placed on our servers or for content harvesting that does not have a legitimate business purpose at our sole discretion.

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

420 – Too many connectionsAll EventsThere were too many connections with the same origin.

Code Event Type Meaning
200 – OK All Events The Topic Create or Topic Update Push API call has been received and successfully processed. The end-point can optionally send a response containing updated “mapping” information.
201 – Created Topic Create Reply/Comment Create The Topic Create or Reply/Comment Create Push API call is received and a corresponding object in the external system has been created. The end-point can optionally send a response containing updated “mapping” information.
202 – Accepted All Events The Topic Create or Topic Update Push API calls have been received, but they have not been processed in real-time and instead batched to be processed at a later time. The processing later may or may not be successful.
400 – Bad Request All Events The Push API call is malformed or contains invalid or incomplete information.
401 – Unauthorized All Events An authenticated call is made, but the credentials are invalid.
429 – Rate exceeded All Events API calls are being made at a rate that is too high.
500 – Internal Server Error All Events An internal error occurred while processing the Push API call.
503 – Service Unavailable All Events The end-point is unable to handle the API call. For example, there is scheduled downtime for the end-point back-end systems. The Push API will retry three times, and then suspend the call.

 

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.

System Status

Company Updates