{"_id":"5b720760c44b7600034b79ca","parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d2bd8e2463351700f67dd7","__v":13,"githubsync":"","editedParams2":true,"version":{"_id":"5b720760c44b7600034b7a08","project":"55e67aaa9cc7c62b00c4a1ea","__v":0,"forked_from":"5b1f2cbdfd653400031d8d9f","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["5b720760c44b7600034b79a7","5b720760c44b7600034b79a8","5b720760c44b7600034b79a9","5b720760c44b7600034b79aa","5b720760c44b7600034b79ab","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5b720760c44b7600034b79ac","5b720760c44b7600034b79ad","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"API V6","version_clean":"1.4.0","version":"1.4"},"editedParams":true,"category":{"_id":"5b720760c44b7600034b79a9","__v":20,"pages":["5b720760c44b7600034b79c0","55ed079b0d968e2100de8339","5b720760c44b7600034b79c1","55ed0bb078319821005005cf","5b720760c44b7600034b79c2","5b720760c44b7600034b79c3","5b720760c44b7600034b79c4","5b720760c44b7600034b79c5","5b720760c44b7600034b79c6","5b720760c44b7600034b79c7","5b720760c44b7600034b79c8","5b720760c44b7600034b79c9","5b720760c44b7600034b79ca","5b720760c44b7600034b79cb","5b720760c44b7600034b79cc","5b720760c44b7600034b79cd","5b720760c44b7600034b79ce","5b720760c44b7600034b79d6","5b720760c44b7600034b79d7","5b720760c44b7600034b79df"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"5b720760c44b7600034b7a08","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-02T04:30:21.948Z","from_sync":false,"order":5,"slug":"rest-api","title":"REST API"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-07T04:33:23.735Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","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}","name":""},{"status":401,"language":"json","code":"{\n  \"error\":\"unauthorized\"\n}","name":""},{"status":403,"language":"text","code":"{\n  \"error\":\"your api client does not have the correct roles\"\n}"}]},"settings":"","examples":{"codes":[{"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","name":"Date","language":"curl"},{"name":"String","language":"curl","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"},{"name":"Boolean","language":"curl","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"},{"name":"Float","language":"curl","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"},{"name":"Integer","language":"curl","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"},{"name":"Multiple types","language":"curl","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\": \"joshsmith@example.com\",\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"}]},"method":"put","apiSetting":null,"auth":"required","params":[{"_id":"55ed121dc9d5b3350072ae9f","ref":"","in":"path","required":true,"desc":"The Carnival device ID","default":"","type":"string","name":"device_id"},{"_id":"55ed13930d968e2100de8353","ref":"","in":"body","required":true,"desc":"JSON model of device Attributes","default":"","type":"object","name":"device"},{"_id":"5aef8cb952bc180003445178","ref":"","in":"body","required":false,"desc":"A unique identifier for a user, generally mapping to an ID in your internal CRM/Backend","default":"","type":"string","name":"device.user_id"},{"_id":"5aef8cb952bc180003445177","ref":"","in":"body","required":false,"desc":"The device's user's email address","default":"","type":"string","name":"device.user_email"},{"_id":"5aef8cb952bc180003445176","ref":"","in":"body","required":false,"desc":"A list of tags that apply to the given device","default":"","type":"array_string","name":"device.tags"},{"_id":"5aef8cb952bc180003445175","ref":"","in":"body","required":false,"desc":"Custom data for the given device. More info on the structure of this hash below","default":"","type":"object","name":"device.user_attributes"}],"url":"/devices/:device_id"},"isReference":true,"order":4,"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.","excerpt":"Updates a device with custom attributes","slug":"devices","type":"endpoint","title":"Devices"}

putDevices

Updates a device with custom attributes

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

device_id:
required
string
The Carnival 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 }}