Data Access

Common information

Common information secction applys for data access APIs, especially common header with authorization.

Common header
Header Mandatory Description
Content-Type Yes Specifies response type body, which should be application/json
Authorization Yes OAuth 2.0-style authorization header, which is “Bearer “ + acquired access token through authorization API
Common error response
Key Data Type Mandatory Description
code interger Yes HTTP error code
reason string Yes Error reason
message string Yes detailed error message
Common error response code
code reason message
401 noAccessToken Could not process request for given user ID
tokenExpired Access token has expired or revoked
403 noManifestId Could not process request for given data type
permissionDenied Client does not have access to perform the requested action
noPermissionGranted Current user does not have access
429 tooManyRequest Temporary issue due to throttling
500 internalError Encountered an internal error
503 serviceUnavailable Encountered an internal server error

User Profile API

Read user profile
URI GET /health/v1/users/me/info
Description Read user profile
Parameters -
Success
Response Body
200 OK
data user_id string unique user ID assigned by data server
account_provider string hard-coded literal as samsung
name string name assigned by user
gender string gender of user, M or F, which corresponds to male and female, respectively
birth_date string user’s date of birth in YYYYMMDD format
country string country of user
weight float latest weight of user in kilogram unit
height float latest height of user in centimeter unit
Update user profile
URI PUT /health/v1/users/me/info
Description Update user profile.
Parameters -
Body data name string name assigned by user, which should be shorter than 100 characters
Success
Response Body
200 OK

Error response

code reason message description
400 badRequest Could not proceed request – invalid properties When invalid property is specified

Device API

Each health data has mandatory field of deviceuuid, which is used to distinguish the source information. For example, mobile device has its own deviceuuid and every health data generated by the device shares same deviceuuid. Health data created through REST API has default virtual deviceuuid of 000000000000 if not specified and every health data has deviceuuid in the body field of server response.

Read device
URI Single device: GET /health/v1/users/me/devices/{deviceuuid}
All devices: GET /health/v1/users/me/devices
Description Read device profile. Percent-encoding, also known as URL encoding, should be used for deviceuuid path element.
For data inserted with server API, following virtual device is used
  • deviceuuid: “000000000000”
  • device_group: 36005
  • name: “Samsung Health Platform"
  • manufacturer : “Samsung”
  • model: “Data Server”
Parameters -
Success
Response Body
200 OK
records array create_time long create time of device profile
update_time long update time of device profile
datauuid string unique identifier
deviceuuid string device identifier
pkg_name string package name
device_group integer group of device
0: unknown
36001: mobile device
36002: external peripheral device
36003: companion or wearable
36005: Web access
name string custom name given to the device
manufacturer string manufacturer of the device
model string model name of the product

Data CRUD API

For each data, there are common fields to uniquely identify each record, create_time, update_time, pkg_name, datauuid and deviceuuid. When creating or updating data of given data type,

  • pkg_name of each record is updated to pkg_name from client_id

  • deviceuuid of each record is updated to predefined device ID of 000000000000

  • update_time of each record is update to current request time

  • datauuid should be format of UUID, the 32 hexadecimal digits displayed in five groups separated by hyphens in the form 8-4-4-4-12. It is highly encouraged to generate it using random UUID generator.

Changes, Create/Update and Delete API may require extra query parameter of device_id. This device_id is a unique device identifier for distinguishing device given by client and used to for changes API by not including changes in the device_id for the response.

Create/Update
URI POST /health/v1/users/me/{data_type}
Description Create or update data of given data type:
  • When necessary parameter or body is missing, this API gives 400 error.
  • This API performs bulk operation and gives 200 OK even though actual delete operation fails with partial failure. Detailed failed result comes with fails key.
  • If package name from client_id does not match owner of each records, update fails partially.
  • If data type is private and it does not contains package name of client_id, client cannot create or update any entry of given data type with 403 error.
Some data types include blob type. Unlike primitive data types like integer, long, float, double or string, blob data should be encoded as base64.
Parameter device_id string Unique device identifier for distinguishing client device which affects behavior of _changes API
Body records array create_time long create time of data
update_time long update time of data
update_time is updated with value specified by client only when override_common parameter is true
deviceuuid string deviceuuid of data
deviceuuid is updated with value specified by client only when override_common parameter is true
pkg_name pkg_name of data
pkg_name is update with value specified by client only when override_common
... ... additional JSON key(s) and value(s)
Successful
Response Body
fails array datauuid string failed datauuid
error_code integer failure error code
1: newer data is available for given datauuid
2: client time is newer than server time
3: property validation failure
error_msg string detailed error message
Example

POST /health/v1/users/me/com.samsung.health.heart_rate
{
    "records":[
    {
        "datauuid":"abcd-1234-efgh-5678",
        "create_time":14090586514,
        "heart_rate":21.1,
        "heart_beat_count":81
    },
    {
        "datauuid":"abcd-1234-efgh-5679",
        "create_time":14090586520,
        "heart_rate":20.5,
        "heart_beat_count":98
    }]
}

Response code: 200
{
    "fails":[
    {
        "datauuid":"abcd-1234-efgh-5678",
        "error_code":1
    }]
}

Error response

code reason message description
400 badRequest Could not proceed request. Invalid properties When query parameter or body does not have required parameter
403 permissionDenied Current user does not have access to perform the requested action When current client is not allowed to access given data type (possible 4000002)
notAllowedOperation Client does not have permission for the operation Client is not allowed to use override_common parameter
Read
URI Single measurement : GET /health/v1/users/me/{data_type}/{datauuid}
All data: GET /health/v1/users/me/{data_type}
Description Read data of given data type
Parameters offset string The offset of the first record returned
limit integer (1~2000), default 2000
changed_after long start timestamp
Success
Response Body
200 OK
records array create_time long create_ time of device profile
... ... additional JSON key(s) and value(s)
sync_time long Synced timestamp. When pagination is required, both sync_time and next_offset should be specified
next_offset string When next_offset is specified, client should handle pagination by specifying offset and changed_after parameter for next request
Example
Response code: 200
{
    "records": [{
        "com.samsung.health.heart_rate.datauuid": "fea289f5-2377-4658-b38f-aab3458e3c40",
        "com.samsung.health.heart_rate.deviceuuid": "ABCD-9876-EFGH-5432",
        "com.samsung.health.heart_rate.time_offset": 7200000,
        "com.samsung.health.heart_rate.heart_rate": 21.1,
        "com.samsung.health.heart_rate.update_time": 1476800453478,
        "com.samsung.health.heart_rate.end_time": 1476800443478,
        "com.samsung.health.heart_rate.pkg_name": "com.sec.android.app.shealth",
        "com.samsung.health.heart_rate.create_time": 1476800443478,
        "com.samsung.health.heart_rate.heart_beat_count": 81,
        "com.samsung.health.heart_rate.start_time": 1476800443478
    },
    {
        "com.samsung.health.heart_rate.datauuid": "abcd-1234-efgh-6666",
        "com.samsung.health.heart_rate.deviceuuid": "ABCD-9876-EFGH-5432",
        "com.samsung.health.heart_rate.time_offset": 7200000,
        "com.samsung.health.heart_rate.heart_rate": 21.1,
        "com.samsung.health.heart_rate.update_time": 1476799462244,
        "com.samsung.health.heart_rate.end_time": 1476799452245,
        "com.samsung.health.heart_rate.pkg_name": "com.sec.android.app.shealth",
        "com.samsung.health.heart_rate.create_time": 1476799452245,
        "com.samsung.health.heart_rate.heart_beat_count": 81,
        "com.samsung.health.heart_rate.start_time": 1476799452245
    }],
    "next_offset": "1476800462466:fea289f5-2377-4658-b38f-aab3458e3c40",
    "sync_time": 1477662206771
}

Error response

code reason message description
400 invalidParameter The value for one of the query parameters was invalid When one of the query parameter was invalid
403 permissionDenied User does not have access to perform the requested action When current client is not allowed to access given data type
Changes
URI GET /health/v1/users/me/{data_type}/_changes
Description Retrieve changed datauuid’s with details. _changes API gives full change history including delete but only for limited time period of 100 days. Changes from current device is not included in the response
Parameters offset string The offset of the first record returned
limit integer (1~2000), default 2000
changed_after long start timestamp
device_id string Unique device identifier for distinguishing client device
Changes from specified device is not included in the response
Success
Response Body
200 OK
changes array datauuid string unique identifier
update_time long update time of device profile
action integer record change type
0: deleted
1: created / updated
sync_time long Synced timestamp. When pagination is required, both sync_time and next_offset should be specified
next_offset string When next_offset is specified, client should handle pagination by specifying offset and changed_after parameter for next request
Example
Response code: 200
{
    "changes":[
    {
        "datauuid":"3123123123-abcd",
        "action":0,
        "update_time":123123123123
      },
      {
         "datauuid":"3123123124-abcd",
         "action":1,
         "update_time":123123123124
      },
      {
         "datauuid":"3123123155-abcd",
         "action":1,
         "update_time":123123123125
      }
    ],
    "next_offset": "1476800462466:fea289f5-2377-4658-b38f-aab3458e3c40",
    "sync_time": 1477662206771
}

Error response

code reason message description
400 invalidParameter The value for one of the query parameters was invalid When one of the query parameter was invalid
403 permissionDenied Current user does not have access to perform the requested action When current client is not allowed to access given data type
URI POST /health/v1/users/me/{data_type}/_search
Description Retrieve data with given criteria
Body datauuids string array array of data records identifiers
Success
Response Body
200 OK
records array create_time long create_ time of the data
update_time long update_ time of the data
... ... additional JSON key(s) and value(s)
Example
POST /health/v1/users/me/com.samsung.health.heart_rate/_search
{
   "datauuids":[
      "fea289f5-2377-4658-b38f-aab3458e3c40",  "abcd-1234-efgh-6666"
   ]
}
Response code: 200
{
    "records": [{
        "com.samsung.health.heart_rate.datauuid": "fea289f5-2377-4658-b38f-aab3458e3c40",
        "com.samsung.health.heart_rate.deviceuuid": "ABCD-9876-EFGH-5432",
        "com.samsung.health.heart_rate.time_offset": 7200000,
        "com.samsung.health.heart_rate.heart_rate": 21.1,
        "com.samsung.health.heart_rate.update_time": 1476800453478,
        "com.samsung.health.heart_rate.end_time": 1476800443478,
        "com.samsung.health.heart_rate.pkg_name": "com.sec.android.app.shealth",
        "com.samsung.health.heart_rate.create_time": 1476800443478,
        "com.samsung.health.heart_rate.heart_beat_count": 81,
        "com.samsung.health.heart_rate.start_time": 1476800443478
    }, {
        "com.samsung.health.heart_rate.datauuid": "abcd-1234-efgh-6666",
        "com.samsung.health.heart_rate.deviceuuid": "ABCD-9876-EFGH-5432",
        "com.samsung.health.heart_rate.time_offset": 7200000,
        "com.samsung.health.heart_rate.heart_rate": 21.1,
        "com.samsung.health.heart_rate.update_time": 1476799462244,
        "com.samsung.health.heart_rate.end_time": 1476799452245,
        "com.samsung.health.heart_rate.pkg_name": "com.sec.android.app.shealth",
        "com.samsung.health.heart_rate.create_time": 1476799452245,
        "com.samsung.health.heart_rate.heart_beat_count": 81,
        "com.samsung.health.heart_rate.start_time": 1476799452245
    }],
}

Error response

code reason message description
403 badRequest Could not proceed request. Invalid properties When current client is not allowed to access given data type
Delete
URI POST /health/v1/users/me/{data_type}/_delete
Description Delete data of given data type:
  • This API performs bulk operation and gives 200 OK even though actual delete operation fails with partial failure. Detailed failed result comes with fails key.
  • If package name from client_id does not match owner of each records, update fails partially.
  • If data type is private and it does not contains package name of client_id, client cannot create or update any entry of given data type with 403 error.
  • Delete request fails partially if server has newer value of update_time than request body.
Paramater device_id string Unique device identifier for distinguishing client device which affects behavior of _changes API
Body records array datauuid string unique identifier
update_time long update_ time of the data. update_time is used only when override_common parameter is true
Successful
Response Body
fails array datauuid string failed datauuid
error_code integer failure error code
1: newer data is available for given datauuid
2: client time is newer than server time
error_msg string detailed error message
Example
POST /health/v1/users/me/com.Samsung.health.heart_rate/_delete
{
    "records":[
    {
        "datauuid":"abcd-1234-efgh-5678",
    },
    {
        "datauuid":"abcd-1234-efgh-5679",
    }]
}
Response code: 200
{
    "fails":[
    {
        "datauuid":"abcd-1234-efgh-5678",
        "error_code":1
    }]
}

Error response

code reason message description
403 permissionDenied Current user does not have access to perform the requested action When current client is not allowed to access given data type
notAllowedOperation Client does not have permission for the operation Client is not allowed to use override_common parameter