{"_id":"5600a22f0c703d19009531e1","project":"55e67aaa9cc7c62b00c4a1ea","category":{"_id":"55e67b5dde6fef23009480ca","__v":20,"pages":["55ed06c7023a81170018f163","55ed079b0d968e2100de8339","55ed0b530d968e2100de8345","55ed0bb078319821005005cf","55ed0df94fba582b0036a18a","55ed0e0c4fba582b0036a18d","55ed0ebd8da0b12100e64246","55ed10bec9d5b3350072ae9a","55ed11410d968e2100de834d","55ed118678319821005005d9","55ed121dc9d5b3350072ae9e","55ed12de8da0b12100e6424e","55ed13930d968e2100de8352","55ed140c4fba582b0036a196","55ed1902c9d5b3350072aebb","55ed197bc9d5b3350072aec0","55ee3dba1452cd0d009e5ee9","5600a22f0c703d19009531e1","5600c6b23aa0520d00da0c41","561da674e078f40d00eadd75"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-02T04:30:21.948Z","from_sync":false,"order":5,"slug":"rest-api","title":"REST API"},"__v":34,"parentDoc":null,"user":"55d2bd8e2463351700f67dd7","editedParams2":true,"version":{"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","__v":10,"createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"editedParams":true,"updates":["5a17921767c3ad002a3dce7a"],"next":{"pages":[],"description":""},"createdAt":"2015-09-22T00:34:55.413Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"name":"","code":"{\n  \"created_at\": \"2017-03-09T13:23:37.488Z\",\n  \"state\": \"scheduled\",\n  \"id\": \"58c157595c50nz000e347f79\",\n  \"to\": {\n    \"id\": \"589b54e38b1ny0000876e528\",\n    \"type\": \"Audience\"\n  },\n  \"notification\": {\n    \"id\": \"58c157595c50nz000e347f7a\", // The Notification ID to use with the Stats endpoint\n    \"created_at\": \"2017-03-09T13:23:37.502Z\",\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"category\": \"TEST_CATEGORY\",\n      \"any_key\": \"any_value\"\n    }\n  }\n}","language":"json","status":201},{"name":"","code":"// This error is given when your API client credentials are not correct. \n{\n  \"error\":\"unauthorized\"\n}","language":"json","status":401},{"status":403,"language":"json","code":"// This error is given when your API client does not have the ability to send Push Notifications.\n{\n  \"error\":\"your api client does not have the correct roles\"\n}"},{"code":"{\nerror: # Dependant on why the request body was incorrect. \n}\n\n","status":422,"language":"json"}]},"settings":"","examples":{"codes":[{"name":"On The Fly Audience","code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"events.video_plays\", \"criteria\": [{ \"gt\": 10 }]}, { \"name\": \"custom.string.video_category\", \"criteria\": [\"sports\"]}],\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"category\": \"TEST_CATEGORY\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'\n\n// Events sent via our API must be prefixed by `Public Api`. The same applies\n// if you're using auto-analytics.\ncurl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"events.Public Api.web_login\", \"criteria\": [{ \"gt\": 10 }]}],\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"category\": \"TEST_CATEGORY\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"json"},{"code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": { \"audience\" : \"55961e0741646178d0010010\" },\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"json","name":"Pre-defined Audience"},{"code":"// Note that you have to explicitly use an asterisk(*) to send a push notification to everyone.\ncurl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d ' {\n  \"notification\": {\n    \"to\":  \"*\",\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"json","name":"Everyone"},{"code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"user_id\", \"criteria\": [\"1234\"]}],\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"json","name":"Specific Users"},{"name":"Rich Push","language":"curl","code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"custom.string.mykey\", \"criteria\": [\"tag2\"]}],\n    \"payload\": {\n      \"alert\": \"Check out this rich push!\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"category\": \"TEST_CATEGORY\",\n      \"mutable_content\": true,\n      \"_st\": {\n        \"image_url\": \"https://www.mysite.com/img.png\"\n      }\n    }\n  }\n}'"},{"code":"# Users with custom attributes will receive something similar to:\n# \"Hello Simon, we just updated your Sneakers collection with brand new arrivals.\"\n\n# Users with no custom attributes will receive:\n# \"Hello there, we just updated your collection with brand new arrivals.\"\n\ncurl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\":  [{\"name\": \"device_id\", \"criteria\": [\"1234\", \"5678\", \"79894\"]}],\n    \"payload\": {\n      \"alert\": \"Hello {{custom.first_name | default: 'there'}}, we just updated your {{custom.favorite_collection}} collection with brand new arrivals.\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\"\n    }\n  }\n}'","language":"curl","name":"Liquid Template"},{"code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"sdk_location\",\n             \"criteria\": [{ \"point\": { \"latitude\": -41.1339, \"longitude\": 174.8406 },\n                            \"distance\": 4, \"unit\": \"kilometers\" }] }],\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"curl","name":"Distance filter"},{"code":"curl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"location\",\n             \"criteria\": [{ \"polygon\":\n                [{ \"latitude\": -41.31243, \"longitude\": 174.75154 }, \n                 { \"latitude\": -41.30341, \"longitude\": 174.96063 }, \n                 { \"latitude\": -41.19293, \"longitude\": 174.91806 }, \n                 { \"latitude\": -41.20029, \"longitude\": 174.76511 }]\n        }] }],\n    \"payload\": {\n      \"alert\": \"This is a push notification test\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"any_key\": \"any_value\" // Arbitrary keys/values.\n    }\n  }\n}'","language":"curl","name":"Polygon filter"},{"name":"Update push","language":"curl","code":"# Define a collapse_key you can reuse in subsequent calls. In this case, our collapse_key is notification_19cbba0022\n\ncurl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"user_id\", \"criteria\": [\"1234\"]}],\n    \"payload\": {\n      \"alert\": \"Story developing: highest attendance on records for the 4th of July parade.\",\n      \"badge\": 1,\n      \"collapse_key\": \"notification_19cbba0022\",\n      \"sound\": \"Default.caf\"\n    }\n  }\n}'\n\n# Send an update by referencing the same collapse key, but changing the push payload\ncurl -X POST -u :API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n  \"notification\": {\n    \"to\": [{ \"name\": \"user_id\", \"criteria\": [\"1234\"]}],\n    \"payload\": {\n      \"alert\": \"Update: highest attendance on records for the 4th of July parade. Over one million people attended the event.\",\n      \"badge\": 1,\n      \"_u\": \"https://example.com/story/19cbba0022/4th-july-parade\",\n      \"collapse_key\": \"notification_19cbba0022\",\n      \"sound\": \"Default.caf\"\n    }\n  }\n}'\n"}]},"auth":"required","params":[{"_id":"5673834022cd7e0d00fada03","ref":"","in":"body","required":false,"desc":"JSON model of notification","default":"","type":"object","name":"notification"}],"url":"/notifications"},"isReference":true,"order":1,"body":"## To Field \n\nThere are three options for target devices:\n * `\"*\"`: will target everyone\n * `{ \"audience\": \"AUDIENCE_ID\" }`: an object with key `audience` and the value being the Audience ID. Will target all users in the specified audience. You can retrieve an ID via [Audiences API](doc:audiences) or as a result of creating an on-the-fly audience (see below).\n * `[{ \"name\": \"CRITERIA_TYPE\", \"criteria\": [CRITERIA_1, CRITERIA_2, …]}, {…}]`: an array of one or more filters for creating an on-the-fly audience (see **Filters** below). Will target devices that match the specified criteria.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Be extremely careful with this endpoint during testing, especially when using `\\\"to\\\": \\\"*\\\"` . We recommend setting up a different app on Carnival from your production app to avoid accidental communication with your users.\",\n  \"title\": \"Sending to All\"\n}\n[/block]\n## Targeting test devices\nYou can send notification to your testers by flagging your test devices as 'development' within the Carnival dashboard (see [Testing Developer Push Notifications])(doc:testing-developer-push-notifications). When you do so, you can send a push notification to your devices by creating this audience:\n`[{\"name\": \"development\", \"criteria\": [true]}]`\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Testing notifications on iOS\",\n  \"body\": \"By default, Xcode builds your app against the Debug scheme, which maps to your Development provisioning profile which in turn can only talk to the Sandbox APNS.\\n\\nIf your Xcode scheme is Debug, make sure to target your Device ID using an on-the-fly audience, and make sure your device is in development mode. You can set this up here: [Testing Developer Push Notifications](https://docs.carnival.io/v1.0/docs/testing-developer-push-notifications).\"\n}\n[/block]\n### Filters\n\nA filter is an object composed of three attributes: `name`, `criteria` and `not_filter`.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Filter attribute\",\n    \"h-1\": \"Details\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String. Device attribute on which the criteria will be applied.\\n\\nExample: `{ \\\"name\\\": \\\"locale\\\", criteria: [\\\"en_US\\\"] }` will match devices with en_US locale. See the list of valid names/attributes below.\",\n    \"1-0\": \"`criteria`\",\n    \"1-1\": \"Array with values to match.\\n\\nProvide at least one element of type string, integer, float, boolean or a range object (see below how to define a range object).\",\n    \"2-0\": \"`not_filter`\",\n    \"2-1\": \"Boolean. When `true`, it will match devices that don't match the criteria. Default is `false`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n#### Valid names/attributes for a filter\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name/Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`locale`\",\n    \"1-0\": \"`time_zone`\",\n    \"2-0\": \"`created_at`\",\n    \"3-0\": \"`registered_at`\",\n    \"4-0\": \"`badge`\",\n    \"5-0\": \"`os_name`\",\n    \"6-0\": \"`os_version`\",\n    \"7-0\": \"`app_version`\",\n    \"8-0\": \"`sdk_version`\",\n    \"9-0\": \"`device_id`\",\n    \"10-0\": \"`country`\",\n    \"0-1\": \"Locale used on the device, specified as a combination of [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) e.g. `en_NZ`, `fr_FR`.\",\n    \"1-1\": \"Time zone used on the device. Possible values can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\",\n    \"2-1\": \"Date of device registration\",\n    \"3-1\": \"Date of last device update\",\n    \"4-1\": \"Current badge count\",\n    \"5-1\": \"Device OS name\",\n    \"6-1\": \"Device OS version\",\n    \"7-1\": \"App version\",\n    \"8-1\": \"Carnival SDK version\",\n    \"9-1\": \"Carnival generated Device ID\",\n    \"10-1\": \"Country based on user location (can be inaccurate, since sometimes the user don't enable GPS tracking and this value be defined using the user IP). Refer to [Known Countries](doc:known-countries) for a list of valid values.\",\n    \"11-0\": \"`marketing_name`\",\n    \"11-1\": \"Device model.\\n\\nExamples: `iPhone 5`, `iPhone 6`, `Samsung Galaxy S5`\",\n    \"12-0\": \"`user_id`\",\n    \"12-1\": \"The ID assigned to the user.\",\n    \"13-0\": \"`development`\",\n    \"13-1\": \"Whether or not to target development devices. Boolean.\",\n    \"14-0\": \"`location`\",\n    \"14-1\": \"Last available location of the user (being GeoIP or GPS location).\",\n    \"15-0\": \"`sdk_location`\",\n    \"15-1\": \"Last available GPS location of the user.\"\n  },\n  \"cols\": 2,\n  \"rows\": 16\n}\n[/block]\nYou can see valid values for these keys by querying Audience Builder in the dashboard.\n\n#### Filtering by custom attributes\n\nThe filter name should be composed as follows: `custom.` + `type of attribute (string, integer, float, date or boolean).` + `attribute_name`.\n\nExamples:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data type\",\n    \"h-1\": \"Prefix\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"String\",\n    \"0-1\": \"`custom.string.`\",\n    \"0-2\": \"`custom.string.favorite_color`\",\n    \"1-0\": \"Date\",\n    \"1-1\": \"`custom.date.`\",\n    \"1-2\": \"`custom.date.last_purchased`\",\n    \"2-0\": \"Integer\",\n    \"2-1\": \"`custom.integer.`\",\n    \"2-2\": \"`custom.integer.tier_points`\",\n    \"3-0\": \"Float\",\n    \"3-1\": \"`custom.float.`\",\n    \"3-2\": \"`custom.float.lifetime_value`\",\n    \"4-0\": \"Boolean\",\n    \"4-1\": \"`custom.boolean.`\",\n    \"4-2\": \"`custom.boolean.is_paid_user`\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n#### Filtering by custom events\n\nThe filter name should be composed as follows: `events.` + source + event name. Events collected by the SDK do not have a source.\n\nExamples:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Source\",\n    \"h-1\": \"Prefix\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"SDK\",\n    \"0-1\": \"`events.`\",\n    \"0-2\": \"`events.checkout_completed`\",\n    \"1-0\": \"Events collected via [Devices / Events](doc:devices-events) or [Users / Events](doc:users-events)\",\n    \"1-1\": \"`events.Public Api.`\",\n    \"1-2\": \"`events.Public Api.instore_purchase_completed`\",\n    \"2-0\": \"Auto Analytics: [Google Analytics](https://docs.carnival.io/docs/collecting-user-data#section-google-analytics)\",\n    \"2-1\": \"`events.Google Analytics.`\",\n    \"2-2\": \"`events.Google Analytics.message_stream_user`\",\n    \"3-0\": \"Auto Analytics: [Adobe Analytics](https://docs.carnival.io/docs/collecting-user-data#section-adobe-analytics)\",\n    \"3-1\": \"`events.Adobe Analytics.`\",\n    \"3-2\": \"`events.Adobe Analytics.checkout_started`\",\n    \"4-0\": \"Auto Analytics: [Mixpanel](https://docs.carnival.io/docs/collecting-user-data#section-mixpanel)\",\n    \"4-1\": \"`events.Mixpanel.`\",\n    \"4-2\": \"`events.Mixpanel.tutorial_started`\",\n    \"5-0\": \"Auto Analytics: [Localytics](https://docs.carnival.io/docs/collecting-user-data#section-localytics)\",\n    \"5-1\": \"`events.Localytics.`\",\n    \"5-2\": \"`events.Localytics.tutorial_completed`\",\n    \"6-1\": \"`events.Flurry Analytics.`\",\n    \"6-2\": \"`events.Flurry Analytics.shared_post_on_twitter`\",\n    \"6-0\": \"Auto Analytics: [Flurry](https://docs.carnival.io/docs/collecting-user-data#section-flurry)\",\n    \"7-0\": \"Auto Analytics: [Amplitude](https://docs.carnival.io/docs/collecting-user-data#section-amplitude)\",\n    \"7-1\": \"`events.Amplitude.`\",\n    \"7-2\": \"`events.Amplitude.video_played`\"\n  },\n  \"cols\": 3,\n  \"rows\": 8\n}\n[/block]\n##### Specifying criteria ranges\n\nA range is an object with at least of the following keys: `gt`, `lt`, `gte` and `lte`.\n\nExamples of valid ranges:\n\n* `{ \"gt\": 0 }` returns values greater than 0\n* `{ \"gt\": 0, \"lt\": 10 }` returns values greater than zero and less than 10 (non-inclusive)\n* `{ \"gte\": 0 }` returns values greater than or equal to 0\n* `{ \"gt\": \"now-1d\" }` return devices where this event have hapenned after yesterday\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Range key\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`gt`\",\n    \"1-0\": \"`lt`\",\n    \"2-0\": \"`gte`\",\n    \"3-0\": \"`lte`\",\n    \"0-1\": \"Greater than value\",\n    \"1-1\": \"Less than value\",\n    \"2-1\": \"Greater than or equal to value\",\n    \"3-1\": \"Less than or equal to value\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n###### Using Math Date for event last happened at\nYou can filter devices by the last time that an event happened. You do it using the same criteria range method but with a special math date syntax.\n\nExample of valid math date ranges:\n* `{ \"gt\": \"now-1d\" }` return devices where this event happened after yesterday\n* `{ \"gt\": \"now-2M\" }` return devices where this event happened after 2 months ago\n* `{ \"gt\": \"now-2w\" }` return devices where this event happened after 2 weeks ago\n* `{ \"lt\": \"now-1y\" }` return devices where this event happened before 1 year ago\n* `{ \"gt\": \"now-1y\", \"lt\": \"now-1d\" }` return devices where this event happened between 1 year ago and yesterday\n\nThe supported units are:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Letter\",\n    \"h-1\": \"Unit\",\n    \"0-0\": \"y\",\n    \"0-1\": \"years\",\n    \"1-0\": \"M\",\n    \"1-1\": \"months\",\n    \"2-0\": \"w\",\n    \"3-0\": \"d\",\n    \"4-0\": \"`h` or `H`\",\n    \"5-0\": \"`m`\",\n    \"6-0\": \"`s`\",\n    \"2-1\": \"weeks\",\n    \"3-1\": \"days\",\n    \"4-1\": \"hours\",\n    \"5-1\": \"minutes\",\n    \"6-1\": \"seconds\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\nMore examples of supported Math Date expressions:\n\n* `now+1h`: The current time plus one hour, with ms resolution.\n* `now+1h+1m`: The current time plus one hour plus one minute, with ms resolution.\n* `now+1h/d`: The current time plus one hour, rounded down to the nearest day.\n* `2015-01-01||+1M/d`: 2015-01-01 plus one month, rounded down to the nearest day.\n\n#### Filtering by distance\n\n`location` and `sdk_location` are the only fields that can be filtered by distance.\n\nThe filter criteria must have the following keys:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"point\",\n    \"1-0\": \"distance\",\n    \"2-0\": \"unit\",\n    \"0-1\": \"A latitude and longitude object\",\n    \"h-2\": \"Example\",\n    \"1-1\": \"A number\",\n    \"2-1\": \"The unit of distance used. It can be one of the following: in, inch, yd, yards, ft, feet, km, kilometers, nauticalmiles, mi, miles m, meters\",\n    \"1-2\": \"`10.5`\",\n    \"2-2\": \"`\\\"kilometers\\\"`\",\n    \"0-2\": \"`{ \\\"latitude\\\" : -41.28664, \\\"longitude\\\" : 174.77557 }`\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nExample:\n\n```json\n{ \n  \"name\": \"sdk_location\", \n  \"criteria\": [{ \"point\" : { \"latitude\" : -41.1339, \"longitude\": 174.8406 }, \n                    \"distance\" : 4, \"unit\" : \"kilometers\" }] }\n```\n\n#### Filtering by a polygon\n\n`location` and `sdk_location` are the only fields that can be filtered by a polygon.\n\nThe filter criteria must have the key `polygon` with at least 3 points with `latitude` and `longitude`. Example:\n\n```json\n{ \n  \"name\": \"location\",\n  \"criteria\": [{ \"polygon\" :\n    [{ \"latitude\" :-41.31243, \"longitude\" : 174.75154 }, \n     { \"latitude\" :-41.30341, \"longitude\" : 174.96063 }, \n     { \"latitude\" :-41.19293, \"longitude\" : 174.91806 }, \n     { \"latitude\" :-41.20029, \"longitude\" : 174.76511 }]\n   }] \n}\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Polygon & Distance combined\",\n  \"body\": \"Polygon and distance filters can be mixed in a single criteria. For example:\\n\\n```json\\n{ \\n  \\\"name\\\": \\\"location\\\",\\n  \\\"criteria\\\": [\\n    { \\\"point\\\" : { \\\"latitude\\\" : -41.1339, \\\"longitude\\\": 174.8406 }, \\n                      \\\"distance\\\" : 4, \\\"unit\\\" : \\\"kilometers\\\" },\\n    { \\\"polygon\\\" :\\n      [{ \\\"latitude\\\" :-41.31243, \\\"longitude\\\" : 174.75154 }, \\n       { \\\"latitude\\\" :-41.30341, \\\"longitude\\\" : 174.96063 }, \\n       { \\\"latitude\\\" :-41.19293, \\\"longitude\\\" : 174.91806 }, \\n       { \\\"latitude\\\" :-41.20029, \\\"longitude\\\" : 174.76511 }]  }\\n  ] \\n}\\n```\"\n}\n[/block]\n## Updating notifications\nYou can update a notification (including its payload) by specifying a `collapse_key` in the notification payload. This key acts as a unique identifier, so that you can reference the same notification in subsequent Notifications API requests. \n\n## Message attributes\nYou can include a hash inside the request `payload` using the `custom` key. For example, if you had a message stream that had multiple categories, you could have a hash like:\n\n`\"custom\" :  { \"category\" : \"announcements\" } `\n\n## On-the-fly audiences\nOn-the-fly audiences are persisted in your list of Audiences. When you send a notification, we return an audience ID in the response. You can use the Audience ID in the `to.id` to [retrieve your Audience](doc:audience) ] for example when you want to check the targeted device count, or to [get a list of devices](doc:audiences-devices) in this audience.\n\nYou will be given one Audience ID for each on-the-fly audience. If you use the same on-the-fly spec more than once you will be given the same Audience ID.\n\nThis example shows you how to create an on-the-fly audience, retrieve its ID and device count, and reuse it to send a push notification at a later stage.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// First, create an on-the-fly audience when sending a push notification\\ncurl -X POST -u :WRITE_API_KEY -H \\\"Content-type: application/json\\\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\\n  \\\"notification\\\": {\\n    \\\"to\\\": [{ \\\"name\\\": \\\"events.video_plays\\\", \\\"criteria\\\": [{ \\\"gt\\\": 10 }]}, { \\\"name\\\": \\\"custom.string.mykey\\\", \\\"criteria\\\": [\\\"tag2\\\"]}],\\n    \\\"payload\\\": { /* Your push payload goes here */ }\\n  }\\n}'\\n\\n// The response will be similar to this:\\n{\\n  \\\"created_at\\\": \\\"2017-03-09T13:23:37.488Z\\\",\\n  \\\"state\\\": \\\"scheduled\\\",\\n  \\\"id\\\": \\\"58c157595c50nz000e347f79\\\",\\n  \\\"to\\\": {\\n    \\\"id\\\": \\\"589b54e38b1ny0000876e528\\\",\\n    \\\"type\\\": \\\"Audience\\\"\\n  },\\n  \\\"notification\\\": { /* Notification payload */ }\\n}\\n\\n// Next, use the `to.id` value to check the targeted device count.\\n// Make sure your API Key has Read permissions.\\ncurl -X GET -u :READ_API_KEY https://api.carnivalmobile.com/v5/audiences/589b54e38b1ny0000876e528\\n\\n// Response\\n{\\n    \\\"audience\\\": {\\n        \\\"name\\\": \\\"api_audience_571a2cb135c4f3008028728_f9b10204a59727a528a4d33d262591f33de7f9fad977e4e1fb70aa4d533b162\\\",\\n        \\\"created_at\\\": \\\"2017-03-21T19:39:25.324Z\\\",\\n        \\\"updated_at\\\": \\\"2017-03-21T19:39:25.324Z\\\",\\n        \\\"id\\\": \\\"589b54e38b1ny0000876e528\\\",\\n        \\\"device_count\\\": 42\\n    }\\n}\\n\\n// You can reuse this on-the-fly audience for another push by specifying its ID\\ncurl -X POST -u :WRITE_API_KEY -H \\\"Content-type: application/json\\\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\\n  \\\"notification\\\": {\\n    \\\"to\\\": { \\\"audience\\\": \\\"589b54e38b1ny0000876e528\\\" },\\n    \\\"payload\\\": { /* Your push payload goes here */ }\\n  }\\n}'\",\n      \"language\": \"json\",\n      \"name\": \"Working with on-the-fly audiences\"\n    }\n  ]\n}\n[/block]\n## Custom Keys and Values\nSome keys are reserved by the Apple, Google Cloud Message and/or Carnival system:\n\n * `alert`\n * `sound`\n * `badge`\n * `category`\n * `mutable_content`\n * `content_available`\n * `available`\n * `from`\n * `gcm`\n * `_st`\n * `_u` (used for [Deep Linking](doc:deep-linking))\n * Any value prefixed by `google`\n\nOther keys and values will be assumed to be custom keys, and will be included in the push payload.","excerpt":"Send push notifications to segments of your users.","slug":"notifications","type":"endpoint","title":"Notifications"}

postNotifications

Send push notifications to segments of your users.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

notification:
object
JSON model of notification

Examples


Result Format


Documentation

## To Field There are three options for target devices: * `"*"`: will target everyone * `{ "audience": "AUDIENCE_ID" }`: an object with key `audience` and the value being the Audience ID. Will target all users in the specified audience. You can retrieve an ID via [Audiences API](doc:audiences) or as a result of creating an on-the-fly audience (see below). * `[{ "name": "CRITERIA_TYPE", "criteria": [CRITERIA_1, CRITERIA_2, …]}, {…}]`: an array of one or more filters for creating an on-the-fly audience (see **Filters** below). Will target devices that match the specified criteria. [block:callout] { "type": "warning", "body": "Be extremely careful with this endpoint during testing, especially when using `\"to\": \"*\"` . We recommend setting up a different app on Carnival from your production app to avoid accidental communication with your users.", "title": "Sending to All" } [/block] ## Targeting test devices You can send notification to your testers by flagging your test devices as 'development' within the Carnival dashboard (see [Testing Developer Push Notifications])(doc:testing-developer-push-notifications). When you do so, you can send a push notification to your devices by creating this audience: `[{"name": "development", "criteria": [true]}]` [block:callout] { "type": "info", "title": "Testing notifications on iOS", "body": "By default, Xcode builds your app against the Debug scheme, which maps to your Development provisioning profile which in turn can only talk to the Sandbox APNS.\n\nIf your Xcode scheme is Debug, make sure to target your Device ID using an on-the-fly audience, and make sure your device is in development mode. You can set this up here: [Testing Developer Push Notifications](https://docs.carnival.io/v1.0/docs/testing-developer-push-notifications)." } [/block] ### Filters A filter is an object composed of three attributes: `name`, `criteria` and `not_filter`. [block:parameters] { "data": { "h-0": "Filter attribute", "h-1": "Details", "0-0": "`name`", "0-1": "String. Device attribute on which the criteria will be applied.\n\nExample: `{ \"name\": \"locale\", criteria: [\"en_US\"] }` will match devices with en_US locale. See the list of valid names/attributes below.", "1-0": "`criteria`", "1-1": "Array with values to match.\n\nProvide at least one element of type string, integer, float, boolean or a range object (see below how to define a range object).", "2-0": "`not_filter`", "2-1": "Boolean. When `true`, it will match devices that don't match the criteria. Default is `false`." }, "cols": 2, "rows": 3 } [/block] #### Valid names/attributes for a filter [block:parameters] { "data": { "h-0": "Name/Attribute", "h-1": "Description", "0-0": "`locale`", "1-0": "`time_zone`", "2-0": "`created_at`", "3-0": "`registered_at`", "4-0": "`badge`", "5-0": "`os_name`", "6-0": "`os_version`", "7-0": "`app_version`", "8-0": "`sdk_version`", "9-0": "`device_id`", "10-0": "`country`", "0-1": "Locale used on the device, specified as a combination of [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) and [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) e.g. `en_NZ`, `fr_FR`.", "1-1": "Time zone used on the device. Possible values can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "2-1": "Date of device registration", "3-1": "Date of last device update", "4-1": "Current badge count", "5-1": "Device OS name", "6-1": "Device OS version", "7-1": "App version", "8-1": "Carnival SDK version", "9-1": "Carnival generated Device ID", "10-1": "Country based on user location (can be inaccurate, since sometimes the user don't enable GPS tracking and this value be defined using the user IP). Refer to [Known Countries](doc:known-countries) for a list of valid values.", "11-0": "`marketing_name`", "11-1": "Device model.\n\nExamples: `iPhone 5`, `iPhone 6`, `Samsung Galaxy S5`", "12-0": "`user_id`", "12-1": "The ID assigned to the user.", "13-0": "`development`", "13-1": "Whether or not to target development devices. Boolean.", "14-0": "`location`", "14-1": "Last available location of the user (being GeoIP or GPS location).", "15-0": "`sdk_location`", "15-1": "Last available GPS location of the user." }, "cols": 2, "rows": 16 } [/block] You can see valid values for these keys by querying Audience Builder in the dashboard. #### Filtering by custom attributes The filter name should be composed as follows: `custom.` + `type of attribute (string, integer, float, date or boolean).` + `attribute_name`. Examples: [block:parameters] { "data": { "h-0": "Data type", "h-1": "Prefix", "h-2": "Example", "0-0": "String", "0-1": "`custom.string.`", "0-2": "`custom.string.favorite_color`", "1-0": "Date", "1-1": "`custom.date.`", "1-2": "`custom.date.last_purchased`", "2-0": "Integer", "2-1": "`custom.integer.`", "2-2": "`custom.integer.tier_points`", "3-0": "Float", "3-1": "`custom.float.`", "3-2": "`custom.float.lifetime_value`", "4-0": "Boolean", "4-1": "`custom.boolean.`", "4-2": "`custom.boolean.is_paid_user`" }, "cols": 3, "rows": 5 } [/block] #### Filtering by custom events The filter name should be composed as follows: `events.` + source + event name. Events collected by the SDK do not have a source. Examples: [block:parameters] { "data": { "h-0": "Source", "h-1": "Prefix", "h-2": "Example", "0-0": "SDK", "0-1": "`events.`", "0-2": "`events.checkout_completed`", "1-0": "Events collected via [Devices / Events](doc:devices-events) or [Users / Events](doc:users-events)", "1-1": "`events.Public Api.`", "1-2": "`events.Public Api.instore_purchase_completed`", "2-0": "Auto Analytics: [Google Analytics](https://docs.carnival.io/docs/collecting-user-data#section-google-analytics)", "2-1": "`events.Google Analytics.`", "2-2": "`events.Google Analytics.message_stream_user`", "3-0": "Auto Analytics: [Adobe Analytics](https://docs.carnival.io/docs/collecting-user-data#section-adobe-analytics)", "3-1": "`events.Adobe Analytics.`", "3-2": "`events.Adobe Analytics.checkout_started`", "4-0": "Auto Analytics: [Mixpanel](https://docs.carnival.io/docs/collecting-user-data#section-mixpanel)", "4-1": "`events.Mixpanel.`", "4-2": "`events.Mixpanel.tutorial_started`", "5-0": "Auto Analytics: [Localytics](https://docs.carnival.io/docs/collecting-user-data#section-localytics)", "5-1": "`events.Localytics.`", "5-2": "`events.Localytics.tutorial_completed`", "6-1": "`events.Flurry Analytics.`", "6-2": "`events.Flurry Analytics.shared_post_on_twitter`", "6-0": "Auto Analytics: [Flurry](https://docs.carnival.io/docs/collecting-user-data#section-flurry)", "7-0": "Auto Analytics: [Amplitude](https://docs.carnival.io/docs/collecting-user-data#section-amplitude)", "7-1": "`events.Amplitude.`", "7-2": "`events.Amplitude.video_played`" }, "cols": 3, "rows": 8 } [/block] ##### Specifying criteria ranges A range is an object with at least of the following keys: `gt`, `lt`, `gte` and `lte`. Examples of valid ranges: * `{ "gt": 0 }` returns values greater than 0 * `{ "gt": 0, "lt": 10 }` returns values greater than zero and less than 10 (non-inclusive) * `{ "gte": 0 }` returns values greater than or equal to 0 * `{ "gt": "now-1d" }` return devices where this event have hapenned after yesterday [block:parameters] { "data": { "h-0": "Range key", "h-1": "Description", "0-0": "`gt`", "1-0": "`lt`", "2-0": "`gte`", "3-0": "`lte`", "0-1": "Greater than value", "1-1": "Less than value", "2-1": "Greater than or equal to value", "3-1": "Less than or equal to value" }, "cols": 2, "rows": 4 } [/block] ###### Using Math Date for event last happened at You can filter devices by the last time that an event happened. You do it using the same criteria range method but with a special math date syntax. Example of valid math date ranges: * `{ "gt": "now-1d" }` return devices where this event happened after yesterday * `{ "gt": "now-2M" }` return devices where this event happened after 2 months ago * `{ "gt": "now-2w" }` return devices where this event happened after 2 weeks ago * `{ "lt": "now-1y" }` return devices where this event happened before 1 year ago * `{ "gt": "now-1y", "lt": "now-1d" }` return devices where this event happened between 1 year ago and yesterday The supported units are: [block:parameters] { "data": { "h-0": "Letter", "h-1": "Unit", "0-0": "y", "0-1": "years", "1-0": "M", "1-1": "months", "2-0": "w", "3-0": "d", "4-0": "`h` or `H`", "5-0": "`m`", "6-0": "`s`", "2-1": "weeks", "3-1": "days", "4-1": "hours", "5-1": "minutes", "6-1": "seconds" }, "cols": 2, "rows": 7 } [/block] More examples of supported Math Date expressions: * `now+1h`: The current time plus one hour, with ms resolution. * `now+1h+1m`: The current time plus one hour plus one minute, with ms resolution. * `now+1h/d`: The current time plus one hour, rounded down to the nearest day. * `2015-01-01||+1M/d`: 2015-01-01 plus one month, rounded down to the nearest day. #### Filtering by distance `location` and `sdk_location` are the only fields that can be filtered by distance. The filter criteria must have the following keys: [block:parameters] { "data": { "h-0": "Key", "h-1": "Description", "0-0": "point", "1-0": "distance", "2-0": "unit", "0-1": "A latitude and longitude object", "h-2": "Example", "1-1": "A number", "2-1": "The unit of distance used. It can be one of the following: in, inch, yd, yards, ft, feet, km, kilometers, nauticalmiles, mi, miles m, meters", "1-2": "`10.5`", "2-2": "`\"kilometers\"`", "0-2": "`{ \"latitude\" : -41.28664, \"longitude\" : 174.77557 }`" }, "cols": 3, "rows": 3 } [/block] Example: ```json { "name": "sdk_location", "criteria": [{ "point" : { "latitude" : -41.1339, "longitude": 174.8406 }, "distance" : 4, "unit" : "kilometers" }] } ``` #### Filtering by a polygon `location` and `sdk_location` are the only fields that can be filtered by a polygon. The filter criteria must have the key `polygon` with at least 3 points with `latitude` and `longitude`. Example: ```json { "name": "location", "criteria": [{ "polygon" : [{ "latitude" :-41.31243, "longitude" : 174.75154 }, { "latitude" :-41.30341, "longitude" : 174.96063 }, { "latitude" :-41.19293, "longitude" : 174.91806 }, { "latitude" :-41.20029, "longitude" : 174.76511 }] }] } ``` [block:callout] { "type": "info", "title": "Polygon & Distance combined", "body": "Polygon and distance filters can be mixed in a single criteria. For example:\n\n```json\n{ \n \"name\": \"location\",\n \"criteria\": [\n { \"point\" : { \"latitude\" : -41.1339, \"longitude\": 174.8406 }, \n \"distance\" : 4, \"unit\" : \"kilometers\" },\n { \"polygon\" :\n [{ \"latitude\" :-41.31243, \"longitude\" : 174.75154 }, \n { \"latitude\" :-41.30341, \"longitude\" : 174.96063 }, \n { \"latitude\" :-41.19293, \"longitude\" : 174.91806 }, \n { \"latitude\" :-41.20029, \"longitude\" : 174.76511 }] }\n ] \n}\n```" } [/block] ## Updating notifications You can update a notification (including its payload) by specifying a `collapse_key` in the notification payload. This key acts as a unique identifier, so that you can reference the same notification in subsequent Notifications API requests. ## Message attributes You can include a hash inside the request `payload` using the `custom` key. For example, if you had a message stream that had multiple categories, you could have a hash like: `"custom" : { "category" : "announcements" } ` ## On-the-fly audiences On-the-fly audiences are persisted in your list of Audiences. When you send a notification, we return an audience ID in the response. You can use the Audience ID in the `to.id` to [retrieve your Audience](doc:audience) ] for example when you want to check the targeted device count, or to [get a list of devices](doc:audiences-devices) in this audience. You will be given one Audience ID for each on-the-fly audience. If you use the same on-the-fly spec more than once you will be given the same Audience ID. This example shows you how to create an on-the-fly audience, retrieve its ID and device count, and reuse it to send a push notification at a later stage. [block:code] { "codes": [ { "code": "// First, create an on-the-fly audience when sending a push notification\ncurl -X POST -u :WRITE_API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n \"notification\": {\n \"to\": [{ \"name\": \"events.video_plays\", \"criteria\": [{ \"gt\": 10 }]}, { \"name\": \"custom.string.mykey\", \"criteria\": [\"tag2\"]}],\n \"payload\": { /* Your push payload goes here */ }\n }\n}'\n\n// The response will be similar to this:\n{\n \"created_at\": \"2017-03-09T13:23:37.488Z\",\n \"state\": \"scheduled\",\n \"id\": \"58c157595c50nz000e347f79\",\n \"to\": {\n \"id\": \"589b54e38b1ny0000876e528\",\n \"type\": \"Audience\"\n },\n \"notification\": { /* Notification payload */ }\n}\n\n// Next, use the `to.id` value to check the targeted device count.\n// Make sure your API Key has Read permissions.\ncurl -X GET -u :READ_API_KEY https://api.carnivalmobile.com/v5/audiences/589b54e38b1ny0000876e528\n\n// Response\n{\n \"audience\": {\n \"name\": \"api_audience_571a2cb135c4f3008028728_f9b10204a59727a528a4d33d262591f33de7f9fad977e4e1fb70aa4d533b162\",\n \"created_at\": \"2017-03-21T19:39:25.324Z\",\n \"updated_at\": \"2017-03-21T19:39:25.324Z\",\n \"id\": \"589b54e38b1ny0000876e528\",\n \"device_count\": 42\n }\n}\n\n// You can reuse this on-the-fly audience for another push by specifying its ID\ncurl -X POST -u :WRITE_API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d '{\n \"notification\": {\n \"to\": { \"audience\": \"589b54e38b1ny0000876e528\" },\n \"payload\": { /* Your push payload goes here */ }\n }\n}'", "language": "json", "name": "Working with on-the-fly audiences" } ] } [/block] ## Custom Keys and Values Some keys are reserved by the Apple, Google Cloud Message and/or Carnival system: * `alert` * `sound` * `badge` * `category` * `mutable_content` * `content_available` * `available` * `from` * `gcm` * `_st` * `_u` (used for [Deep Linking](doc:deep-linking)) * Any value prefixed by `google` Other keys and values will be assumed to be custom keys, and will be included in the push payload.

User Information

Try It Out

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