Developer FAQ

Portal

How do I obtain my API keys?

To setup your application and obtain API keys, first you need to create an account on Jawbone.com if you don't already have one. Then sign in via the link under "Account" on the left side of the developer portal.

You will need to setup both an organization and an application (organizations are the high level parent and you can have multiple applications under each). Then you create your new application vendor by hitting the "Create An Account" button where you can setup your organization. After you created your organization, go to 'Manage Account" and under the account you will have the option to 'Create App'. Once you setup your app you will see your API keys to start making OAuth calls.

What are the roles for organizations and apps?

Roles control who can administer your applications. Roles at the organization level also have the same rights for any applications created under it. Roles at the application level only apply to that application, but not the organization. Admins can add other roles, edit configuration, and are whitelisted to see application posts on their UP feed. Developers can edit configurations and are whitelisted to see application posts on their UP feed. Testers are whitelisted to see application posts on their UP feed.

What does publishing an application do?

Until an application is published only those users with roles under that org/app can see the posts from it. Once an application is published any UP user will see events from that application if they come from a teammate, and can also use those events to connect to the app themselves. Note: publishing an application does not make it available to users via the UP app gallery (this is invitation only) but once a user connects to the app it will appear there. You must use only HTTPS for redirects in order to publish an app per the OAuth 2.0 specification. NOTE: once an application is published you cannot edit or unpublish it unless you contact API Support, so only publish once you are confident of the app final configuration and have thoroughly tested your application.

I published my app already but need to edit the details/links. How can I do that?

Send an email to apisupport@jawbone.com with your Client ID and what field you need changed. If you need to make big changes, we can also unpublish the app for you, just let us know if you need that done instead.

Does the webhook for Pub Sub need to be HTTPS for published apps?

No, we don't restrict the webhook to HTTPS, although we do recommend it.

What pixel dimensions should the App Logo be?

We recommend 150 x150.

What pixel dimensions should the screenshots be?

We recommend 280 tall and up to 320 wide.

Platform

Which UP trackers will work with my application?

All of them! UP24, UP MOVE, UP2, UP3, and UP4 trackers sync automatically via Bluetooth. The original UP tracker does not use Bluetooth so data will arrive asynchronously whenever a user chooses to connect and sync their UP tracker with their phone. Use our Pub Sub system to be notified when new user data is available for all products.

There are two UP apps in the Application Store -- which one will my application work with?

Both! UP, UP24, and UP MOVE use the UP app (blue icon) and UP2, UP3, and UP4 use the UP by Jawbone app (purple icon). Additionally, the UP by Jawbone app can use a compatible device's co-processor to track steps, so you don't even need an UP tracker to track your data.

How quickly does data from an UP band sync to my device?

Provided that you have a network connection, you data will be synced and updated on our server anywhere from every 1 to 20 minutes, depending on the proximity of you band to your mobile. Without a network connection, the data will be updated for the user in the UP app via Bluetooth, but the most recent data will not be available for access via the API since the app would not have synced with the server just yet.

Can a developer access Bluetooth or the raw sensors on your devices directly?

No, only access to the derived user data from the cloud via our REST API is possible at this time. See our endpoints section for specific details on what data is available.

Can a developer access alerts or vibrations on your band directly?

Not at this time.

Can I test the API without using UP hardware?

We now have UP Sims available, which are test user accounts filled with randomized move and sleep data. See our Tools documentation for details.

Policy for being featured in UP app gallery?

Featuring in the UP app gallery is by invitation from Jawbone. You should focus on expanding your user base via your own entry point, and our users will also discover your application from any events you post to their teammates feed. Be sure to read the marketing guidelines for more details on how best to communicate your integration with Jawbone.

What is the rate limit for your API?

The API includes very high rate-limiting safety valves that should be more than enough for the standard application. If you find that your application is exceeding these limits, please let us know your intended use and call volume, so we can review the provisions.

Pub Sub allows partner applications to automatically receive notifications about new and updated user events that will be sent to a webhook url that the partner specifies. See our Pub Sub section for more details.

What can your Pub Sub handle for scalability and volumes?

Our Pub Sub is totally scalable and we have systems in place to support millions of devices. If you have any specific scenarios or numbers that you are concerned about we are happy to review them, but in the general case we should be fine here.

Is there a restriction that a jawbone account can only have one access token for our app per user at a time? Because I noticed that when I re-authenticate and obtain a new access token, attempting to access the API with the old token results in an error response.

That's correct, only one token can be valid per user per app. One reason is the scopes permissions - if you had multiple tokens per user you could have different scope permissions for each different token for the same user, and that would lead to both security and user expectation concerns. Cleaner to just allow the last one they authenticated to rule.

No, this scenario is supported - we only match redirect URI against the prefix.

How to deal with people trying to 'game' or 'cheat' the system (eg by shaking the armband instead of actually moving).

Our general policy here is we're not out to catch movement cheats. Policing users isn't our approach to the user experience, we're focused on enabling awesome experiences that excite our users and encourage their engagement. There are also technical limitations to catching movement cheats with the current wristband as it's only an accelerometer - however there might be more possible down the road with the additional of BodyMedia and their multi-sensor approach.

API

For the time being, the only advanced sensor data available through the UP API is Resting Heart Rate. This provides one value per day, captured when the user wakes up while wearing the band, and is only available from users that have an UP3 band. We are currently exploring opportunities to unlock access to more sensor data in the future, but do not have a set timeline yet.

Can I access real-time data for heart rate/sleep/moves?

Unfortunately not. The only heart rate measure we have available at this time is resting heart rate, which is a single value per day. Sleep data becomes available for access via the API after the sleep has been completed, so you won’t be able to know what sleep phase a user is in while they are sleeping. There is also only one move created per day for the user and it details all the activity from the UP band for the day. The move for the day will be created when the user first starts wearing their band, and will be updated throughout the day as new data comes in. The best way to get notified when new data is available is through our Pub Sub notifications.

Can I access the data of a user’s friend using the friends endpoint?

If that friend has also authorized your application, you can use the XID returned from the friends endpoint to retrieve the friend’s data.

I’d like to develop a Windows Phone application integrated with UP. Is there a SDK I can use?

We currently do not have a Windows client available, but that should not stop you from creating an application on the UP platform. Our API is web-based, so you can make HTTP calls to send and receive data to/from the Jawbone Cloud.

What dimensions should the event image be?

We recommend 640x440. There will be some clipping of the picture for the user's event feed so make sure to center essential details (less than 10% will be clipped but can't guarantee exact amount due to Android devices). Image layout for clipping is detailed on each endpoint.

Are your data parameters for read calls in GMT or the user's local time?

When using any parameter that is in epoch time it will be in GMT. When using any parameter that takes a direct date/time it will be according to the user's local timezone.

Why is the sleep percentage shown in the user's app a different value than the quality value retrieved in API calls?

In the app the sleep percentage value shown is the amount of their sleep goal they achieved for the night. Via the API we give the actual sleep quality (a proprietary formula based on the amount of deep and light sleep vs wake time).

Does the average intensity number have a lower and upper limit?

Lower limit is zero, no upper limit set by hardware.

Are cardiac events used to track heart rate monitor workouts? Or is it just a single HR / BP measurement that you save?

At this point they capture a single HR / BP measurement at a time, we don't track zones.

Can you explain the updated_after timestamp in more detail? Would this just be used if someone manually changed a workout?

Users can update with more details after event creation, so this tells you the last time they touched it. You can also query by the updated_after epoch time to find events that were updated after that point (even if they were created before).

How can I tell which data retrieved from the API came from a verified device, and was not edited or created manually?

We don't tag our data sources via the API at this time. However, you can tell if the workout event was created by the UP band or manually by the presence of steps data - if it came from the band it will have steps, if manually or 3rd party logged it will not.

What is the attributes field for in the generic event?

The attributes field is more useful for the partner to store and retrieve attributes that are custom to them. the image, title and verb are what get displayed in the feed

Can we submit events into the future?

Up accepts events up to 60 days in the future, but they won’t be displayed in the user’s feed until they actually catch up to the real time.

Does UP only return data in metric units?

We always return the values in metric units and it's responsibility of the partner to convert them to user's preference. As an API provider it is best to standardize on a specific unit when passing data to a partner. It is up to the partner to present the data as per the user preferences defined in the partners environment.

How to deal with duplicate data from 3rd parties?

Currently we don't make 3rd party source data very available via the API. For now this is on the integrator to make sure their data isn't duplicated when using multiple sources.

What is the precedence for date parameters in calls?

The precedence is as follow

- 1st: "date" parameter: if the request contains "date" parameter, the API will return all the events for that given day (YYYYMMDD)

- 2nd: "page_token" parameter: if the request contains the "page_token" parameter, the API will return all the workouts, in reverse order, (capped by "limit" or default of 10) that were completed before that page_token. The page_token is a timestamp, and there's a special case, when the request comes with page_token=0 which is interpreted as passing page_token = CURRENT_TIMESTAMP, ie, give all the workouts (with a limit)

- 3rd: "start_time" and (optional) "end_time" and "updated_after" parameters: if the request contains the "start_time" and "end_time" parameters, the API will return all the workouts in the time range: [start_time, end_time]. In the case the request only contains the "start_time" parameter, then the API will default to using end_time = CURRENT_TIMESTAMP. Finally, if the request contains the "updated_after" parameter, the API will return only the workouts that have been modified after that timestamp.

- 4th: If no parameters are passed, the API defaults to returning a similar response if it was called with page_token=0, ie all the workouts, in reverse order, since the CURRENT_TIMESTAMP

Research

Does Jawbone provide assistance to researchers who want to use UP in their studies?

For qualified research projects who are willing to collect data with limitations beyond regular UP usage, we can provide sensor data. For more details, please read about Jawbone’s Research Participation.

AliphCom dba Jawbone (the "Company") has entered into an assignment for the benefit of creditors. As a potential interested party, should you believe you have a claim against the Company, please click here.