Create Sleep Log

Creates a log entry for a sleep event and returns a response in the format requested.

Scope: sleep

Request

POST	/1.2/user/[user-id]/sleep.json

URI Arguments

user-id

required

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

Query Parameters

date	required	Log entry date in the format yyyy-MM-dd.	string ($date)
duration	required	Duration in milliseconds.	integer
startTime	required	Start time; hours and minutes in the format HH:mm.	string ($date)

Request Headers

authorization	required	Specify the token type and Fitbit user’s access token. Token type: `Bearer`
accept	optional	Defines the media type of the response content the client is expecting. Supported: `application/json`
accept-language	optional	The measurement unit system to use for response values. See Localization.
accept-locale	optional	The locale to use for response values. See Localization.
content-length	required	According to RFC 7230, section 3.3.2, this HTTP request requires the Content-Length header field containing the anticipated size of the payload body.

Examples

URL
CURL

POST https://api.fitbit.com/1.2/user/-/sleep.json?date=2020-02-09&startTime=22:00&duration=720000
POST https://api.fitbit.com/1.2/user/GGNJL9/sleep.json?date=2020-02-09&startTime=22:00&duration=720000

curl -X POST "https://api.fitbit.com/1.2/user/-/sleep.json?date=2020-02-09&startTime=22:00&duration=720000" \
-H "accept: application/json" \
-H "authorization: Bearer <access_token>" \
-H "content-length: <message_body_size>"

Element Name	Description
sleep : dateOfSleep	The data the sleep log ended.
sleep : duration	Length of the sleep in milliseconds.
sleep : efficiency	Calculated sleep efficiency score. This is not the sleep score available in the mobile application.
sleep : endTime	Time the sleep log ended.
sleep : infoCode
sleep : isMainSleep	Boolean value: `true` or `false`
sleep : levels : data : dateTime	Timestamp the user started in sleep level.
sleep : levels : data : level	The sleep level the user entered.
sleep : levels : data : seconds	The length of time the user was in the sleep level. Displayed in seconds.
sleep : levels : summary : [stage] : count	Total number of times the user entered the sleep level.
sleep : levels : summary : [stage] : minutes	Total number of minutes the user appeared in the sleep level.
sleep : logId	Sleep log ID.
sleep : minutesAfterWakeup	The total number of minutes after the user woke up.
sleep : minutesAsleep	The total number of minutes the user was asleep.
sleep : minutesAwake	The total number of minutes the user was awake.
sleep : minutesToFallAsleep	The total number of minutes before the user fell asleep.
sleep : startTime	Time the sleep log begins.
sleep : timeInBed	Total number of minutes the user was in bed.
sleep : type	The type of sleep log. Supported : `classic` \| `stages`

{
  "sleep": {
    "dateOfSleep": "2020-02-09",
    "duration": 720000,
    "efficiency": 100,
    "endTime": "2020-02-09T22:12:00.000",
    "infoCode": 0,
    "isMainSleep": false,
    "levels": {
      "data": [
        {
          "dateTime": "2020-02-09T22:00:00.000",
          "level": "asleep",
          "seconds": 720
        }
      ],
      "summary": {
        "asleep": {
          "count": 0,
          "minutes": 12
        },
        "awake": {
          "count": 0,
          "minutes": 0
        },
        "restless": {
          "count": 0,
          "minutes": 0
        }
      }
    },
    "logId": 25793948582,
    "minutesAfterWakeup": 0,
    "minutesAsleep": 12,
    "minutesAwake": 0,
    "minutesToFallAsleep": 0,
    "startTime": "2020-02-09T22:00:00.000",
    "timeInBed": 12,
    "type": "classic"
  }
}

Response Headers

content-type	The media type of the response content being sent to the client. Supported: `application/json`
fitbit-rate-limit-limit	The quota number of calls.
fitbit-rate-limit-remaining	The number of calls remaining before hitting the rate limit.
fitbit-rate-limit-reset	The number of seconds until the rate limit resets.

Note: The rate limit headers are approximate and asynchronously updated. This means that there may be a minor delay in the decrementing of remaining requests. This could result in your application receiving an unexpected 429 response if you don't track the total number of requests you make yourself.

Response Type

HTTP Status Code	HTTP response code. List of codes are found in the Troubleshooting Guide.
Status Message	Description of the status code.
Response Body	Contains the JSON response to the API call. When errors are returned by the API call, the errorType, fieldName and message text will provide more information to the cause of the failure.

Response Codes

201	A successful request.
400	The request had bad syntax or was inherently impossible to be satisfied.
401	The request requires user authentication.

Note: For a complete list of response codes, please refer to the Troubleshooting Guide.

Additional Information

It is NOT possible to create overlapping log entries. The dateOfSleep in the response for the sleep log is the date on which the sleep event ends.

This endpoint supports two kinds of sleep data:

stages : Levels data is returned with 30-second granularity. 'Sleep Stages' levels include deep, light, rem, and wake.
classic : Levels data returned with 60-second granularity. 'Sleep Pattern' levels include asleep, restless, and awake.

Note: shortData is only included for stages sleep logs and includes wake periods that are 3 minutes or less in duration. This distinction is to simplify graphically distinguishing short wakes from longer wakes, but they are physiologically equivalent.

Manually Created Sleep Logs

A manual sleep log is either a sleep log that has human input through the mobile or web application, or a 3rd party application records sleep using the Create Sleep Log endpoint. When a sleep log is manually recorded, a "classic" sleep log is generated. Sleep "stage" logs use the device heart rate and movement to calculate sleep stage data. When manually entering a sleep log, this information is typically not available.

Create Sleep Goal

Delete Sleep Log