{"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/v5/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/v5/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/v4/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/v4/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/v4/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/v4/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/v4/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/v4/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/v4/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/v4/devices/:device_id","language":"curl","name":"Multiple types"}]},"method":"put","params":[{"name":"device_id","type":"string","default":"","desc":"The Carnival 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":3,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5b1f2cbdfd653400031d8d63","parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d2bd8e2463351700f67dd7","__v":12,"githubsync":"","createdAt":"2015-09-07T04:33:23.735Z","editedParams2":true,"version":{"version":"1.3","version_clean":"1.3.0","codename":"rebrand","is_stable":false,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5b1f2cbdfd653400031d8d42","5b1f2cbdfd653400031d8d43","5b1f2cbdfd653400031d8d44","5b1f2cbdfd653400031d8d45","5b1f2cbdfd653400031d8d46","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5b1f2cbdfd653400031d8d47","5b1f2cbdfd653400031d8d48","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2"],"_id":"5b1f2cbdfd653400031d8d9f","project":"55e67aaa9cc7c62b00c4a1ea","__v":0,"forked_from":"55e67aab9cc7c62b00c4a1ed","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z"},"editedParams":true,"category":{"sync":{"isSync":false,"url":""},"pages":["5b1f2cbdfd653400031d8d59","55ed079b0d968e2100de8339","5b1f2cbdfd653400031d8d5a","55ed0bb078319821005005cf","5b1f2cbdfd653400031d8d5b","5b1f2cbdfd653400031d8d5c","5b1f2cbdfd653400031d8d5d","5b1f2cbdfd653400031d8d5e","5b1f2cbdfd653400031d8d5f","5b1f2cbdfd653400031d8d60","5b1f2cbdfd653400031d8d61","5b1f2cbdfd653400031d8d62","5b1f2cbdfd653400031d8d63","5b1f2cbdfd653400031d8d64","5b1f2cbdfd653400031d8d65","5b1f2cbdfd653400031d8d66","5b1f2cbdfd653400031d8d67","5b1f2cbdfd653400031d8d6f","5b1f2cbdfd653400031d8d70","5b1f2cbdfd653400031d8d78"],"title":"REST API","slug":"rest-api","order":5,"from_sync":false,"reference":true,"_id":"5b1f2cbdfd653400031d8d44","__v":20,"createdAt":"2015-09-02T04:30:21.948Z","project":"55e67aaa9cc7c62b00c4a1ea","version":"5b1f2cbdfd653400031d8d9f"}}