Social Features
chevron down
 

Friends

Get Friends

The Get Friends endpoint returns data of a user's friends in the format requested using units in the unit system which corresponds to the Accept-Language header provided.

Privacy Settings

The Fitbit privacy setting, My Friends (Private, Friends Only or Public), determines the access to a user's list of friends.

Resource URL

GET https://api.fitbit.com/1.1/user/[user-id]/friends.json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.

Examples of Requests

Here are two accepted formats for retrieving user's friends data:

GET https://api.fitbit.com/1.1/user/28H22H/friends.json
GET https://api.fitbit.com/1.1/user/-/friends.json

Request Headers

Accept-Language optional The measurement unit system to use for response values.

Example Response

{
 "data": [
   {
     "type": "person",
     "id": "1236K9",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": true,
       "name": "Nick"
     }
   },
  {
     "type": "person",
     "id": "GGNJL9",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": true,
       "name": "Alan"
     }
   }
 ]
}


Get Friends Leaderboard

The Get Friends Leaderboard endpoint gets the user's friends leaderboard in the format requested using units in the unit system which corresponds to the Accept-Language header provided.

Authorized user (self) is also included in the response. Leaderboard has last seven (7) days worth of data (including data from the previous six days plus today's data in real time).

Privacy Settings

The Average Daily Step Count privacy setting allows a user to be included to Friends leaderboard whether he hides himself on his profile settings or not. There are two privacy settings to consider for the response data:

Resource URL

GET https://api.fitbit.com/1.1/user/[user-id]/leaderboard/friends.json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional The measurement unit system to use for response values.

Example Response

{
 "data": [
   {
     "type": "ranked-user",
     "id": "22JP9H",
     "attributes": {
       "step-rank": 1,
       "step-summary": 6392.0
     },
     "relationships": {
       "user": {
         "data": {
           "type": "person",
           "id": "22JP9H"
         }
       }
     }
   },
   {
     "type": "ranked-user",
     "id": "32FKD5",
     "attributes": {
       "step-rank": 2,
       "step-summary": 5205.0
     },
     "relationships": {
       "user": {
         "data": {
           "type": "person",
           "id": "32FKD5"
         }
       }
     }
   },
   {
     "type": "inactive-user",
     "id": "33KF8Z",
     "relationships": {
       "user": {
         "data": {
           "type": "person",
           "id": "33KF8Z"
         }
       }
     }
   }
 ],
 "included": [
   {
     "type": "person",
     "id": "22JP9H",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": true,
       "name": "Person 523387"
     }
   },
   {
     "type": "person",
     "id": "32FKD5",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": true,
       "name": "James"
     }
   },
   {
     "type": "person",
     "id": "33KF8Z",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": true,
       "name": "Erin"
     }
   }
 ]
}


Invite Friend

The Invite Friend endpoint creates an invitation to become friends with the authorized user. A successful request returns a 201 status code and an empty response body.

If the invitedUserEmail value is provided, the standard friendship invitation email is sent to the specified recipient to be accepted or rejected later. If the invitedUserId is provided, the invitation is created silently and can only be fetched through the Get Invitations endpoint. Both invitation types can be accepted or rejected via the Accept Invitation endpoint.

Warning: Be careful when using the Invite Friend endpoint and, as always, adhere to the Terms of Service. Though Fitbit has organic limits on allowed number of invitations, your application's workflow must not allow users to send bulk invitations to users. Doing so could be considered SPAM.

Resource URL

POST https://api.fitbit.com/1.1/user/-/friends/invitations

POST Parameters

invitedUserEmail required/optional Email of the user to invite. Does not need to be a Fitbit member. Either invitedUserEmail or invitedUserId is required.
invitedUserId required/optional Encoded ID of the invited user. Either invitedUserEmail or invitedUserId is required.

Get Friend Invitations

The Get Friend Invitations endpoint returns a list of invitations to become friends with a user in the format requested.

Resource URL

GET https://api.fitbit.com/1.1/user/[user-id]/friends/invitations.json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.

Example Response

{
 "data": [
   {
     "type": "inbox-invitation",
     "id": "1550258161302",
     "attributes": {
       "dateTime": "2019-02-14T14:23:04.010",
       "source": "PROFILE_INVITATION"
     },
     "relationships": {
       "user": {
         "data": {
           "type": "person",
           "id": "GGNJLD"
         }
       }
     }
   },
   {
     "type": "sent-invitation",
     "id": "1550258161321",
     "attributes": {
       "dateTime": "2019-02-15T19:16:01.321",
       "email": "notauser@mail.com",
       "source": "PROFILE_INVITATION"
     }
   },
   {
     "type": "sent-invitation",
     "id": "1550258161286",
     "attributes": {
       "dateTime": "2019-02-13T12:44:32.344",
       "source": "PROFILE_INVITATION"
     },
     "relationships": {
       "user": {
         "data": {
           "type": "person",
           "id": "GGNJL7"
         }
       }
     }
   }
 ],
 "included": [
   {
     "type": "person",
     "id": "GGNJLD",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": false,
       "name": "Alexandra"
     }
   },
   {
     "type": "person",
     "id": "GGNJL7",
     "attributes": {
       "avatar": "https://static0.fitbit.com/images/profile/defaultProfile_150.png",
       "child": false,
       "friend": false,
       "name": "Arnold"
     }
   }
 ]
}

Respond to Friend Invitation

The Respond to Friend Invitation endpoint accepts or rejects an invitation to become friends with inviting user.

Resource URL

POST https://api.fitbit.com/1.1/user/-/friends/invitations/[from-user-id]
from-user-id Encoded ID of user from which to accept or reject invitation.

POST Parameters

accept required Accept or reject invitation. 'true' or 'false'.

Friends API Ver. 1.0

If your application has a dependency on Friends API endpoints ver. 1.0, the previous documentation can be found here.