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 is a two-tiered mechanism, where the first level setting, Friends (Friends or Anyone), determines the access to a user's list of friends.

The second level setting determines from the list of friends, access to the following profile (Personal Information) fields:

  • About Me (Friends or Anyone)
  • Age and Height (Friends or Anyone)
  • Location (Friends or Anyone)
  • My Body (Friends or Anyone)

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/friends.json

user-idThe 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:

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

  2. GET https://api.fitbit.com/1/user/-/friends.json

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for response values.

Example Response

{
    "friends":[
        {
            "user":
                {
                    "aboutMe":"I live in San Francisco.",
                    "avatar":"http://www.fitbit.com/images/profile/defaultProfile_100_male.gif",
                    "city":"San Francisco",
                    "country":"US",
                    "dateOfBirth":"1970-02-18",
                    "displayName":"Nick",
                    "encodedId":"257V3V",
                    "fullName":"Fitbit",
                    "gender":"MALE",
                    "height":176.7,
                    "offsetFromUTCMillis":25200000,
                    "state":"CA",
                    "strideLengthRunning":0,
                    "strideLengthWalking":0,
                    "timezone":"America/Los_Angeles",
                    "weight":80.5
                }
         },
         {
            "user":
                {
                    "aboutMe":"",
                    "avatar":"http://www.fitbit.com/images/profile/defaultProfile_100_male.gif",
                    "city":"",
                    "country":"",
                    "dateOfBirth":"",
                    "displayName":"Fitbit U.",
                    "encodedId":"2246K9",
                    "fullName":"Fitbit User",
                    "gender":"NA",
                    "height":190.7,
                    "offsetFromUTCMillis":14400000,
                    "state":"",
                    "strideLengthRunning":0,
                    "strideLengthWalking":0,
                    "timezone":"Europe/Moscow",
                    "weight":0
                }
         }
     ]
}

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

There are two privacy settings to consider for the response data:

  1. The Hide me from rankings privacy setting allows a user to be included to Friends leaderboard whether he hides himself on his profile settings or not.

  2. The following privacy permissions grant granular access to any listed user's respective profile fields:

    • About Me (Friends or Anyone)
    • Age and height (Friends or Anyone)
    • Location (Friends or Anyone)
    • My Body (Friends or Anyone)

The response includes the correct values for accessible fields and empty values: empty string, "NA" (empty gender), 0 (empty height), default avatar etc., while some values are revealed to authorized user only, such as:

  • About Me - controls aboutMe, gender, avatar
  • Age and height - controls dateOfBirth, height
  • Location - controls country, city, state, timezone, offsetFromUTCMillis
  • My Body - controls weight

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/friends/leaderboard.json

user-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for response values.

Example Response

{
    "hideMeFromLeaderboard":"false",
    "friends":[
        {
            "average":
                {
                    "steps":9854,
                },
            "rank":
                {
                    "steps":1
                },
            "summary":
                {
                    "steps":56000
                },
            "lastUpdateTime":"2013-03-29T13:25:00",
            "user":
                {
                    "aboutMe":"I live in San Francisco.",
                    "avatar":"http://www.fitbit.com/images/profile/defaultProfile_100_male.gif",
                    "city":"San Francisco",
                    "country":"US",
                    "dateOfBirth":"1970-02-18",
                    "displayName":"Nick",
                    "encodedId":"257V3V",
                    "fullName":"Fitbit",
                    "gender":"MALE",
                    "height":176.7,
                    "offsetFromUTCMillis":-25200000,
                    "state":"CA",
                    "timezone":"America/Los_Angeles",
                    "weight":80.5
                }
         },
         {
            "average":
                {
                    "steps":13854,
                },
            "rank":
                {
                    "steps":2
                },
            "summary":
                {
                    "steps":45000
                },
            "lastUpdateTime":"2013-03-29T15:25:00",
            "user":
                {
                    "aboutMe":"",
                    "avatar":"http://www.fitbit.com/images/profile/defaultProfile_100_male.gif",
                    "city":"",
                    "country":"",
                    "dateOfBirth":"",
                    "displayName":"Fitbit U.",
                    "encodedId":"2246K9",
                    "fullName":"Fitbit User",
                    "gender":"NA",
                    "height":190.7,
                    "offsetFromUTCMillis":14400000,
                    "state":"",
                    "timezone":"Europe/Moscow",
                    "weight":0
                }
         }
     ]
}

Invitations

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

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/user/-/friends/invitations.json

POST Parameters

invitedUserEmailrequired/optionalEmail of the user to invite. Does not need to be a Fitbit member. Either invitedUserEmail or invitedUserId is required.
invitedUserIdrequired/optionalEncoded 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/user/<user-id>/friends/invitations.json

Example Response

{
    "friends":[
        {
            "dateTime":"2012-06-05T02:26:29.000",
            "user":
                {
                    "aboutMe":"I live in San Francisco.",
                    "avatar":"http://www.fitbit.com/images/profile/defaultProfile_100_male.gif",
                    "city":"San Francisco",
                    "country":"US",
                    "dateOfBirth":"1970-02-18",
                    "displayName":"Nick",
                    "encodedId":"257V3V",
                    "fullName":"Fitbit",
                    "gender":"MALE",
                    "height":176.7,
                    "offsetFromUTCMillis":25200000,
                    "state":"CA",
                    "strideLengthRunning":0,
                    "strideLengthWalking":0,
                    "timezone":"America/Los_Angeles",
                    "weight":80.5
                }     
        }
    ]
}

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/user/-/friends/invitations/[from-user-id].json

from-user-idEncoded ID of user from which to accept or reject invitation.

POST Parameters

acceptrequiredAccept or reject invitation. 'true' or 'false'.

Example Response

{
  "friends":  [
     {
      "dateTime": "2014-10-07T16:00:39.237-07:00",
      "userId": "23SZNY"
    }
  ]
}

Badges

Get Badges

The Get Badges endpoint retrieves user's badges in the format requested. Response includes all badges for the user as seen on the Fitbit website badge locker (both activity and weight related). Fitbit returns weight and distance badges based on the user's unit profile preference as on the website.

Privacy Setting

There are two privacy settings to consider for the response data:

  • The My Achievements (Friends or Anyone) privacy permission grants access to other user's resource.
  • The My Body (Friends or Anyone) privacy permission reveals weight badge data in response.

Resource URL

GET /1/user/[user-id]/badges.json

from-user-idEncoded ID of user from which to accept or reject invitation.

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for response values.

Example Response

{
    "badges":[
        {
            "badgeType":"DAILY_FLOORS",
            "dateTime":"2012-04-27",
            "image50px":"http://www.fitbit.com/images/dash/badge_daily_floors10.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_daily_floors10.png",
            "timesAchieved":3,
            "value":10
        },
        {
            "badgeType":"DAILY_FLOORS",
            "dateTime":"2012-04-27",
            "image50px":"http://www.fitbit.com/images/dash/badge_daily_floors25.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_daily_floors25.png",
            "timesAchieved":3,
            "value":25
        },
        {
            "badgeType":"DAILY_STEPS",
            "dateTime":"2012-04-27",
            "image50px":"http://www.fitbit.com/images/dash/badge_daily_steps5k.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_daily_steps5k.png",
            "timesAchieved":6,
            "value":5000
        },
        {
            "badgeType":"LIFETIME_KILOMETERS",
            "dateTime":"2011-09-26",
            "image50px":"http://www.fitbit.com/images/dash/badge_lifetime_kilometers50.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_lifetime_kilometers50.png",
            "timesAchieved":1,
            "unit":"KILOMETERS",
            "value":50
        },
        {
            "badgeType":"LIFETIME_FLOORS",
            "dateTime":"2011-09-27",
            "image50px":"http://www.fitbit.com/images/dash/badge_lifetime_floors500.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_lifetime_floors500.png",
            "name":"Helicopter",
            "timesAchieved":1,
            "value":500
        }
        {
            "badgeType":"GOAL_BASED_WEIGHT_LOSS_POUNDS",
            "dateTime":"2012-06-21",
            "image50px":"http://www.fitbit.com/images/dash/badge_weight_finish.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_weight_finish.png",
            "timesAchieved":1,
            "value":1
        },
        {
            "badgeType":"LIFETIME_LOSS_POUNDS",
            "dateTime":"2012-05-23",
            "image50px":"http://www.fitbit.com/images/dash/badge_lifetime_weight_teal.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_lifetime_weight_teal.png",
            "timesAchieved":1,
            "unit":"POUNDS",
            "value":-10
        },
        {
            "badgeType":"GOAL_BASED_WEIGHT_LOSS_ACHIEVEMENT",
            "dateTime":"2012-06-21",
            "image50px":"http://www.fitbit.com/images/dash/badge_weight_finish.png",
            "image75px":"http://www.fitbit.com/images/dash/75px/badge_weight_finish.png",
            "timesAchieved":1,
            "value":1
        }
    ]
}