{"__v":21,"_id":"551ef4f04986f62b00a7205d","category":{"__v":4,"_id":"551ef4ef4986f62b00a72038","pages":["551ef4f04986f62b00a7205d","551ef4f04986f62b00a7205e","551ef4f04986f62b00a7205f","551ef4f04986f62b00a72060","551ef4f04986f62b00a72061","551ef4f04986f62b00a72062","551ef4f04986f62b00a72063","551ef4f04986f62b00a72064","551ef4f04986f62b00a72065","551ef4f04986f62b00a72066","551ef4f04986f62b00a72067","551ef4f04986f62b00a72068","551ef4f04986f62b00a72069","551ef4f04986f62b00a7206a","551ef4f04986f62b00a7206b","551ef4f04986f62b00a7206c","5523150ae20da719000e78c2","5641731cb0dc090d00f88398","56c2761847394f0d00e2285e"],"project":"542b6018044e1e2200413772","version":"551ef4ef4986f62b00a7202e","reference":false,"createdAt":"2014-10-22T01:34:57.891Z","from_sync":false,"order":16,"slug":"server-rest-api","title":"Server REST API"},"parentDoc":null,"project":"542b6018044e1e2200413772","user":"542b6010044e1e220041376f","version":{"__v":7,"_id":"551ef4ef4986f62b00a7202e","forked_from":"542b6018044e1e2200413775","project":"542b6018044e1e2200413772","createdAt":"2015-04-03T20:15:43.149Z","releaseDate":"2015-04-03T20:15:43.149Z","categories":["551ef4ef4986f62b00a7202f","551ef4ef4986f62b00a72030","551ef4ef4986f62b00a72031","551ef4ef4986f62b00a72032","551ef4ef4986f62b00a72033","551ef4ef4986f62b00a72034","551ef4ef4986f62b00a72035","551ef4ef4986f62b00a72036","551ef4ef4986f62b00a72037","551ef4ef4986f62b00a72038","551ef4ef4986f62b00a72039","551ef4ef4986f62b00a7203a","551ef4ef4986f62b00a7203b","551ef4ef4986f62b00a7203c","551ef4ef4986f62b00a7203d","551ef4ef4986f62b00a7203e","55d7f1879510f00d007ec727","56b94a5a9fc0de1700b60ae9","56bd0e48ac1c5c1900b2dbe4","56d74afc3eb4dd0b0020196a","5723ab8a1f41110e003081ed","576b4dd327d6252b00085422"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":["55aa905de2bdcb0d00c74649","56b2154b1bc8490d00701f16"],"createdAt":"2014-10-22T01:35:45.624Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"Our server API allows you to:\n\n1. Programmatically deliver notifications from your server or device to another device.\n2. Add, update, and fetch data for your users without using our mobile or web SDKs.\n\nOur API covers:\n\n1. **Apps**\n2. **Players** (also known as *devices* or *users*)\n3. **Notifications**\n\nOur API can be accessed using any regular HTTP library of your choice.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nSome API calls require authentication. There are two kinds of *keys*:\n\n- **App Key**  (found in your app > App Settings > Keys & IDs)\n- **User Key**  (found by clicking your email > API Keys)\n\nAlmost all every call that requires authentication will require your *App Key*. The *User Key* is only required when you view, create, or update apps.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Store Keys Securely\",\n  \"body\": \"Never store your key in publicly viewable code.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<a name=\\\"apps\\\"/>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Apps\"\n}\n[/block]\nAn app represents a single app / website across all the platforms it's released on. Each platform can be configured to send notifications.\n\n#Available /apps methods\n\n- [Fetch the details of all your apps (GET /apps)](/v2.0/docs/apps-view-apps)\n\n- [Fetch one app's details (GET /apps/:id)](/v2.0/docs/appsid)\n\n- [Create an app (POST /apps)](/v2.0/docs/apps-create-an-app)\n\n- [Update one app's details (PUT /apps/:id)](/v2.0/docs/appsid-update-an-app)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"User Key Required\",\n  \"body\": \"Each of these calls requires your User Key.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<a name=\\\"users\\\"/>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Players\"\n}\n[/block]\nEach OneSignal app can have many users, each of which corresponds to a unique user that has installed and run your application.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"A user has the following attributes:\",\n  \"body\": \"- app_id\\n- id\\n- device_type\\n- identifier\\n- language\\n- session_count\\n- last_active\\n- device_os\\n- timezone\\n- ad_id\\n- badge_count\\n- app_version\\n- created_at\\n- amount_spent\\n- tags\\n- duration\\n- invalid_identifier\\n- badge_count\\n\\nThe `id` and `created_at` values are assigned by the OneSignal API when a user is created. \\n\\n`app_id` is available on the OneSignal website after creating a new app. \\n\\n`invalid_identifier` is set to true in the following cases:\\n1. The user does not have an identifier, for instance if they declined the push notification permission.\\n2. If the user re-installed your app and a new user record was created for them\\n3. If they failed to receive a push notification because they uninstalled the app.\"\n}\n[/block]\n#Available /players methods#\n\n- [Fetch one user's details (GET /players/:id)](/v2.0/docs/playersid)\n\n- [Add a new user to an app (POST /players)](/v2.0/docs/players-add-a-device)\n\n- [Update one user's details (PUT /players/:id)](/v2.0/docs/playersid-1)\n\n- [Indicate a user started using your app (POST /players/:id/on_session)](/v2.0/docs/playersidon_session)\n\n- [Indicate a user made a purchase in your app (POST /players/:id/on_purchase)](doc:on_purchase)\n\n- [Update the total session time of a user (POST /players/:id/on_focus)](/v2.0/docs/playersidon_focus)\n[block:html]\n{\n  \"html\": \"<a name=\\\"notifications\\\"/>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Notifications\"\n}\n[/block]\nNotifications can be targeted to users by:\n\n- a set of user IDs, targeting one or many\n- a set of tags, matching all users in a single app that match each tag\n- a list of segments, sending to all users included in the segments\n\n#Available /notifications methods#\n\n- [Fetch all sent notifications' details GET /notifications](/v2.0/docs/notifications-view-notifications)\n\n- [Fetch a single sent notification's details (GET /notifications/:id)](/v2.0/docs/notificationsid-view-notification)\n\n- [Send a notification (POST /notifications)](/v2.0/docs/notifications-create-notification)\n\n- [Track that a notification was opened](/v2.0/docs/notificationsid-track-open)","excerpt":"","slug":"server-api-overview","type":"basic","title":"Overview"}

Introduction

iOS

Android

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Website Push

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap, Cordova, Ionic

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous

Overview

Our server API allows you to: 1. Programmatically deliver notifications from your server or device to another device. 2. Add, update, and fetch data for your users without using our mobile or web SDKs. Our API covers: 1. **Apps** 2. **Players** (also known as *devices* or *users*) 3. **Notifications** Our API can be accessed using any regular HTTP library of your choice. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] Some API calls require authentication. There are two kinds of *keys*: - **App Key** (found in your app > App Settings > Keys & IDs) - **User Key** (found by clicking your email > API Keys) Almost all every call that requires authentication will require your *App Key*. The *User Key* is only required when you view, create, or update apps. [block:callout] { "type": "warning", "title": "Store Keys Securely", "body": "Never store your key in publicly viewable code." } [/block] [block:html] { "html": "<a name=\"apps\"/>" } [/block] [block:api-header] { "type": "basic", "title": "Apps" } [/block] An app represents a single app / website across all the platforms it's released on. Each platform can be configured to send notifications. #Available /apps methods - [Fetch the details of all your apps (GET /apps)](/v2.0/docs/apps-view-apps) - [Fetch one app's details (GET /apps/:id)](/v2.0/docs/appsid) - [Create an app (POST /apps)](/v2.0/docs/apps-create-an-app) - [Update one app's details (PUT /apps/:id)](/v2.0/docs/appsid-update-an-app) [block:callout] { "type": "warning", "title": "User Key Required", "body": "Each of these calls requires your User Key." } [/block] [block:html] { "html": "<a name=\"users\"/>" } [/block] [block:api-header] { "type": "basic", "title": "Players" } [/block] Each OneSignal app can have many users, each of which corresponds to a unique user that has installed and run your application. [block:callout] { "type": "info", "title": "A user has the following attributes:", "body": "- app_id\n- id\n- device_type\n- identifier\n- language\n- session_count\n- last_active\n- device_os\n- timezone\n- ad_id\n- badge_count\n- app_version\n- created_at\n- amount_spent\n- tags\n- duration\n- invalid_identifier\n- badge_count\n\nThe `id` and `created_at` values are assigned by the OneSignal API when a user is created. \n\n`app_id` is available on the OneSignal website after creating a new app. \n\n`invalid_identifier` is set to true in the following cases:\n1. The user does not have an identifier, for instance if they declined the push notification permission.\n2. If the user re-installed your app and a new user record was created for them\n3. If they failed to receive a push notification because they uninstalled the app." } [/block] #Available /players methods# - [Fetch one user's details (GET /players/:id)](/v2.0/docs/playersid) - [Add a new user to an app (POST /players)](/v2.0/docs/players-add-a-device) - [Update one user's details (PUT /players/:id)](/v2.0/docs/playersid-1) - [Indicate a user started using your app (POST /players/:id/on_session)](/v2.0/docs/playersidon_session) - [Indicate a user made a purchase in your app (POST /players/:id/on_purchase)](doc:on_purchase) - [Update the total session time of a user (POST /players/:id/on_focus)](/v2.0/docs/playersidon_focus) [block:html] { "html": "<a name=\"notifications\"/>" } [/block] [block:api-header] { "type": "basic", "title": "Notifications" } [/block] Notifications can be targeted to users by: - a set of user IDs, targeting one or many - a set of tags, matching all users in a single app that match each tag - a list of segments, sending to all users included in the segments #Available /notifications methods# - [Fetch all sent notifications' details GET /notifications](/v2.0/docs/notifications-view-notifications) - [Fetch a single sent notification's details (GET /notifications/:id)](/v2.0/docs/notificationsid-view-notification) - [Send a notification (POST /notifications)](/v2.0/docs/notifications-create-notification) - [Track that a notification was opened](/v2.0/docs/notificationsid-track-open)