REST API

Yammer provides a RESTful interface to the resources in the Yammer web interface e.g. messages, users, groups etc. Once your app has authenticated a Yammer user, it can call a REST API endpoint using the obtained access token and get the corresponding resources. A simple example is getting the authenticated user’s profile information using the https://www.yammer.com/api/v1/users/current.json API endpoint.

If you are new to REST, you can understand the basics at http://en.wikipedia.org/wiki/REST. Please note that the endpoints support JSON (recommended) and XML. The documentation allows you to shift from JSON to XML where relevant.Timestamps are formatted according to RFC3339.

Rate Limits

API calls are subject to rate limiting. Exceeding any rate limits will result in all endpoints returning a status code of 429 (Too Many Requests). Rate limits are per user per app. There are four rate limits:

Autocomplete: 10 requests in 10 seconds.

Messages: 10 requests in 30 seconds.

Notifications: 10 requests in 30 seconds.

All Other Resources: 10 requests in 10 seconds.

These limits are independent e.g. in the same 30 seconds period, you could make 10 message calls and 10 notification calls. The specific rate limits are subject to change but following the guidelines below will ensure that your app is not blocked.

Messages

When polling for messages, do not exceed one poll per minute. Apps that poll excessively will be blocked. However, your app may sometimes need to fetch messages more frequently e.g. if a user flips between “following”, “sent” and “received” feeds quickly: this is allowed for a few requests. Do not attempt to decrease message latency in your app by checking for new messages more frequently than once per minute.

Autocomplete

The autocomplete resources allow for more frequent polling than other resources, as they are meant to enable realtime responses for a user as they type. See the autocomplete section below to understand how to use this feature.

Other Resources

Rate limits for all other resources are tuned to virtually guarantee that a normally functioning client serving even a heavy Yammer user will not run into rate limit problems.

Admin Actions

In order to perform administrative API actions such as creating and deleting users, the access token should belong to a verified admin user in paid Yammer networks.

Versioning

The API version is shown in the URLs of the endpoints e.g. /api/v1.

Developers should expect that new elements could be added to the XML document or the JSON data structure, in an API version. If elements are removed, we will typically release a new version of the API. The ordering of items within the data structures is not guaranteed. For example, the order of the foo and bar items in the excerpts below might be swapped in the same version of the API:

XML

<things> <foo>Foo!</foo> <bar>Bar!</bar> </things>

JSON

{ "things": { "foo": "Foo!", "bar": "Bar!" } }

Here are the various resources and the corresponding API endpoints:

Messages

Viewing Messages

Endpoints:

1) All public messages in the user’s (whose access token is being used to make the API call henceforth referred to as current user) Yammer network. Corresponds to “All” conversations in the Yammer web interface.

GET https://www.yammer.com/api/v1/messages.json

2) The user’s feed, based on the selection they have made between “Following” and “Top” conversations.

GET https://www.yammer.com/api/v1/messages/my_feed.json

3) The algorithmic feed for the user that corresponds to “Top” conversations, which is what the vast majority of users will see in the Yammer web interface.

GET https://www.yammer.com/api/v1/messages/algo.json

4) The “Following” feed which is conversations involving people, groups and topics that the user is following.

GET https://www.yammer.com/api/v1/messages/following.json

5) All messages sent by the user. Alias for /api/v1/messages/from_user/logged-in_user_id.format.

GET https://www.yammer.com/api/v1/messages/sent.json

6) Private messages received by the user.

GET https://www.yammer.com/api/v1/messages/private.json

7) All messages received by the user.

GET https://www.yammer.com/api/v1/messages/received.json
Parameters:

The messages API endpoints return a similar structure and support the following query parameters:

older_than - Returns messages older than the message ID specified as a numeric string. This is useful for paginating messages. For example, if you’re currently viewing 20 messages and the oldest is number 2912, you could append “?older_than=2912″ to your request to get the 20 messages prior to those you’re seeing.

newer_than - Returns messages newer than the message ID specified as a numeric string. This should be used when polling for new messages. If you’re looking at messages, and the most recent message returned is 3516, you can make a request with the parameter “?newer_than=3516″ to ensure that you do not get duplicate copies of messages already on your page.

threaded=[true | extended] - threaded=true will only return the first message in each thread. This parameter is intended for apps which display message threads collapsed. threaded=extended will return the thread starter messages in order of most recently active as well as the two most recent messages, as they are viewed in the default view on the Yammer web interface.

limit - Return only the specified number of messages. Works for threaded=true and threaded=extended.

Manipulating Messages

Endpoints:

1) Create a new message. The response body will include the new message formatted the same way as message polling above. This allows your app to immediately display the newly-posted message back to the user.

POST https://www.yammer.com/api/v1/messages.json

POST messages are form encoded.

2) Remove a message. The message must be owned by the current user.

DELETE https://www.yammer.com/api/v1/messages/[:id]

DELETE requests should use querystring parameters. If your app does not support the DELETE method you can do a POST with the parameter _method=DELETE.

Parameters:

body - The text of the message body.

group_id - The ID of the group to which the message should be posted.

replied_to_id - The message ID this message is in reply to.

direct_to_id - Send a private message directly to the user indicated.

broadcast=true - This message should be broadcast to all users. The access token should belong to a verified admin user in paid Yammer networks.

topicn - Topics to apply to the message. Can use topic1 through topic20.

attachmentn and pending_attachmentn - Yammer provides two methods to associate attachments with a message. Both make use of multi-part HTTP upload (see RFC1867).

The first method is the easiest, simply use file form elements with names attachment1 through attachment20. If there are a several attachments or the attachments are large it may take some time for a message to POST causing your application to appear to hang.

An alternative way is to use the Pending Attachments resource (see below for details) allowing attachments to be uploaded in parallel. Apps that support HTTP chunked transfer encoding can monitor the progress of each upload. On success each pending attachment’s response body includes an id. These pending attachment ids are to be submitted with the message using form elements pending_attachment1 through pending_attachment20. Finally, if form elements for both attachmentN and pending_attachmentN are present only the pending_attachmentN elements will be honored.

og_<property> - A message may contain an Open Graph (OG) object as an attachment. The og_url parameter is required, the other parameters are optional.

If og_fetch is true, the Yammer server will fetch the page at the URL and attempt to populate the other OG parameters automatically. For this to work, the page must be publicly accessible over the Internet from Yammer’s servers.

og_url - (required) The canonical URL of the OG object that will be used as its permanent ID in the graph.

og_title - The title of your object as it should appear within the graph.

og_image - A thumbnail image URL which represents your object in the graph.

og_description - A one to two sentence description of your object.

og_object_type - The type of your object, e.g., “employee”. Must be a supported type. Here’s the list of supported object types.

og_site_name – An identifier to relate objects from a common domain, e.g., “Yammer Blog”.

og_meta – Structured metadata about this object that can be used by clients for custom rendering.

og_fetch – Fetch Open Graph attributes over the Internet. (default: false)

Pending Attachments

Endpoints:

1) Create a new pending attachment.

POST https://www.yammer.com/api/v1/pending_attachments

2) Delete a pending attachment owned by the current user.

DELETE https://www.yammer.com/api/v1/pending_attachments/[:id]
Parameters:

attachment - Message attachments are supported using a multi-part HTTP upload (see RFC1867).

Emailing Messages

Send the current user a copy of the message specified by the numeric string ID.

POST https://www.yammer.com/api/v1/messages/email

Viewing Threads

The “conversation view” for a thread specified by the numeric string ID.

GET https://www.yammer.com/api/v1/threads/[:id].json

Likes

1) Marks the specified message as liked by the current user.

POST https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]

2) Removes the like mark from the specified message.

DELETE https://www.yammer.com/api/v1/messages/liked_by/current.json?message_id=[:id]

Topics

Topics can be added to a thread either by a user posting a message with a hashtag or by adding the topic after the fact (see parameters for manipulating messages above). Topics, along with their ids, can be retrieved using search or autocomplete.

1) The users that have used the topic specified by the numeric string ID.

GET https://www.yammer.com/api/v1/topics/[:id].json

2) The feed of messages for a hashtag specified by the numeric string ID.

GET https://www.yammer.com/api/v1/messages/about_topic/[:id].json

Groups

Allow current user to join or leave a specified group

Endpoints:

1) Join the group specified by the numeric string ID.

POST https://www.yammer.com/api/v1/group_memberships.json?group_id=[:id]

2) Leave a group.

DELETE https://www.yammer.com/api/v1/group_memberships.json?group_id=[:id]

Parameters:

group_id - The group_id that the user is joining or leaving.

Users

Perform user management i.e. retrieve, create, update, and suspend Yammer users.

Endpoints:

1) Retrieve users in the current user’s Yammer network. Supports page, sort_by, reverse, and letter parameters.

GET https://www.yammer.com/api/v1/users.json

2) View data about the current user.

GET https://www.yammer.com/api/v1/users/current.json

3) View data about a user.

GET https://www.yammer.com/api/v1/users/[:id].json

4) Alias to /api/v1/users/current user’s id.format. Supports include_followed_users, include_followed_tags, and include_group_memberships parameters.

GET https://www.yammer.com/api/v1/users/by_email.json?email=user@domain.com

5) Users in a group. Supports the page parameter.

GET https://www.yammer.com/api/v1/users/in_group/[:id].json

6) Create a new user. Current user should be a verified admin in a paid Yammer network to perform this action.

POST https://www.yammer.com/api/v1/users.json

7) Update information about a user. The target user should be the current user or a verified admin in a paid Yammer network.

PUT https://www.yammer.com/api/v1/users/[:id].json

8) Suspend or delete a user. Current user should be a verified admin in a paid Yammer network to perform this action.

DELETE https://www.yammer.com/api/v1/users/[:id].json
Parameters:

page - Programmatically paginate through the users in the network. 50 users will be shown per page.

letter - Return users with usernames beginning with the given character.

sort_by=[ messages | followers ] - Results will be returned sorted by number of messages or followers, instead of the default behavior of sorting alphabetically.

reverse=TRUE - Returns results in reverse order.

delete=TRUE - The DELETE method on a user resource will suspend that user’s account, allowing the user to reactivate through the website if they have access to a company email address. Passing delete=true along with the request will cause the account to be deleted, which cannot be undone by the user.

Parameters for creating or updating users:

email (required for creating a new user)

full_name

job_title

department_name

location

im_provider

im_username

work_telephone

work_extension

mobile_telephone

external_profiles

significant_other

kids_names

interests

summary

expertise

education[] (school,degree,description,start_year,end_year) - accepts multiple attributes i.e. education[]=UCLA,BS,Economics,1998,2002&education[]=USC,MBA,Finance,2002,2004

previous_companies[] (company,position,description,start_year,end_year) - accepts multiple attributes i.e. previous_companies[]=Geni.com,Engineer,2005,2008

Relationships

Manipulate the Yammer Org Chart.

Endpoints:

1) Show org chart relationships. Defaults to user_current, supports user_id.

GET https://www.yammer.com/api/v1/relationships.json

2) Add an org chart relationship. Specify id of the user for whom the relationship is being added as user_id, if the user is not the current user. Use [ subordinate | superior | colleague ] to create the relationship.

POST https://www.yammer.com/api/v1/relationships.json

3) Remove the relationship specified by relationship_type from the user specified by the numeric string ID.

DELETE https://www.yammer.com/api/v1/relationships/[:id].json?type=[relationship_type]
Parameters:

user_id - To view or edit the relationships for a user other than the logged-in user.

[ subordinate | superior | colleague ]=email_address - Pass email addresses as the value of the subordinate, superior or colleague parameters to add them to your org chart. All three can be passed in one request, and each can be passed multiple times.

id - The user ID whose relationship you’re removing from your org chart. Must be combined with type.

type=relationship_type - One of subordinate, superior, colleague. Used in DELETE requests to indicate which type of relationship you’re removing from your org chart.

Notifications

Get the notifications feed for the current user.

GET https://www.yammer.com/api/v1/streams/notifications.json

Suggestions

View and decline suggestions for joining groups and following users.

Endpoints:

1) Show suggested groups to join and users to follow.

GET https://www.yammer.com/api/v1/suggestions.json

2) Decline a suggestion.

DELETE https://www.yammer.com/api/v1/suggestions/[:id].json
Parameters:

limit - Return only the specified number of suggestions.

Subscriptions

Manage subscriptions to topics, threads, and users.

Endpoints:

1) Check to see if you are subscribed to the user with the given id. Returns 404 when you are not following a given user. If you are in a Community that is set to follow everyone all requests will return 404.

GET https://www.yammer.com/api/v1/subscriptions/to_user/[:id].json

2) Check to see if you are subscribed to thread with the given id. Returns 404 when you are not following a given thread. If you are in a Community that is set to follow everyone all requests will return 404.

GET https://www.yammer.com/api/v1/subscriptions/to_thread/[:id].json

3) Check to see if you are subscribed to topic with the given id. Returns 404 when you are not following a given topic.

GET https://www.yammer.com/api/v1/subscriptions/to_topic/[:id].json

4) Subscribe to a user or topic. Supports target_type and target_id parameters.

POST https://www.yammer.com/api/v1/subscriptions

5) Unsubscribe to a user or topic. Supports target_type and target_id parameters.

DELETE https://www.yammer.com/api/v1/subscriptions
Parameters:

target_type - The target type (user or tag(legacy for topic)) to which user_current will subscribe/unsubscribe. Must be used in combination with target_id.

target_id - The ID of the object to which user_current will subscribe/unsubscribe. Must be used in combination with target_type.

Autocomplete

The autocomplete feature is useful for giving suggestions to users when they begin to type something that looks like the name of a group, user or topic. This is most useful in composing messages in your app. If your user begins to type Hello, @kg and pauses for a fraction of a second, you can send the string kg and prompt the user with the username kgale to complete what she is typing.

To avoid excessive network activity, and to ensure you don’t run up against our rate limits, please only send requests after users have paused their typing for half a second, not when they’re continuously typing.

Please also cache the results you receive for a few minutes to optimize the user experience. Users will often begin to type a string, then backspace. You shouldn’t be sending the same autocomplete prefix multiple times while the user sends a single message.

Endpoint:

Return typeahead suggestions for the prefix passed

GET https://www.yammer.com/api/v1/autocomplete/ranked

“Accept: application/json” must be included as a header in the request.

Parameters:

prefix=string - A string for matching against the searchable fields in the specified models. For example, specifying the parameter prefix=ab would return autocomplete results for models that have searchable fields that begin with “ab”.

models=modelName:count -  Accepts a comma separated list of the models that should be searched on and the how many results should be returned for each model. This is specified in the format modelName1:count1,modelName2:count2 where count is an integer and modelName can be the following:

Both parameters above are required. If either is missing, a 400 – Bad Request is returned.

modelName Types:

user

group

topic

file

page (note)

open_graph_object

department

external_network

domain

For example, specifying the parameter models=user:5,group:5,open_graph_object:5 would return autocomplete results just for users, groups, and open graph objects and return up to 5 of each.

Invitations

Sends an email invitation to a user who has not yet joined the current user’s yammer network. If the current user is a verified admin in a paid yammer network, users with external email domains can be added. If the current user is not, only email addresses for official company domains will be allowed.

Endpoint:

Invites a user to the current user’s Yammer network.

POST https://www.yammer.com/api/v1/invitations.json
Parameter:

email - The email address of the user being invited. This can be specified multiple times to invite multiple users, or using email1 through email20.

Search

The search resource will return a list of messages, users, topics and groups that match the user’s search query.

Endpoints:

The example below searches for “”.

GET https://www.yammer.com/api/v1/search.json
Parameters:

search - The search query.

page - Only 20 results of each type will be returned for each page, but a total count is returned with each query. page=1 (the default) will return items 1-20, page=2 will return items 21-30, etc.

num_per_page - This allows you to limit the number of results of each type per page, up to a maximum of 20, the default value.

Networks

Facilitates switching a user between different Yammer networks. All Yammer web requests contain a network permalink in the URL (https://www.yammer.com/network_permalink/resource_path) to denote the network context. API requests use a different OAuth token for each user/network combination.

Endpoint:

Returns a list of networks to which the current user has access. Supports included_suspended parameter.

GET https://www.yammer.com/api/v1/networks/current.json
Parameters:

include_suspended=TRUE - Optional. Include networks the user is suspended in.

exclude_own_messages_from_unseen=TRUE - Optional. Exclude the user’s own messages from the unseen count. This is good for unread badges.