Misfit Cloud API

Getting Started

Server Address

All applications must first be authenticated using OAuth as described in OAuth 2.0 protocol.

The URL_ROOT is https://api.misfitwearables.com. Misfit supports HTTPS; the HTTP endpoint is not available.

The authentication API server root is URL_ROOT/auth, which is https://api.misfitwearables.com/auth

The resource server API root is URL_ROOT/move/v1, which is https://api.misfitwearables.com/move/resource/v1

Please check the detailed API endpoint for each API in the API reference page.

Quick start:

  1. Register a developer account on the Misfit Developer Portal Sign Up page.

    1. The Misfit Developer Portal is the entry point for developers to register/manage their application and get the API consumer key and secret which allow apps to connect to the Misfit Cloud API.
    2. The Misfit Developer Portal is a registration center where partners can upload their application information (websites, contacts, logos) which will be shown when users grant permissions to use
      their data.
    3. The Misfit Developer Portal is a console for developers to configure their app settings: redirecting url domain restriction, setting the subscription endpoint, resources they want to subscribe
      to, etc.
  2. Check API Reference

    1. OAuth flow, API
    2. Resource API
    3. Subscription API
  3. Community Tools/Libraries: Start with tools or libraries

Authentication API

OAuth uses specific terminology to represent the developer and the entity that provisions authorization. In this case, the application or site that requires access to user data is known as the Consumer, whereas Misfit is known as the Service Provider.

authentication

Before you can start making Misfit Cloud API requests, you need to sign up and submit some details about your company on the Sign Up page.

After registering your application, you will receive an App ID (also called Client Key) which is your unique Misfit ID. You will also receive an App Secret (also called Client Secret) that will be required when asking for a Request Token. Save the App ID and App Secret so that you can use it in your code as required.

After your registration is approved you will need to indicate the type of Misfit User data (also called Scopes) that you want to access on the Application Settings page. In the current version, the scopes are defaulted for full access. Later in the OAuth process, Misfit will ask for your users’ permission to access their user data.

Resource API

 

Overview

The Resource API is the primary way to get data in and out of Misfit’s health platform. It’s a low-level HTTP-based API that you can use to query data, post new stories, upload photos and a variety of other tasks that an app may need to do.

Using the Resource API

All resource in the Resource API can be simply read with an HTTP GET request to the relevant endpoint. For example, if you want to retrieve information about the current user, you would make an HTTP GET request as follows:

GET https://api.misfitwearables.com/move/resource/v1/user/me/profile HTTP/1.1 Host: api.misfitwearables.com

Most API calls must be signed with an access_token. You can determine which permission are needed in this access token by looking at the api reference.

me

The /me node is a special endpoint that translates to the user_id of the person whose access token is currently being used to make the API calls.

Summary and Session

Put simply, Summary describes a user’s daily movement and sleep, while Activity Sessions highlight the day’s most intense moments. Besides individual activity sessions, the Misfit Shine/Flash continually reports activities for the previous 24 hours.

Why is the summary result more than the sum of session activities?

We count a user’s total daily activity in the progress summary which can be more than the sum of session activities, because the summary results include minor activities outside of sessions.

Timezone

For each time-related resource, such as an activity or sleep session, our server will keep track of the timezone offset (from UTC). For example

Sample activity

{
    "id":"537bc32bea4656a82e030036",
    "activityType":"Walking",
    "startTime":"2014-05-19T10:26:54-04:00",
    "duration":840,
    "points":66.4,
    "steps":660,
    "calories":30.9342,
    "distance":0.2338
}

The startTime field above indicates that the session happens at 10:26:54 at UTC-4. Please take note of the timezone offset in case you want to compare your users’ data.

Required HTTP Header

You have two methods of accessing user data:

User-level access

Your request should include the user’s access_token in the headers

access_token=USER_ACCESS_TOKEN

or

Authorization: Bearer USER_ACCESS_TOKEN

App-level access

Your request should include your app token (App ID and App Secret)

 app_id=YOUR_APP_ID
app_secret=YOUR_APP_SECRET

Note: Using app-level access, ‘me’ will not a valid userId in the URL. Furthermore, you can only access data from users who have authorized your app or a “Forbidden” error will occur.

userId in URL

In any /user/:userId/* APIs, you can input ‘me’ as userId to get current user’s data

API Rate Limit

The Resource API only allows you to query 150 times/hour per user. Each time you query, our server will track your limit in the response header. For example

Sample response header

Response Headers:
X-RateLimit-Limit:150
X-RateLimit-Remaining:148
X-RateLimit-Reset:1404298869

If you reach that limit an error will occur

Limit rate error

HTTP Status Code: 429
{
  error_message: 'Rate limit exceeded'
}

Date Formatting

Date format

Dates should be in YYYY-MM-DD format (e.g. 2014-01-31)

Time format

All time formats are in ISO Time

Array format

Some API responses have multiple data objects. For example, the goal API will respond with information about several goals.

In this API, data will be organized into objects, which part of an array in the response.

Common Exceptions

{
    "code": 500,
    "message": "Unexpected server error"
}

OR

{
    "code": 400,
    "message": "Missing parameters"
}

Subscription API

 

Overview

The Subscription API allows third parties to subscribe to real-time notifications from Misfit.

Third parties can register an HTTP endpoint to receive notifications when there is a change in Misfit user data.

Attention

When you sub/unsub some resources with the Subscription API, you are subscribing/unsubscribing data change events of ALL USERS of your app, not just for a specific user.

Quick Start

Step 1: Prepare an HTTP endpoint before subscribing for notifications

Before you subscribe to user data changes, be sure to prepare an HTTP endpoint that:

  1. Is accessible to the public
  2. Responds correctly when receiving a confirmation message from Misfit. See API References#Confirmsubscription
  3. Is able to parse the data correctly according to Misfit’s notification message format. See API References#Receivenotificationupdate

Step 2: Subscribe for user resource changes

When you have your HTTP endpoint, you can subscribe to changes in specific resource types.

Please login to https://build.misfit.com with your developer account and find your app to set up the subscription endpoint and resources.

  1. Enable the resources you want to subscribe to in the update event.
    subscription1

  2. Input your endpoint for receiving update events and pass the test by clicking the “test endpoint” button.
    subscription2

    After your app is subscribed to notifications, Amazon SNS will post a confirmation message to your endpoint. You must parse the SNS message to find the “SubscribeURL” value. Perform an HTTP GET to that URL to confirm the subscription. Your endpoint will receive future notifications only after the subscription is confirmed.
    See more details here.

Step 3: Receive notifications

When there is a change to user data, the Misfit system will send a request to your HTTP endpoint.

The notification message only contains the ID of the resource and metadata of the change, as outlined in API References#Receivenotificationupdate.

You will need to query the Resource API to get the latest data and perform an update on the Consumer side.

Community Tools

These tools/libraries are created and maintained by 3rd parties, which may help you quickly start implementing the API in your application. They are not developed or supported by Misfit, and are only listed here as a convenience for our developer community. If you have any questions please contact the tool owner directly.

  1. Ruby:
  2. Node.js:
  3. Python:

Many thanks to all the developers of Misfit API.

API Errors

 
API errors use both HTTP error code and API specific error codes and messages.

HTTP Codes

HTTP error codes indicates that a request is not successful and helps the client quickly identify various types of problems.

HTTP Code Description
502 Bad Gateway Server is down, crashed, restarting
500 Internal Server Erro Server cannot fulfill the request. For example: cannot establish DB connections
404 Not Found Invalid endpoints

The resource with a given id doesn’t exist
401 Unauthorized Lack of app token (key & secret) or user access token

Invalid/expired access token
403 Forbidden Does not have proper permission to access the resources
400 Bad Request Invalid parameters

Other API specific errors

An API Specific Errors

API specific error is comprised of an error code and an error message.

The first digit indicates the type of error.

A resource specific error is assigned an error-type digit.

code type Example
0XX Generic errors

(not related to a specific resource type)
001: Unknown error>002: Invalid endpoint

003: Missing parameters

004: Invalid parameters

(applied for basic field validation: integer, float, min, max, email, unsupported characters)
1XX User 101: Email is already taken
2XX Profile 201: Handle is already taken
3XX
.. ..
10XX Subscription 1001: Invalid resource # when trying to subscribe to an invalid resource

1002: Subscription not found # when try to unsubscribe but was not subscribed before

Example

HTTP 400
{
"error_code": "1002",
"error_message": "Subscription not found"
}

×
Valid email required.
Name required.
Company/organization required.
Number of Employees required.
×