{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/devices/:device_id","auth":"required","results":{"codes":[{"name":"","code":"{\n\t\"device\": {\n    \"id\": \"123\",\n    \"user_id\": \"JSmithOTI\",\n    \"user_email\": \"joshsmith:::at:::example.com\",\n    \"push_token\": \"fake_token_string\",\n    \"tags\": [\"working\", \"man\"],\n    \"platform\": \"iOS\",\n    \"user_attributes\": {\n      \"my_date\": {\n        \"type\": \"date\",\n        \"value\": \"2012-04-23T18:25:00.000Z\"\n      }\n    },\n    \"user_events\": {\n      \"purchase_unlocked\": {\n        \"count\": 10,\n        \"first_happened_at\": \"2016-05-23T04:12:34.173Z\",\n        \"last_happened_at\": \"2016-05-24T04:12:34.173Z\"\n      }\n    },\n    \"location\": {\n      \"gps\": {\n        \"lat\": \"-41.12345\",\n        \"lng\": \"174.12345\"\n      },\n      \"geoip\": {\n        \"lat\": \"-41.0\",\n        \"lng\": \"174.0\",\n        \"city\": \"Wellington\",\n        \"country\": \"New Zealand\"\n      }\n    }\n  }\n}","language":"json","status":200},{"name":"","code":"{\n  \"error\":\"unauthorized\"\n}","language":"json","status":401},{"code":"{\n  \"error\":\"your api client does not have the correct roles\"\n}","language":"text","status":403}]},"settings":"","examples":{"codes":[{"language":"curl","name":"Date","code":"# Single attribute\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_date\": {\n          \"value\": \"2012-04-23T18:25:00Z\",\n          \"type\" : \"date\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id\n  \n# Array\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_dates_key\": {\n          \"value\": [\"2012-04-23T18:25:00Z\", \"2012-05-23T18:25:00Z\"],\n          \"type\": \"date\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id"},{"code":"# Single attribute\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_string_key\": {\n          \"value\": \"My string value\",\n          \"type\" : \"string\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id\n\n# Array\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"user\": {\n      \"custom\": {\n        \"my_strings_key\": { \n          \"value\": [\"Hello\", \"there\"],\n          \"type\" : \"string\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id","language":"curl","name":"String"},{"code":"# Booleans can only be set as single attributes\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_boolean_key\": {\n          \"value\": true,\n          \"type\": \"boolean\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id","language":"curl","name":"Boolean"},{"code":"# Single attribute\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_float_key\": { \n          \"value\": 2.14, \n          \"type\": \"float\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id\n  \n# Array\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_floats_key\": {\n          \"value\": [23.2, 3.141], \n          \"type\": \"float\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id","language":"curl","name":"Float"},{"code":"# Single attribute\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_integer_key\": { \n          \"value\": 123,\n          \"type\": \"integer\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/:$device_id\n  \n# Array\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n      \"user_attributes\": {\n        \"my_integers_key\": { \n          \"value\": [23, 3], \n          \"type\": \"integer\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id","language":"curl","name":"Integer"},{"code":"# You can set multiple attributes in the same request\ncurl -X PUT -u :$API_KEY -d \\\n  '{\n    \"device\": {\n    \t\"user_id\": \"JSmithOTI\",\n      \"user_email\": \"[email protected]\",\n      \"tags\": [\"working\", \"man\"],\n      \"user_attributes\": {\n        \"release_date\": {\n          \"value\": \"1965-12-03T01:15:00Z\",\n          \"type\" : \"date\"\n        },\n        \"favorite_song\": {\n          \"value\": \"Drive My Car\",\n          \"type\" : \"string\"\n        },\n        \"starred_tracks\": {\n          \"value\": [1, 6, 11],\n          \"type\": \"integer\"\n        }\n      }\n    }\n  }' -H 'Content-Type: application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/devices/$device_id","language":"curl","name":"Multiple types"}]},"method":"put","params":[{"name":"device_id","type":"string","default":"","desc":"The Sailthru Mobile device ID","required":true,"in":"path","ref":"","_id":"55ed121dc9d5b3350072ae9f"},{"name":"device","type":"object","default":"","desc":"JSON model of device Attributes","required":true,"in":"body","ref":"","_id":"55ed13930d968e2100de8353"},{"name":"device.user_id","type":"string","default":"","desc":"A unique identifier for a user, generally mapping to an ID in your internal CRM/Backend","required":false,"in":"body","ref":"","_id":"5aef8cb952bc180003445178"},{"name":"device.user_email","type":"string","default":"","desc":"The device's user's email address","required":false,"in":"body","ref":"","_id":"5aef8cb952bc180003445177"},{"name":"device.tags","type":"array_string","default":"","desc":"A list of tags that apply to the given device","required":false,"in":"body","ref":"","_id":"5aef8cb952bc180003445176"},{"name":"device.user_attributes","type":"object","default":"","desc":"Custom data for the given device. More info on the structure of this hash below","required":false,"in":"body","ref":"","_id":"5aef8cb952bc180003445175"}],"apiSetting":null},"next":{"description":"","pages":[]},"title":"Devices","type":"endpoint","slug":"devices","excerpt":"Updates a device with custom attributes","body":"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.\n\nNote that 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.\n\n## Valid Types\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data type\",\n    \"h-1\": \"Ranges/valid values\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"`integer`\",\n    \"h-3\": \"Notes\",\n    \"0-1\": \"`-2,147,483,647` to `2,147,483,647`\",\n    \"0-2\": \"`12`, `24`, `25`\",\n    \"0-3\": \"Floating point numbers are accepted but they will be truncated to an `integer`. If you wish to keep the decimal part, use `float` instead.\\n\\nValues out of range will be discarded.\",\n    \"1-0\": \"`float`\",\n    \"1-2\": \"`12.343`, `123.33`\",\n    \"2-0\": \"`string`\",\n    \"2-2\": \"`Cody`, `gold`, `A string with a , comma`\",\n    \"2-1\": \"UTF-8 character encoding\",\n    \"2-3\": \"Maximum 255 characters long\",\n    \"3-0\": \"`date`\",\n    \"3-1\": \"ISO 8601, e.g. `YYYY-MM-ddTHH:mm:ssZ`\",\n    \"3-2\": \"`2017-02-06T18:25:32+0300`\",\n    \"4-0\": \"`boolean`\",\n    \"4-1\": \"`true` or `false`\",\n    \"1-1\": \"Single-precision 32-bit IEEE 754 floating point.\",\n    \"1-3\": \"Floats greater than 32-bit will be converted to scientific notation.\",\n    \"4-3\": \"\",\n    \"h-4\": \"Can be sent as array\",\n    \"0-4\": \"Yes\",\n    \"1-4\": \"Yes\",\n    \"2-4\": \"Yes\",\n    \"3-4\": \"Yes\",\n    \"4-4\": \"No\"\n  },\n  \"cols\": 5,\n  \"rows\": 5\n}\n[/block]\n#### User Attributes Hash Structure\nUser 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"device\\\": {\\n    \\\"user_attributes\\\": { // Hash containing all the attributes we want to set\\n      \\\"first_name\\\": { // The name of the attribute\\n        \\\"type\\\": \\\"string\\\", // Attribute type as described above\\n        \\\"value\\\": \\\"Cody\\\" // The actual value of the attribute\\n      },\\n      \\\"last_name\\\": {\\n        \\\"type\\\": \\\"string\\\",\\n        \\\"value\\\": \\\"Buena\\\"\\n      }\\n      // + as many as 48 other attributes you want to set\\n    }\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"User Attributes\"\n    }\n  ]\n}\n[/block]\n#### Custom Attribute Limits\nThere are limits in place on the maximum number of custom attributes allowed as well as the length (size) of strings and arrays.\n\n* A maximum of **50** custom attributes is allowed per device. If you exceed this amount any new attributes being set will be discarded.\n* String values that have more than **255** characters will be truncated. The limitation is on the character length, not on the size in bytes.\n* Arrays with more than **50** elements will be truncated.\n\n#### Key Name Restrictions\nThere are some restrictions in place on the key name, these are:\n\n * **Only letters, numbers, underscore and dash are valid characters.**\n * Leading spaces will be removed. `\"         my_string_key         \"` will become `\"my_string_key\"`.\n * Invalid characters other than spaces and dots will be removed. `\"my_string_key~~~~\"` will become `\"my_string_key\"`.\n * Spaces and dots will be replaced for underscores. `\"my string.key\"` will become `\"my_string_key\"`.\n * Keys will be truncated to a maximum of 255 characters.\n * Invalid keys (including keys exclusively made of invalid characters) will simply be discarded and no error will be returned.","updates":[],"order":4,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5e6156bf5e4a51006dcd8142","parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d2bd8e2463351700f67dd7","__v":19,"githubsync":"","createdAt":"2015-09-07T04:33:23.735Z","editedParams2":true,"version":{"version":"1.5","version_clean":"1.5.0","codename":"ST Rebrand","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5e6156bf5e4a51006dcd8120","5e6156bf5e4a51006dcd8121","5e6156bf5e4a51006dcd8122","5e6156bf5e4a51006dcd8123","5e6156bf5e4a51006dcd8124","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5e6156bf5e4a51006dcd8125","5e6156bf5e4a51006dcd8126","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2","5e69868cbd5dcb006b35867b","5e6986ca2c6652006791b6e8"],"_id":"5e6156bf5e4a51006dcd818c","project":"55e67aaa9cc7c62b00c4a1ea","__v":2,"forked_from":"5b720760c44b7600034b7a08","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z"},"editedParams":true,"category":{"sync":{"isSync":false,"url":""},"pages":["5e6156bf5e4a51006dcd8138","55ed079b0d968e2100de8339","5e6156bf5e4a51006dcd8139","55ed0bb078319821005005cf","5e6156bf5e4a51006dcd813a","5e6156bf5e4a51006dcd813b","5e6156bf5e4a51006dcd813c","5e6156bf5e4a51006dcd813d","5e6156bf5e4a51006dcd813e","5e6156bf5e4a51006dcd813f","5e6156bf5e4a51006dcd8140","5e6156bf5e4a51006dcd8141","5e6156bf5e4a51006dcd8142","5e6156bf5e4a51006dcd8143","5e6156bf5e4a51006dcd8144","5e6156bf5e4a51006dcd8145","5b720760c44b7600034b79ce","5e6156bf5e4a51006dcd814d","5e6156bf5e4a51006dcd814e","5e6156bf5e4a51006dcd8156"],"title":"REST API","slug":"rest-api","order":5,"from_sync":false,"reference":true,"_id":"5e6156bf5e4a51006dcd8122","__v":20,"createdAt":"2015-09-02T04:30:21.948Z","project":"55e67aaa9cc7c62b00c4a1ea","version":"5e6156bf5e4a51006dcd818c"}}

putDevices

Updates a device with custom attributes

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

device_id:
required
string
The Sailthru Mobile device ID

Body Params

device:
required
object
JSON model of device Attributes
device.user_id:
string
A unique identifier for a user, generally mapping to an ID in your internal CRM/Backend
device.user_email:
string
The device's user's email address
device.tags:
array of strings
A list of tags that apply to the given device
device.user_attributes:
object
Custom data for the given device. More info on the structure of this hash below

Examples


Result Format


Documentation

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. Note that 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 [block:parameters] { "data": { "h-0": "Data type", "h-1": "Ranges/valid values", "h-2": "Example", "0-0": "`integer`", "h-3": "Notes", "0-1": "`-2,147,483,647` to `2,147,483,647`", "0-2": "`12`, `24`, `25`", "0-3": "Floating point numbers are accepted but they will be truncated to an `integer`. If you wish to keep the decimal part, use `float` instead.\n\nValues out of range will be discarded.", "1-0": "`float`", "1-2": "`12.343`, `123.33`", "2-0": "`string`", "2-2": "`Cody`, `gold`, `A string with a , comma`", "2-1": "UTF-8 character encoding", "2-3": "Maximum 255 characters long", "3-0": "`date`", "3-1": "ISO 8601, e.g. `YYYY-MM-ddTHH:mm:ssZ`", "3-2": "`2017-02-06T18:25:32+0300`", "4-0": "`boolean`", "4-1": "`true` or `false`", "1-1": "Single-precision 32-bit IEEE 754 floating point.", "1-3": "Floats greater than 32-bit will be converted to scientific notation.", "4-3": "", "h-4": "Can be sent as array", "0-4": "Yes", "1-4": "Yes", "2-4": "Yes", "3-4": "Yes", "4-4": "No" }, "cols": 5, "rows": 5 } [/block] #### 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: [block:code] { "codes": [ { "code": "{\n \"device\": {\n \"user_attributes\": { // Hash containing all the attributes we want to set\n \"first_name\": { // The name of the attribute\n \"type\": \"string\", // Attribute type as described above\n \"value\": \"Cody\" // The actual value of the attribute\n },\n \"last_name\": {\n \"type\": \"string\",\n \"value\": \"Buena\"\n }\n // + as many as 48 other attributes you want to set\n }\n }\n}", "language": "javascript", "name": "User Attributes" } ] } [/block] #### 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.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}