PUT Devices
Contents
Updates a device with custom attributes
URL Endpoint: https://api.carnivalmobile.com/v6/devices/:device_id
Parameters
Path Parameters
Name | Type | Required | Definition |
---|---|---|---|
device_id | string | Yes | The Sailthru Mobile device ID |
Body Parameters
Name | Type | Required | Definition |
---|---|---|---|
device | object | Yes | JSON model of device Attributes |
device.user_id | string | No | A unique identifier for a user, generally mapping to an ID in your internal CRM/Backend |
device.user_email | string | No | The device’s user’s email address |
device.tags | array of strings | No | A list of tags that apply to the given device |
device.user_attributes | object | No | Custom data for the given device. More info on the structure of this hash below |
Examples
Date
# Single attribute
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_date": {
"value": "2012-04-23T18:25:00Z",
"type" : "date"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
# Array
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_dates_key": {
"value": ["2012-04-23T18:25:00Z", "2012-05-23T18:25:00Z"],
"type": "date"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
String
# Single attribute
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_string_key": {
"value": "My string value",
"type" : "string"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
# Array
curl -X PUT -u :$API_KEY -d \
'{
"user": {
"custom": {
"my_strings_key": {
"value": ["Hello", "there"],
"type" : "string"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
Boolean
# Booleans can only be set as single attributes
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_boolean_key": {
"value": true,
"type": "boolean"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
Float
# Single attribute
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_float_key": {
"value": 2.14,
"type": "float"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
# Array
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_floats_key": {
"value": [23.2, 3.141],
"type": "float"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
Integer
# Single attribute
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_integer_key": {
"value": 123,
"type": "integer"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/:$device_id
# Array
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_attributes": {
"my_integers_key": {
"value": [23, 3],
"type": "integer"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
Multiple Types
# You can set multiple attributes in the same request
curl -X PUT -u :$API_KEY -d \
'{
"device": {
"user_id": "JSmithOTI",
"user_email": "joshsmith@example.com",
"tags": ["working", "man"],
"user_attributes": {
"release_date": {
"value": "1965-12-03T01:15:00Z",
"type" : "date"
},
"favorite_song": {
"value": "Drive My Car",
"type" : "string"
},
"starred_tracks": {
"value": [1, 6, 11],
"type": "integer"
}
}
}
}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id
Result Format
200 OK
{
"device": {
"id": "123",
"user_id": "JSmithOTI",
"user_email": "joshsmith@example.com",
"push_token": "fake_token_string",
"tags": ["working", "man"],
"platform": "iOS",
"user_attributes": {
"my_date": {
"type": "date",
"value": "2012-04-23T18:25:00.000Z"
}
},
"user_events": {
"purchase_unlocked": {
"count": 10,
"first_happened_at": "2016-05-23T04:12:34.173Z",
"last_happened_at": "2016-05-24T04:12:34.173Z"
}
},
"location": {
"gps": {
"lat": "-41.12345",
"lng": "174.12345"
},
"geoip": {
"lat": "-41.0",
"lng": "174.0",
"city": "Wellington",
"country": "New Zealand"
}
}
}
}
{
"error":"unauthorized"
}
403 Forbidden
{
"error":"your api client does not have the correct roles"
}
Note: This endpoint updates a device with new attributes, merging (not replacing) the attributes you sent in the request with the ones present on the device record.
If sent a mix invalid data (keys other than user_email
, user_id
, user_attributes
or tags
, or invalid values for any of the above) and valid data, we’ll take the valid data and discard the invalid. If only invalid data is sent, however, we’ll return a 422 response.
Valid Types
Data type | Ranges/valid values | Example | Notes | Can be sent as array |
---|---|---|---|---|
|
|
|
Floating point numbers are accepted but they will be truncated to an Values out of range will be discarded. |
Yes |
|
Single-precision 32-bit IEEE 754 floating point. |
|
Floats greater than 32-bit will be converted to scientific notation. |
Yes |
|
UTF-8 character encoding |
|
Maximum 255 characters long |
Yes |
|
ISO 8601, e.g. |
|
Yes |
|
|
|
No |
User Attributes Hash Structure
User Attributes – sometimes called Custom Attributes – have a specific structure that must be user when setting them via the Sailthru Mobile API. Below is an annotated example:
Custom Attribute Limits
There are limits in place on the maximum number of custom attributes allowed as well as the length (size) of strings and arrays.
- A maximum of 50 custom attributes is allowed per device. If you exceed this amount any new attributes being set will be discarded.
- String values that have more than 255 characters will be truncated. The limitation is on the character length, not on the size in bytes.
- Arrays with more than 50 elements will be truncated.
Key Name Restrictions
There are some restrictions in place on the key name, these are:
- Only letters, numbers, underscore and dash are valid characters.
- Leading spaces will be removed.
" my_string_key "
will become"my_string_key"
. - Invalid characters other than spaces and dots will be removed.
"my_string_key~~~~"
will become"my_string_key"
. - Spaces and dots will be replaced for underscores.
"my string.key"
will become"my_string_key"
. - Keys will be truncated to a maximum of 255 characters.
- Invalid keys (including keys exclusively made of invalid characters) will simply be discarded and no error will be returned.