PUT Devices

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

Copy

# Single attribute
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

# Single attribute
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

# Booleans can only be set as single attributes
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

# Single attribute
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

# Single attribute
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

# You can set multiple attributes in the same request
curl -X PUT -u :$API_KEY -d \
  '{
    "device": {
      "<span class="mc-variable MyVariables.User_lower variable">user</span>_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

Copy

{
  "device": {
    "id": "123",
    "<span class="mc-variable MyVariables.User_lower variable">user</span>_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"      }
    }
  }
}

401 Unauthorized

Copy

{
  "error":"unauthorized"}

403 Forbidden

Copy

{
  "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
`integer`	`-2,147,483,647` to `2,147,483,647`	`12`, `24`, `25`	Floating point numbers are accepted but they will be truncated to an `integer`. If you wish to keep the decimal part, use `float` instead. Values out of range will be discarded.	Yes
`float`	Single-precision 32-bit IEEE 754 floating point.	`12.343`, `123.33`	Floats greater than 32-bit will be converted to scientific notation.	Yes
`string`	UTF-8 character encoding	`Cody`, `gold`, `A string with a , comma`	Maximum 255 characters long	Yes
`date`	ISO 8601, e.g. `YYYY-MM-ddTHH:mm:ssZ`	`2017-02-06T18:25:32+0300`		Yes
`boolean`	`true` or `false`			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.