Push Installation API

The Push Installation API provides endpoints to register and unregister the tokens that enable mobile devices to receive push notifications from an application.

A push notification is a text message that appears on a user's mobile device to alert them about something important or to ask them to perform an action.

When creating custom mobile applications, in order to set up Push notifications, you must register the device with the manufacturer’s service. The service must know the address of a user's device so it can properly send notifications to that device using push tokens. The device also needs to be able to receive the notifications and act on them. For instructions on how to register a device and get a push token, refer to the device’s operating systems developer documentation. For example, for Apple devices, refer to https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns.

Push Installation - POST /now/push/{pushApplicationName}/installation

Adds or updates tokens that enable devices to receive push notifications from the specified application.

URL format

Versioned URL: /api/now/{api_version}/push/{pushApplicationName}/installation

Default URL: /api/now/push/{pushApplicationName}/installation

Supported request parameters

Table 1. Path parameters

Parameter	Description
api_version	Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String
pushApplicationName	Name of the application for which to register the push notifications. This parameter must be the same as the value in the Name column for the associated application in the Push Application [sys_push_application] table. Data type: String

Table 2. Query parameters

Name	Description
None

Table 3. Request body parameters (XML or JSON)

Element	Description
platform	Platform on which to register the push notification. This parameter must be the Name value from the Push Platform [sys_push_platform] table. Data type: String
token	Token supplied by the device manufacturer, such as Apple, when the mobile application registers to receive push notifications. The endpoint writes the token value to the Push Notification Installation [sys_push_notif_app_install] table. Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

Table 5. Response headers

Header	Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name	Description
None

Sample cURL request

curl -X POST \
  https://instance.servicenow.com/api/now/push/ServiceNowPushApp/installation \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{"platform":"Apple","token":"544836d77ac2e551bbf78204630509a7d494fc87f52e85da52e5b5d42910e2cf"}' \

None

Push Installation - POST /now/push/{pushApplicationName}/removeInstallation

Deactivates the tokens that enable mobile devices to receive push notifications from the specified application.

URL format

Versioned URL: /api/now/{api_version}/push/{pushApplicationName}/removeInstallation

Default URL: /api/now/push/{pushApplicationName}/removeInstallation

Supported request parameters

Table 7. Path parameters

Name	Description
api_version	Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest. Data type: String
pushApplicationName	Name of the application for which to unregister the push notifications. This parameter must be the same as the value in the Name column for the associated application in the Push Application [sys_push_application] table. Data type: String

Table 8. Query parameters

Name	Description
None

Table 9. Request body parameters (XML or JSON)

Element	Description
platform	Platform on which to register the push notification. This parameter must be the Name value from the Push Platform [sys_push_platform] table. Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers

Header	Description
Content-Type	Data format of the request body. Only supports application/json.

Table 11. Response headers

Header	Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 12. Status codes

Status code	Description
200	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected.
401	Unauthorized. The user credentials are incorrect or have not been passed.
500	Internal Server Error. A logic error on the server-side code occurred.

Response body parameters (JSON or XML)

Name	Description
None

Sample cURL request

curl -X POST \
  https://instance.servicenow.com/api/now/push/ServiceNowPushApp/removeInstallation \
--header "Content-Type: application/json" \
--user "username":"password" \
--data '{"platform":"Apple"}' \

None