POST friendships/create

Allows the authenticating user to follow (friend) the user specified in the ID parameter.

Returns the followed user when successful. Returns a string describing the failure condition when unsuccessful. If the user is already friends with the user a HTTP 403 may be returned, though for performance reasons this method may also return a HTTP 200 OK message even if the follow relationship already exists.

Actions taken in this method are asynchronous. Changes will be eventually consistent.

Resource URL

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

Resource Information

Response formats JSON
Requires authentication? Yes (user context only)
Rate limited? Yes
Requests / 24-hour window 1000 per user; 1000 per app*

Please note - The 1000 per app rate limit goes into effect on October 22nd, 2018. You can learn more about this change by reading our recent forum post.

Parameters

Name Required Description Default Value Example
screen_name optional The screen name of the user to follow.   twitterdev
user_id optional The ID of the user to follow.   12345
follow optional Enable notifications for the target user.   true

Example Request

curl --request POST 
--url 'https://api.twitter.com/1.1/friendships/create.json?user_id=USER_ID_TO_FOLLOW&follow=true' 
--header 'authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY", oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP", oauth_token="USERS_ACCESS_TOKEN", oauth_version="1.0"' 
--header 'content-type: application/json'

Example Response

{user-object,
  "status": {tweet-object}
}