Yammer API Documentation

Important: Read the Addendum to Yammer OAuth API concerning the recent OAuth Security Vulnerability

Beta API Notice

This release of the Yammer API is intended for beta testing. We're interested in feedback from application authors. During the beta period, we may have to change the interface. We'll do so as little as possible, and if we do need to change anything, we'll notify application developers in advance.

Introduction

The Yammer API is a RESTful interface to the features provided by the Yammer web interface.
We use OAuth for user authorization and application identification.

Detailed help with OAuth

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

Formats Supported

All resources available via the GET method support XML or JSON. Append .xml or .json where indicated by format.

Client Identification and Authentication

Yammer uses OAuth to authenticate clients. This allows applications to securely access data on a user's behalf without storing or needing the user's password. More information is provided below.

Rate Limit

Rate limits are imposed in the API. 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 &em; for example, if a user flips between "following", "sent" and "received" feeds quickly) &em;, 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 administrator of your network. To become a verified administrator you must first claim your network and then contact us so that we can verify your identity.

Changes and Versioning

All API changes will be mentioned and explained on the Yammer blog, and this documentation will be updated.

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.

The version of the API being used is indicated in the URLs of resources. For example, version 1.0 of the API is available at https://www.yammer.com/api/v1/...

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!"}}

General Notes

Timestamps are formatted according to RFC3339. For more information, please see http://tools.ietf.org/html/rfc3339.

Some clients may be using libraries which do not properly implement all HTTP request methods such as PUT, POST or DELETE. In order to accommodate these clients, we support the _method CGI parameter. If you can't send a real PUT, append ?_method=PUT to your request.

Some clients may also have trouble with HTTP status codes of 201, treating them as errors. If your HTTP library suffers from this problem, you can pass the parameter no_201=true along with any POST request. The server will return 200 codes everywhere a 201 is normally expected.

Overview

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

Detailed help with OAuth

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:

User goes to your site or opens your application.
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
```
Your application redirects the user to a special oauth authorization url, passing your REQUEST_TOKEN and SECRET.
```
https://www.yammer.com/oauth/authorize
```
User is asked to log in if they are not yet logged in
User is asked if they want to allow your application to access their data.
User is redirected back to your site/application's callback_url specified when you requested your application key here.
Your application requests a permanent ACCESS_TOKEN and SECRET by passing the REQUEST_TOKEN you were initially given.
```
https://www.yammer.com/oauth/access_token
```
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.

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. With this key you 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.com. When you use your API key, your client will be identified by name and this will be linked to your website.

You must be logged in to get an application key.

Bad Request

If your hexdigest, nonce string, or client name do not all match, your request will fail and generate an HTTP status 400 (Bad Request).

Examples

Ruby:

Requires oauth gem


 sudo gem install oauth

 require 'rubygems
 require 'oauth/consumer'

 consumer      = OAuth::Consumer.new CONSUMER_KEY, SECRET, {:site=>"https://www.yammer.com"}  
 request_token = consumer.get_request_token
 request_token.authorize_url # go to that url and hit authorize
 access_token  = request_token.get_access_token
 response      = access_token.get '/api/v1/messages.json'
 puts response.body

Ruby on Rails Controller

Requires oauth gem


 require 'oauth'
 require 'oauth/client'
 class OauthClientController < ApplicationController  
   CONSUMER_KEY    = 'pKo58Rj3j3LM8mAwN13V1w'
   CONSUMER_SECRET = 'TcaEpJQ92d8Vfa84eEcMS9mvtlp5KYxc8QClfDMiE'
   def index    
     if request.post?      
       consumer                     = get_consumer
       @request_token               = consumer.get_request_token
       session[:oauth_token]        = @request_token.token
       session[:oauth_token_secret] = @request_token.secret
       redirect_to @request_token.authorize_url # redirects user to https://www.yammer.com/authorize
     end        
   end      

   def callback
     consumer                     = get_consumer
     @request_token               = OAuth::RequestToken.new(consumer,session[:oauth_token],session[:oauth_token_secret])
     @access_token                = @request_token.get_access_token
     session[:oauth_token]        = @access_token.token
     session[:oauth_token_secret] = @access_token.secret        
   end                                                      

   def messages                     
     @access_token = OAuth::AccessToken.new(consumer,session[:oauth_token],session[:oauth_token_secret])
     @response     = @access_token.get '/api/v1/messages.json'
     if @response.is_a?(Net::HTTPSuccess)
       @api          = ActiveSupport::JSON::decode(@response.body)
     else
       flash[:error] = "Code: #{@response.code}, Error: #{ActiveSupport::JSON::decode(@response.body).pretty_print_inspect}"
       render :action => :error
     end
   end

   def get_consumer
     @consumer||=OAuth::Consumer.new(CONSUMER_KEY,CONSUMER_SECRET,:site => "https://www.yammer.com")
   end

 end

Perl:

Requires OAuth::Lite



 use OAuth::Lite::Consumer;
 $consumer_key    = 'pKo58Rj3j3LM8mAwN13V1w'
 $consumer_secret = 'TcaEpJQ92d8Vfa84eEcMS9mvtlp5KYxc8QClfDMiE'
 my $consumer = OAuth::Lite::Consumer->new(
        consumer_key       => $consumer_key,
        consumer_secret    => $consumer_secret,
        site               => q{https://www.yammer.com},
        request_token_path => q{/oauth/request_token},
        access_token_path  => q{/oauth/access_token},
        authorize_path     => q{https://www.yammer.com/oauth/authorize},
    );

  my $request_token = $consumer->get_request_token();

  ## Send user to page below
  $consumer->url_to_authorize(token => $request_token, callback_url => q{http://yourservice/callback});

  # Once user authorizes the request token, you can grab the access token
  my $access_token = $consumer->get_access_token( token => $request_token );

  my $res = $consumer->request(
      method => 'GET', 
      url    => q{https://www.yammer.com/api/v1/messages.json},
      token  => $access_token,
      params => { },
  );

  unless ($res->is_success) {
      if ($res->status == 400 || $res->status == 401) {
          my $auth_header = $res->header('WWW-Authenticate');
          if ($auth_header && $auth_header =~ /^OAuth/) {
              # access token may be expired,
              # get request-token and authorize again
          } else {
              # another auth error.
          }
      }
      # another error.
  }

  my $resource = $res->content;

PHP:


 PHP example on Google Code

C#:


 C# example on Github

Messages (Viewing)

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/messages.format	All messages in this network. Corresponds to the "All" tab on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/sent.format	Alias for /api/v1/messages/from_user/logged-in_user_id.format Corresponds to the "Sent" tab on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/received.format	Messages received by the logged-in user. Corresponds to the "Received" tab on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/following.format	Messages followed by the logged-in user. Corresponds to the "Following" tab on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/from_user/id.format	Messages sent by the user with the given ID. Corresponds to the messages on a user profile page on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/from_bot/id.format	Messages sent by the bot with the given ID. Corresponds to the messages on a bot profile page on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/tagged_with/id.format	Messages including the tag with given ID. Corresponds to the messages on a tag's page on the website.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/in_group/id.format	Messages in the group with the given ID. Corresponds to the messages you'd see on a group's profile page.	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/favorites_of/user_id.format	Favorite messages of the given user ID. Can pass 'current' in place of user_id for currently logged in user	older_than, newer_than, threaded
GET	https://www.yammer.com/api/v1/messages/in_thread/id.format	Messages in the thread with the given ID. Corresponds to the page you'd see when clicking on "in reply to" on the website.	older_than, newer_than

Parameters:

All of these resources return the same data structure and support the following CGI variables:

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

Return only the first message in each thread. This parameter is intended for applications which display message threads collapsed, as they are in our website's threaded mode.

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.

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 examples below are abbreviated to show only one example of each reference type, and only one message.

XML


 <response>
   <references>
     REFERENCE REPRESENTATIONS OF OBJECTS GO HERE
   </references>
   <messages>
     FULL REPRESENTATIONS OF OBJECTS GO HERE
   </messages>
   <meta>
     <older-available>true</older-available>
     <followed_user_ids>
      <followed_user_id>1</followed_user_id>
      <followed_user_id>2</followed_user_id>
     </followed_user_ids>
     <favorite_message_ids>
      <favorite_message_id>1</favorite_message_id>
      <favorite_message_id>2</favorite_message_id>
     </favorite_message_ids>
   </meta>
 </response>

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)

Resources:

Method	URL	Description	Parameters
POST	https://www.yammer.com/api/v1/messages/	Create a new message.	group_id, replied_to_id, body, attachment1...attachment20, direct_to_id
DELETE	https://www.yammer.com/api/v1/messages/id	Delete a message owned by the current user.

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.

attachmentn

Message attachments are supported by using a multi-part HTTP upload (see RFC1867). Use form element names attachment1 through attachment20.

Messages (Manipulating Favorites)

Resources:

Method	URL	Description	Parameters
POST	https://www.yammer.com/api/v1/favorites_of/user_id	Add a message to user_id's favorite messages.	message_id
DELETE	https://www.yammer.com/api/v1/favorites_of/user_id	Remove a favorite.	message_id

Parameters:

message_id=number

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

Groups

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/groups.format	A list of groups.	page, sort_by, letter, reverse
GET	https://www.yammer.com/api/v1/groups/id.format	View data about one group.
POST	https://www.yammer.com/api/v1/groups.format	Create a new group.	name, private
PUT	https://www.yammer.com/api/v1/groups/id.format	Modify an existing group.	name, private

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

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.

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/tags.format	Tags in this network. NOT YET IMPLEMENTED
GET	https://www.yammer.com/api/v1/tags/id.format	View data about one tag.

Users

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/users.format	Users in this network.	page, sort_by, reverse, letter
GET	https://www.yammer.com/api/v1/users/id.format	View data about one user.
GET	https://www.yammer.com/api/v1/users/current.format	Alias to /api/v1/users/current user's id.format.
GET	https://www.yammer.com/api/v1/users/by_email.format?email=user@domain.com	Set containing the single user who owns the address user@domain.com if that user exists in this network.
POST	https://www.yammer.com/api/v1/users.format	Create a new user. Must be an admin.	(See below)
PUT	https://www.yammer.com/api/v1/users/id.format	Update information about a user. Must be the logged-in user or an admin.	(See below)
DELETE	https://www.yammer.com/api/v1/users/id.format	Suspend or delete a user. Must be an admin.	delete

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

Group Memberships

Resources:

Method	URL	Description	Parameters
POST	https://www.yammer.com/api/v1/group_memberships.format	Join a group.	group_id
DELETE	https://www.yammer.com/api/v1/group_memberships/id.format	Leave a group.	group_id

Parameters:

group_id=number

The group_id you are joining or leaving.

Relationships (Org chart)

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/relationships.format	Show org chart relationships.	user_id
POST	https://www.yammer.com/api/v1/relationships.format	Add an org chart relationship.	user_id, subordinate, superior, colleague
DELETE	https://www.yammer.com/api/v1/relationships/id.format?type=relationship_type	Remove a relationship.	user_id, relationship_type

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.

Suggestions

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/suggestions.format	Show suggested groups and users.
GET	https://www.yammer.com/api/v1/suggestions/users.format	Show only suggested users.
GET	https://www.yammer.com/api/v1/suggestions/groups.format	Show only suggested groups.
DELETE	https://www.yammer.com/api/v1/suggestions/id.format	Decline a suggestion.	id

Parameters:

id

When declining a suggestion, pass its ID.

Subscriptions

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/subscriptions/to_user/id.format	Check to see if you are subscribed to the user of the given id.
GET	https://www.yammer.com/api/v1/subscriptions/to_tag/id.format	Check to see if you are subscribed to the tag of the given id.
POST	https://www.yammer.com/api/v1/subscriptions/	Subscribe to a user or tag.	target_type, target_id
DELETE	https://www.yammer.com/api/v1/subscriptions/	Unsubscribe to a user or tag.	target_type, target_id

Parameters:

target_type=type&target_id=number

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

Autocomplete

Resources:

Method	URL	Description	Parameters
GET	https://www.yammer.com/api/v1/autocomplete.format	Return typeahead suggestions for the prefix passed	prefix

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.

Usage

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.

Invitations

Resources:

Method	URL	Description	Parameters
POST	https://www.yammer.com/api/v1/invitations.format	Invites a user to the logged-in user's Yammer network.	email

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.

Usage

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.

Oauth Access Tokens (Admin Only)

Resources:

Method	URL	Description	Parameters
POST	https://www.yammer.com/api/v1/oauth.format	Returns a preauthorized oauth access token for a given user_id/consumer_key combination.	user_id, consumer_key

Parameters:

user_id=string

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

consumer_key=string

The application's consumer key.

Usage

This is a feature for network admins only. It 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 is a feature for network admins only. It allows you to request valid access tokens for your users to use a particular API client application.

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

Message

Full


 <message>
   <id>1102</id>
   <group-id>1201</group-id>
   <direct-to-id>1005</direct-to-id>
   <url>https://www.yammer.com/api/v1/messages/1102</url>
   <web-url>https://www.yammer.com/messages/1102</web-url>
   <replied-to-id>1101</replied-to-id>
   <thread-id>1101</thread-id>
   <body>
     <plain>I love #yammer.</plain>
     <parsed>I love [[tag:1000]].</parsed>
   </body>
   <attachments>
     <attachment>
       <type>image</type>
       <id>1301</id>
       <name>network-topology.png</name>
       <web-url>https://www.yammer.com/images/1301</web-url>
       <image>
         <size>37235</size>
         <url>https://www.yammer.com/api/v1/images/1301</url> 
         <thumbnail-url>https://www.yammer.com/api/v1/images/1301/small</thumbnail-url> 
       </image>
     </attachment>
     <attachment>
       <type>file</type>
       <id>1302</id>
       <name>sales-data.xls</name>
       <size>29182109</size>
       <web-url>https://www.yammer.com/files/1302</web-url>
       <file>
         <size>37235</size>
         <url>https://www.yammer.com/api/v1/files/1302</url> 
       </file>
     </attachment>
   </attachments>
   <message-type>update</message-type>
   <client-type>web</client-type>
   <sender-id>1002</sender-id>
   <sender-type>user</sender-type>
   <created-at>2008-09-12T17:35:43Z</created-at>
 </message>

Reference


 <reference>
   <type>message</type>
   <id>1101</id>
   <url>https://www.yammer.com/api/v1/messages/1101</url>
   <web-url>https://www.yammer.com/messages/1101</web-url>
   <replied-to-id nil="true">/>
   <direct-to-id>1005</direct-to-id>
   <body>
     <plain>Welcome to the Geni network!</plain>
   </body>
   <sender-id>1</sender-id>
   <sender-type>guide</sender-type>
   <created-at>2008-09-12T17:35:43Z</created-at>
 </reference>

sender-type: The sender's object type: user, bot, or guide. The guide is a virtual user that exists in the system to send messages such as the tips and initial welcome message. Bots are automated virtual users that can perform tasks like reposting items from an RSS feed as Yammer messages.
sender-id: The ID of the message's sender.
group-id: (Optional) When a message is posted into a group, that group's ID will appear here and the group will be available in the references section.
direct-to-id: (Optional) When a message is a private 1-to-1 (or "direct") message, this will indicate the intended recipient.
replied-to-id: The ID of the message this message is in reply to, if applicable.
thread-id: The thread in which this message appears.
body:
- plain: A plaintext version of the message body.
- parsed: A version of the message body with #tags and @users replaced by [[object:id]]. This is not present in the reference version of a message.
message-type: This will be system or update. A system message is automatically generated by the system and describes an action, such as "Kris Gale has joined the Geni network." An update message is a regular message posted by a user such as "Kris Gale: Hi everyone." Put simply, this indicates whether a colon will separate the body of the message from the sender's name in the web interface.
attachments: A list of attachments for this message. (See below)

All #tags, @users and @groups replaced by [[tag:id]], [[user:id]] or [[group:id]] in a message body will be present in that request's references section.

The following regular expression may be handy in parsing out the reference placeholders in messages: /\[\[([^\[\]]*?)\]\]/ Note that the caret (^) indicates negation of a character class, as it does in Ruby or Perl. Your regexp impelementation may require an exclamation point (!).

Implementing Message Attachments in Your Client:

All attachments, regardless of type, will provide the following attributes:

type: Indicates the type of attachment. Current options: image and file
id: Numerical idenifier for this attachment.
name: Short text identifier which may not be unique.
web-url: Where the attachment can be viewed on the Yammer website.

This information will allow a client to support any present or future message attachment types without having to be updated. We recommend all clients display the name hyperlinked to the web-url for attachments of types they do not have special features to handle. This will allow users of your client to see new attachment types we may add in the future.

For a more seamless integration of attachments, we will provide additional information specific to its type. In the example message above, note that the file and image attachments both have a section named after their respective types which includes data such as size, url (for both types), and thumbnail (for images). This information will allow clients supporting those attachment types to download them directly instead of using the web-url.

User

Full


 <response>
   <type>user</type>
   <id>1002</id>
   <name>kgale</name>
   <full-name>Kris Gale</full-name>
   <mugshot-url>https://www.yammer.com/user_uploaded/photos/p1/0000/0001/k.jpg</mugshot-url>
   <url>https://www.yammer.com/api/v1/users/1002</url>
   <web-url>https://www.yammer.com/users/kgale</web-url>
   <job-title>Senior Engineer</job-title>
   <location>Los Angeles, CA</location>
   <contact>
     <email-addresses>
       <email-address>
         <type>primary</type>
         <address>nospam@geni.com</address>
       </email-address>
       <email-address>
         <type>personal</type>
         <address>nospam@gmail.com</address>
       </email-address>
     </email-addresses>
     <phone-numbers>
       <phone-number>
         <type>work</type>
         <number>555-123-1234 x7</number>
       </phone-number>
       <phone-number>
         <type>mobile</type>
         <number>555-321-4321</number>
       </phone-number>
     </phone-numbers>
     <im>
       <username>kgale@example.com</username>
       <provider>jabber</provider>
     </im>
   </contact>
   <external-urls>
      <external-url>http://www.linkedin.com/pub/b/577/abb</external-url>
   </external-urls>
   <previous-companies>
      <previous-company>
         <employer>Innotech</employer>
         <position>Software Engineer</position>
         <description>Created TPS Reports</description>
         <start-year>2006</start-year>
         <end-year>2008</end-year>
      </previous-company>
   </previous-companies>
   <schools>
      <school>
         <school>University of Southern California</school>
         <degree>BS</degree>
         <description>Computer Science</description>
         <start-year>2002</start-year>
         <end-year>2006</end-year>
      </school>
   </schools>
   <birth-date>March 18</birth-date>
   <hire-date>2008-03-15</hire-date>
   <interests>These are my interests</interests>
   <expertise>This is my expertise</expertise>
   <summary>This is my summary</summary>
   <timezone>US/Pacific</timezone>
   <state>active</state>
   <network-id>1</network-id>
   <network-name>geni.com</network-name>
   <network-domains>
      <network-domain>geni.com</network-domain>
   </network-domains>
   <stats>
      <updates>174</updates>
      <followers>20</followers>
      <following>6</following>
   </stats>
 </response>

Reference


 <reference>
   <type>user</type>
   <id>1002</id>
   <name>kgale</name>
   <full-name>Kris Gale</full-name>
   <mugshot-url>https://www.yammer.com/user_uploaded/photos/p1/0000/0001/k.jpg</mugshot-url>
   <url>https://www.yammer.com/api/v1/users/1002</url>
   <web-url>https://www.yammer.com/users/kgale</web-url>
   <job-title>Senior Engineer</job-title>
   <stats>
     <updates>174</updates>
     <followers>20</followers>
     <following>6</following>
   </stats>
 </reference>

name: The username of this user.
full-name: The user's full name.
mugshot-url: The URL of this user's picture.

Extra Information When Viewing The Logged-In User

Using the path /api/v1/users/current will show the following extra information:


 <user>
   [ ...All information as above in the full representation... ]
   <web-preferences>
     <show-full-names>true</show-full-names>
     <hide-avatars>false</hide-avatars>
     <enter-does-not-submit-message>false</enter-does-not-submit-message>
     <absolute-timestamps>false</absolute-timestamps>
   </web-preferences>
   <group-memberships>
     [ Group references ]
   </group-memberships>
   <subscriptions>
     [ Subscription references ]
   </subscriptions>
 </user>

web-preferences: Exposes the user's settings from the Yammer website, allowing your client to keep in sync with the user's preferences.
- show-full-names: Toggles the display of full names (Kris Gale) instead of usernames (kgale) when viewing messages.
- hide-avatars: Suppresses the display of user mugshots.
- enter-does-not-submit-message: Toggles whether pressing enter in the update form will submit a message or insert a newline.
- absolute-timestamps: Toggles timestamps between absolute and relative.
group-memberships: A list of reference representations of groups to which this user belongs.
subscriptions: A list of reference representations of this user's subscriptions to tags and users.

Group

Full


 <group>
   <type>group</type>
   <id>1</id>
   <full-name>Sales Team</full-name>
   <name>salesteam</name>
   <privacy>public</privacy>
   <url>https://www.yammer.com/api/v1/groups/1</url>
   <web-url>https://www.yammer.com/groups/salesteam</web-url>
   <stats>
     <members>5</members>
     <updates>102</updates>
   </stats>
 </group>

Reference

(Same as full.)

full-name: Name given to this group.
name: Shortened name of this group. Used in references (@salesteam), addressing (to:salesteam), the email address for group updates (salesteam@yammer.com) and the web URL (www.yammer.com/groups/salesteam).
privacy: Either public or private, to indicate whether updates are visible to non-members (public) and whether joining requires a group admin's approval (private).

Guide

Full

(Not available.)

Reference


 <reference>
   <type>guide</type>
   <id>1</id>
   <name>yammer</name>
   <full-name>yammer</full-name>
   <mugshot-url>https://www.yammer.com/images/guide_photo_small.gif</mugshot-url>
   <web-url>https://www.yammer.com/about</web-url>
 </reference>

The structure should match a regular user, but the guide is responsible for sending tips and other system-generated messages that aren't specific to one user.

Bot

Full

(Not available.)

Reference


 <reference>
   <type>bot</type>
   <id>1</id>
   <name>rss-bot</name>
   <full-name>RSS Bot</full-name>
   <mugshot-url>https://www.yammer.com/images/feed_icon_small.jpg</mugshot-url>
   <web-url>https://www.yammer.com/rss_feeds/42</web-url>
   <created-at>2009-02-12T17:35:43Z</created-at>
 </reference>

The structure is similar to a regular user, but the bot is a limited virtual account without all the fields and functionality of a user.

Tag

Full


 <response>
   <type>tag</type>
   <id>1000</id>
   <stats>
     <followers>10</followers>
     <updates>7</updates>
   </stats>
   <name>yammer</name>
   <url>https://www.yammer.com/api/v1/tags/1000</url>
   <web-url>https://www.yammer.com/tags/yammer</web-url>
 </response>

Reference


 <reference>
   <type>tag</type>
   <id>1000</id>
   <name>yammer</name>
   <url>https://www.yammer.com/api/v1/tags/1000</url>
   <web-url>https://www.yammer.com/tags/yammer</web-url>
 </reference>

followers: (Only in full) This indicates how many users are following a given tag.

Thread

Full

(Not available.)

Reference


 <reference>
   <type>thread</type>
   <id>1005</id>
   <url>https://www.yammer.com/api/v1/messages/in_thread/1005</url>
   <web-url>https://www.yammer.com/threads/1005</web-url>
   <stats>
     <updates>2</updates>
     <latest-reply-at>2008-09-12T17:35:43Z</latest-reply-at>
   </stats>
 </reference>

updates: The number of messages in this thread.
latest-reply-at: Timestamp of the most recent message in this thread.

Subscription

Full


 <response>
   <url>https://www.yammer.com/api/v1/subscriptions/1201</url>
   <type>subscription</type>
   <target-web-url>https://www.yammer.com/tags/yammer-tips</target-web-url>
   <target-type>tag</target-type>
   <target-url>https://www.yammer.com/api/v1/tags/1000</target-url>
 </response>

Reference

(Not available.)

updates: The number of messages in this thread.
latest-reply-at: Timestamp of the most recent message in this thread.

Autocomplete

Full


 <response>
   <tags>
     <tag>
       <name>address</name>
       <id>1002</id>
       <messages>10</messages>
       <followers>2</followers>
     </tag>
   </tags>
   <groups>
     <group>
       <name>adsales</name>
       <full-name>Ad Sales</full-name>
       <id>1108</id>
       <messages>57</messages>
       <members>7</members>
     </group>
   </groups>
   <users>
     <user>
       <name>apisoni</name>
       <full-name>Adam Pisoni</full-name>
       <id>1501</id>
       <messages>1203</messages>
       <followers>15</followers>
     </user>
     <user>
       <name>jadams</name>
       <full-name>John Adams</full-name>
       <id>1502</id>
       <messages>1001</messages>
       <followers>10</followers>
     </user>
   </users>
 </response>

Reference

(Not available.)

Invitation

(Not yet available.)

Oauth Access Tokens (Admin Only)

Full


  <response>
    <oauth-token-secret>bFtQPallbt36TfPWhs3cL2rBm5H82N2j6pBmpRLZyk</oauth-token-secret>
    <oauth-token>wC6tMnK3u8DNvtsR4SU4YA</oauth-token>
  <response>

Reference

(Not available.)

Yammer API Documentation

General Notes

Beta API Notice

Introduction

Formats Supported

Client Identification and Authentication

Rate Limit

Message Resources

Autocomplete

Other Resources

Administrative API Functions

Changes and Versioning

General Notes

OAuth Information

Overview

Obtain a Client Key

Bad Request

Examples

Ruby:

Ruby on Rails Controller

Perl:

PHP:

C#:

Supported Resources

Messages (Viewing)

Resources:

Parameters:

older_than=id

newer_than=id

threaded=true

Response:

XML

Messages (Manipulating)

Resources:

Parameters:

body=text

group_id=id

replied_to_id=id

direct_to_id=user_id

attachmentn

Messages (Manipulating Favorites)

Resources:

Parameters:

message_id=number

Groups

Resources:

Parameters:

page=number

letter=letter

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

reverse=true

name=string

private=true

Tags

Resources:

Users

Resources:

Parameters:

page=number

letter=letter

sort_by=[ messages | followers ]

reverse=true

delete=true

Parameters for creating or updating users

Group Memberships

Resources:

Parameters:

group_id=number

Relationships (Org chart)

Resources:

Parameters:

user_id=number

[ subordinate | superior | colleague ]=email_address

id=number

type=relationship_type

Suggestions

Resources:

Parameters:

id

Subscriptions