Yammer API Documentation

Introduction - Welcome! close section open section
The Yammer API is a RESTful interface to the features provided by the Yammer web interface.
OAuth is used for all user authorization and application identification, the first step in gaining access to the API is registering your application and going through the OAuth process.

See also: http://en.wikipedia.org/wiki/REST
See also: http://oauth.net/

All resources support JSON (Recommended) and XML. The documentation allows you to shift from JSON to XML where relevant.

All timestamps are formatted according to RFC3339.

Rate Limits

All API calls are subject to rate limiting. Exceeding any rate limits will result in all resources returning a status code of 403 (Forbidden). Our specific rate limits are subject to change, but following these guidelines will ensure that your application will not exceed our limits.

Message Resources

When polling for messages, do not exceed one poll per minute. Clients polling excessively will be blocked. However, you may sometimes need to fetch messages more frequently than once per minute, for example, if a user flips between "following", "sent" and "received" feeds quickly), and this is allowed for a few requests. Do not attempt to decrease message latency in your client by checking for new messages more frequently than once per minute.

Autocomplete

The autocomplete resources allow more frequent polling than other resources, as they are meant to enable realtime responses for the user as she types. See the notes in the autocomplete section below for suggestions on how to use this feature of the API.

Other Resources

The 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.

Administrative API Functions

In order to perform administrative API functions, such as creating and deleting users, your API account must be a Verified Admin of your network. Please see the Yammer admin page for more information.

Changes and Versioning

Developers should expect that new elements could be added to the XML document or the JSON data structure. If any data structures are removed or rearranged, we will release a new version of the API.

All API urls begin with /api/v1. The version of the API being used is indicated in the URLs of resources. We may add additional functionality to the current version of the API but we will not make reverse incompatible changes to it.

Developers should anticipate the ordering of items within the data structures changing and code appropriately. Expect, for example, that the order of the foo and bar items in the excerpts below might be swapped:
XML
```
  <things>
                  <foo>Foo!</foo>
                  <bar>Bar!</bar>
              </things>
```
JSON
```
     {"things": {"foo": "Foo!", "bar": "Bar!"}}
```
OAuth - Everyone's favorite authorization standard. close section open section
Basics

You can read the full OAuth specs here or view the diagram.

Basically, OAuth will allow your application to access a user's data with a special key/secret pair that the user will authorize specifically for your application. The client libraries will handle most of this process for you. The process looks like this:
1. User goes to your site or opens your application.
2. Behind the scenes you request a REQUEST_TOKEN and SECRET from yammer by passing your CONSUMER_KEY (application key) to https://www.yammer.com/oauth/request_token.
  Show example.
3. Your application redirects the user to a special oauth authorization url, passing your REQUEST_TOKEN and SECRET. https://www.yammer.com/oauth/authorize?oauth_token=REQUEST_TOKEN.
4. User is asked to log in if they are not yet logged in
5. User is asked if they want to allow your application to access their data.
6. User is shown a short alphanumeric code, called the oauth_verifier, and instructed to go back to your application.
7. User goes back to your application and enters the oauth_verifier code into your application or web site.
8. Your application requests a permanent ACCESS_TOKEN and SECRET by passing the REQUEST_TOKEN you were initially given along with the oauth_verifier to: https://www.yammer.com/oauth/access_token.
  Show example.
9. Your application can now access the API as per the permissions granted to you by the user by signing each request with the user's ACCESS_TOKEN and SECRET obtained from the POST response.
  Show example.
Obtain a Client Key

In order to access the Yammer API you must first obtain a client application key and secret which you will use to identify your application. You can get a key here (you must be logged in to yammer) that will only have access to your own network. If you would like your application to be able to access additional networks, or would like to make it available for public use, please send your registered email address, and client key to api@yammer-inc.com. When you use your API key, your client will be identified by name and this will be linked to your website.

Bad Request

If your hexdigest, client name, secret and token do not all match, your request will fail and generate an HTTP status 400 (Bad Request). Read the body of the response to find out what part of the request failed.

Object Representations

Objects within the Yammer system are represented in two ways: As a reference or a full object. References are used when one object refers to another, and data about the referenced object would be useful. This avoids redundancy in what is returned. For example, a page of messages may include 20 messages from the same user. Each message will indicate that it was sent by a user and that user's ID, and the references section will include that user only once and include the name and mugshot (profile picture) URL.

Note: Some objects do not have full representations because there are no API resources dedicated to fetching them.
Common Attributes
- type: The object type, such as user, tag, etc.
- id: The ID number for this object. Note that IDs are not unique across all object types: there may be a user and tag with the same numerical ID.
- url: The API resource for fetching this object.
- web-url: The URL for viewing this object on the main Yammer website.
- created-at: The time and date this resource was created. This would indicate when a user joined the network or when a message was posted.
Messages (Viewing) - Retrieving direct and public messages.. close section open section

Common Parameters

All of the messages APIs return a similar structure and support the following common query parameters.

older_than=id

Returns only messages older than the message ID specified. 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 HTTP request to get the 20 messages prior to those you're seeeing.

newer_than=id

Return only messages newer than the message ID specified. This should always be used when polling for new messages. If you're looking at a message resource, and the most recent message returned is 3516, you could make requests 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 applications 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 our website.

Note: A strict rate limit is applied to all API requests, so clients should never poll for new messages more frequently than every 30 seconds to ensure that the user is still able to use the API for posting messages, etc.

limit=number

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

Rate Limits

Developers should note that a strict rate limit is applied to all API requests, so clients should never poll for new messages more frequently than every 30 seconds to ensure that the user is still able to use the API for posting messages, etc.

Resources

All messages in this network. Corresponds to the "Company Feed" tab on the website.

Alias for /api/v1/messages/from_user/logged-in_user_id.format. Corresponds to the "Sent" tab on the website.

Messages received by the logged-in user. Corresponds to the "Received" tab on the website.

Private Messages (aka Direct Messages) for the logged-in user. Corresponds to the "Direct Messages" section on the website.

Messages followed by the logged-in user. Corresponds to the "My Feed" tab on the website.

Messages sent by the user with the given ID. Corresponds to the messages on a user profile page on the website.

Messages including that have the topic with given ID. Corresponds to the messages on a topic's page on the website. This is a newer API and the response body may differ slightly from other response bodies.

Messages in the group with the given ID. Corresponds to the messages you'd see on a group's profile page.

Liked messages of the given user ID. Can pass 'current' in place of id for currently logged in user.

Messages in the thread with the given ID. Corresponds to the page you'd see when clicking on "in reply to" on the website. Does not accept the threaded parameter.

Response:

All of the above resources will return messages in the same structure. A response will return up to 20 qualifying messages. To fetch more than 20, you will need to make a second request and pass older_than as described above.

The older-available element indicates whether messages older than those shown are available to be fetched. See the older_than parameter mentioned above.

The followed_user_ids element contains an array of user_ids corresponding to the the returned message senders being followed by the current user.

The favorite_message_ids element contains an array of message_ids corresponding to returned messages which are favorites of the current user.
Messages (Manipulating) - Create and delete public and private messages. close section open section
POST messages are form encoded. DELETE requests should use querystring parameters. If your client does not support the DELETE method you can do a POST with the parameter _method=DELETE.

Parameters:
body=text

The text of the message body.

group_id=id

The ID of the group in which this message belongs.

replied_to_id=id

The message ID this message is in reply to, if applicable.

direct_to_id=user_id

This will send a private message directly to the user indicated.

broadcast=true

This message should be broadcasted to all users. Must be an admin.

topicn

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

attachmentn and pending_attachmentn

We provide two methods to associate attachments with a message. Both make user of multi-part HTTP upload (see RFC1867) but do so at different stages. The first method is the easiest, simply use file from 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 to upload attachments is to use the Pending Attachments resource allowing attachments to be uploaded in parallel. Clients 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 Object as an attachment. The og_url parameter is required and all other parameters are optional. If og_fetch is true then the server will fetch the page at the URL and attempt to populate the other 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 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.
- 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)
The default rendering of an Open Graph Object attachment is:
Resources:

Create a new message. The response body will include the new message formatted as in message polling above. This allows you to immediately display the newly-posted message back to the user.

Removes a message. Must be owned by the current user.
Messages (Email) - Sending emails to the current user. close section open section

Parameters:

message_id=number

Id of message to send to the current user.

Resources:

Send current_user a copy of this message.
Likes - Like is the new Favorite. close section open section

Parameters:

POST messages are form encoded.

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

message_id=number

Liked message of the given user ID. Can pass 'current' in place of user_id for currently logged in user.

Resources:

Add a message to user_id's liked messages.

Remove a message of user_id's liked messages.
Groups - View and modify group information. close section open section

Parameters:

page=number

20 groups will be shown per page.

letter=letter

Return groups beginning with the given letter.

sort_by=[ messages | members | privacy | created_at | creator ]

Results will be returned sorted by one of the above options instead of the default behavior of sorting by number of messages.

reverse=true

Return results in reverse order.

name=string

The name of this group. Used when creating or updating groups.

private=true

Optional. Used when creating or updating groups to make them private.

Resources:

A list of groups. Supports page, sort_by, letter, and reverse parameters.

View data about one group.

Create a new group. Supports name and private parameters.

Modify an existing group. Supports name and private parameters.
Topics - Topics are the new Tags. close section open section

Resources:

Get topic information by id.

Create a new topic in this network.
Users - Create, modify and delete users. close section open section
Parameters:
page=number

50 users will be shown per page.

letter=letter

Return users beginning with the given letter.

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

Return 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
- 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
Resources:

Users in this network. Supports page, sort_by, reverse, and letter parameters.

View data about one user.

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

Create a new user. Must be an admin.

Update information about a user. Must be the logged-in user or an admin.

Suspend or delete a user. Must be an admin.
Group Memberships - Add and remove users from groups. close section open section

Parameters:

group_id=number

The group_id you are joining or leaving.

Resources:

Join a group.

Leave a group.
Relationships (Org chart) - View and modify the org chart of users in a network. close section open section

Parameters:

user_id=number

Allows you 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=number

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.

Resources:

Show org chart relationships. Supports user_id

Add an org chart relationship. Supports user_id, subordinate, superior, and colleague parameters.

Remove a relationship. Supports user_id and relationship_type parameters.
Suggestions - View and decline suggestions for following. close section open section

Parameters:

limit=number

Return only the specified number of suggestions.

id

When declining a suggestion, pass its ID.

Resources:

Show suggested groups and users.

Decline a suggestion.
Threads - Viewing threads. close section open section

Parameters:

id

The ID of the thread to show.

Resources:

Show details about a message thread.
Subscriptions - Manage subscriptions to topics, threads, and users. close section open section

Parameters:

target_type=type&target_id=number

The target type (user or tag) and ID to which you are subscribing or unsubscribing.

Resources:

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.

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.

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

Subscribe to a user or tag. Supports target_type and target_id parameters.

Unsubscribe to a user or tag. Supports target_type and target_id parameters.
Autocomplete - Beef up your interface with autocomplete. close section open section

The autocomplete feature is useful for giving suggestions to users when they begin to type something that looks like the name of a tag, group or user. This is most useful in composing messages. 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.

Parameters:

prefix=string

The partial string from which autocomplete suggestions will be generated. A bare string such as foo will return groups, users and tags. Prefixes can be used to limit the results: @foo will return only users, #foo will return only tags, and to:foo will return users and groups.

Resources:

Return typeahead suggestions for the prefix passed
Invitations - Invite users to your network. close section open section

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

Parameters:

email=string

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

Resources:

Invites a user to the logged-in user's Yammer network.
Search -Find stuff in your network. close section open section

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

Parameters:

search=string

The search query.

page=number

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=number

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

Resources:

Search for Yammer content. Supports search, page, and num_per_page parameters.
Networks - View all the networks for a user. close section open section

This 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.

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.

Resources:

Returns a list of networks to which the logged-in user has access. Supports included_suspended parameter.
Oauth Access Tokens - Manage your OAuth access tokens. close section open section

This feature allows you to request valid access tokens for your users to use a particular API client application. This would be useful if your intranet website or desktop image included a Yammer client and you would like to set it up ahead of time and save the user the trouble of walking through the normal API flow. This also facilitates implementing fast user switching between network contexts, without requiring the user to perform the OAuth flow for each network in which they are a member.

Creating a pre-authorized token and retrieving the tokens for a user other than the currently logged in user is restricted to verified admin accounts only. Non-admins may only perform the GET action and may not include the user_id or consumer_key parameters. If the consumer_key is not included it will be read from the OAuth headers, therefore non-admins may not request this resources if they are not authenticated with OAuth.

Parameters:

user_id=string

The user_id for whom we're authorizing this client application.

consumer_key=string

The application's consumer key.

Resources:

Generates (if necessary) and returns a list of authorized oauth access tokens for each network which the user is a member. Supports user_id and consumer_key parameters. Verified Admins may use the user_id and consumer_key parameters to generate tokens on behalf of other users.

Verified Admins Only.

Returns a preauthorized oauth access token for a given user_id/consumer_key combination. Supports user_id and consumer_key parameters.
Pending Attachments close section open section

Parameters:

attachment

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

Resources:

Create a new pending attachment.

Delete a pending attachment owned by the current user.

Introduction - Welcome! close section open section

Rate Limits

Message Resources

Autocomplete

Other Resources

Administrative API Functions

Changes and Versioning

OAuth - Everyone's favorite authorization standard. close section open section

Basics

Obtain a Client Key

Bad Request

Object Representations

Common Attributes

Messages (Viewing) - Retrieving direct and public messages.. close section open section

Common Parameters

older_than=id

newer_than=id

threaded=true/extended

limit=number

Rate Limits

Resources

Response:

Messages (Manipulating) - Create and delete public and private messages. close section open section

Parameters:

body=text

group_id=id

replied_to_id=id

direct_to_id=user_id

broadcast=true

topicn

attachmentn and pending_attachmentn

og_<property>

Resources:

Messages (Email) - Sending emails to the current user. close section open section

Parameters:

message_id=number

Resources:

Likes - Like is the new Favorite. close section open section

Parameters:

message_id=number

Resources:

Groups - View and modify group information. close section open section

Parameters:

page=number

letter=letter

sort_by=[ messages | members | privacy | created_at | creator ]

reverse=true

name=string

private=true

Resources:

Topics - Topics are the new Tags. close section open section

Resources:

Users - Create, modify and delete users. close section open section

Parameters:

page=number

letter=letter

sort_by=[ messages | followers ]

reverse=true

delete=true

Parameters for creating or updating users

Resources:

Group Memberships - Add and remove users from groups. close section open section

Parameters:

group_id=number

Resources:

Relationships (Org chart) - View and modify the org chart of users in a network. close section open section

Parameters:

user_id=number

[ subordinate | superior | colleague ]=email_address

id=number

type=relationship_type

Resources:

Suggestions - View and decline suggestions for following. close section open section

Parameters:

limit=number

id

Resources:

Threads - Viewing threads. close section open section

Parameters:

id