Developer Preview: Contributor API

[Raffi Krikorian]

As you may have seen on our blog, we're starting a very small test of a new feature that will allow a Twitter account to have multiple "contributors".  This is the first in a suite of features that we'll be rolling out specifically targeted to the needs of businesses, and this particular feature is going to allow a business to invite employees and representatives to tweet, DM, follow users, etc., on behalf of the account holder.

While this feature is not ready for prime-time, and while we're not yet taking requests to be part of an early-access release while we work out the kinks, we're really committed to keeping our developers in the loop.  I want to give you all a heads up on what is coming on the API side, and, for this particular feature, I wanted to give you all a look at what we're calling the "Contributor API".  The reason I want to really highlight these changes is because we'll be making an addition to the status objects as this rolls out.

We'll be introducing a new parameter called contributingto to most API endpoints -- this parameter must be set to the user ID of the user that the employee or representative wants to take the action on behalf of.  If using contributingto, then the caller must authenticate when calling and must use OAuth.  For example, if I, @raffi, wanted to tweet on behalf of @twitter (ID 783214), I would call /status/update.xml, I would attach a parameter of contributingto=783214, and I would authenticate to that endpoint as myself using OAuth.  The API will confirm that @raffi has permission to contribute to the @twitter account, and will error with a 403 if that account does not.

You can expect to see contributingto show up as an optional parameter to the following endpoints (and presumably some more) when calling on http://api.twitter.com/1:

/account/rate_limit_status

/account/update_profile

/account/update_profile_background_image

/account/update_profile_colors

/account/update_profile_image

/account/verify_credentials

/blocks/blocking

/blocks/blocking/ids

/blocks/create

/blocks/destroy

/blocks/exists

/direct_messages

/direct_messages/destroy

/direct_messages/new

/direct_messages/sent

/favorites

/favorites/create

/favorites/destroy

/followers/ids

/friends/ids

/friendships/create

/friendships/destroy

/friendships/exists

/report_spam

/saved_searches

/saved_searches/create

/saved_searches/destroy

/saved_searches/show

/statuses/destroy

/statuses/followers

/statuses/friends

/statuses/friends_timeline

/statuses/home_timeline

/statuses/mentions

/statuses/public_timeline

/statuses/retweet

/statuses/retweeted_by_me

/statuses/retweeted_to_me

/statuses/retweets

/statuses/retweets_of_me

/statuses/show

/statuses/update

/statuses/user_timeline

/users/show

Lastly, the <status> objects will include an additional parameter named contributors that will have an user_id with the ID of the user who actually created this status object.  An example XML status would have

<status>

  ...

  <contributors>

    <user_id>ID of the contributor</user_id>

  </contributors>

  ...

</status>

and in JSON

{

  ...

  "contributors" : [ID of the contributor],

  ...

}

Due to caching, historical status objects may or may not contain the contributors, but all status created after launch will.

Like I said, more details to come!

--
Raffi Krikorian
Twitter Platform Team
http://twitter.com/raffi