POST friendships/create

Updated on Wed, 2012-04-18 11:26

Allows the authenticating users to follow the user specified in the ID parameter.

Returns the befriended user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. If you are already friends with the user a HTTP 403 may be returned, though for performance reasons you may get a 200 OK message even if the friendship already exists.

Resource URL

http://api.twitter.com/1/friendships/create.format

Parameters

Providing either screen_name or user_id is required.

screen_name optional

The screen name of the user for whom to return results for. Helpful for disambiguating when a valid screen name is also a user ID.

Example Values: noradio

user_id optional

The ID of the user for whom to return results for. Helpful for disambiguating when a valid user ID is also a valid screen name.

Example Values: 12345

Note:: Specifies the ID of the user to befriend. Helpful for disambiguating when a valid user ID is also a valid screen name.

follow optional

Enable notifications for the target user.

Example Values: true

Extended description

The URL pattern /version/friendships/create/:screen_name_or_user_id.format is still accepted but not recommended. As a sequence of numbers is a valid screen name we recommend using the screen_name or user_id parameter instead.

Example Request

POST

https://api.twitter.com/1/friendships/create.json

POST Data

user_id=1401881

  1. {
  2.   "profile_sidebar_border_color": "87bc44",
  3.   "profile_sidebar_fill_color": "f2f8fc",
  4.   "profile_background_tile": false,
  5.   "name": "Doug Williams",
  6.   "created_at": "Sun Mar 18 06:42:26 +0000 2007",
  7.   "profile_image_url": "http://a3.twimg.com/profile_images/1119551297/dougw_avatar_normal.png",
  8.   "location": "San Francisco, CA",
  9.   "profile_link_color": "0000ff",
  10.   "follow_request_sent": false,
  11.   "is_translator": false,
  12.   "id_str": "1401881",
  13.   "url": "http://t.co/pqDlsTN",
  14.   "favourites_count": 1375,
  15.   "contributors_enabled": true,
  16.   "default_profile": false,
  17.   "id": 1401881,
  18.   "profile_image_url_https": "https://si0.twimg.com/profile_images/1119551297/dougw_avatar_normal.png",
  19.   "utc_offset": -28800,
  20.   "listed_count": 872,
  21.   "profile_use_background_image": true,
  22.   "profile_text_color": "000000",
  23.   "followers_count": 314103,
  24.   "lang": "en",
  25.   "protected": false,
  26.   "geo_enabled": true,
  27.   "time_zone": "Pacific Time (US & Canada)",
  28.   "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/2752608/twitter_bg_grass.jpg",
  29.   "description": "Partnerships at Twitter. Free spirit.",
  30.   "profile_background_color": "9ae4e8",
  31.   "notifications": false,
  32.   "verified": false,
  33.   "profile_background_image_url": "http://a1.twimg.com/profile_background_images/2752608/twitter_bg_grass.jpg",
  34.   "status": {
  35.     "coordinates": {
  36.       "coordinates": [
  37.         -122.406288,
  38.         37.78095
  39.       ],
  40.       "type": "Point"
  41.     },
  42.     "created_at": "Mon Jan 30 19:59:38 +0000 2012",
  43.     "favorited": false,
  44.     "truncated": false,
  45.     "id_str": "164075313838559232",
  46.     "in_reply_to_user_id_str": "352673744",
  47.     "text": "@R_Thaler a nudge to use fewer paper towels in the restroom. cc @garen http://t.co/BxxOugm0",
  48.     "contributors": null,
  49.     "id": 164075313838559232,
  50.     "retweet_count": 0,
  51.     "in_reply_to_status_id_str": null,
  52.     "geo": {
  53.       "coordinates": [
  54.         37.78095,
  55.         -122.406288
  56.       ],
  57.       "type": "Point"
  58.     },
  59.     "retweeted": false,
  60.     "in_reply_to_user_id": 352673744,
  61.     "possibly_sensitive": false,
  62.     "source": "<a href=\"http://www.apple.com\" rel=\"nofollow\">Photos on iOS</a>",
  63.     "place": {
  64.       "name": "SoMa",
  65.       "country_code": "US",
  66.       "country": "United States",
  67.       "attributes": {
  68.       },
  69.       "url": "http://api.twitter.com/1/geo/id/2b6ff8c22edd9576.json",
  70.       "id": "2b6ff8c22edd9576",
  71.       "bounding_box": {
  72.         "coordinates": [
  73.           [
  74.             [
  75.               -122.42284884,
  76.               37.76893497
  77.             ],
  78.             [
  79.               -122.3964,
  80.               37.76893497
  81.             ],
  82.             [
  83.               -122.3964,
  84.               37.78752897
  85.             ],
  86.             [
  87.               -122.42284884,
  88.               37.78752897
  89.             ]
  90.           ]
  91.         ],
  92.         "type": "Polygon"
  93.       },
  94.       "full_name": "SoMa, San Francisco",
  95.       "place_type": "neighborhood"
  96.     },
  97.     "possibly_sensitive_editable": true,
  98.     "in_reply_to_screen_name": "R_Thaler",
  99.     "in_reply_to_status_id": null
  100.   },
  101.   "friends_count": 1080,
  102.   "default_profile_image": false,
  103.   "statuses_count": 10179,
  104.   "screen_name": "dougw",
  105.   "following": true,
  106.   "show_all_inline_media": true
  107. }