Device API

This is the API used by our Android and iOS SDKs.

We want everyone to use our official Android and iOS SDKs. If your use case requires this documentation, please contact us betterbeams@pusher.com

Register new APNs device

1
POST https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/apns

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Request body

A JSON object with the following keys:

  • token (string|required): The APNs gateway token.
  • bundleIdentifier (string|required): The application bundle identifier.
  • metadata (apnsMetadata|optional): The metadata for this device, which contains the following fields:
    • sdkVersion: the version of the SDK.
    • iosVersion: the iOS version the device has.
    • macosVersion: the macOS version the device has.

Response Body

A JSON object with the following fields:

  • id (string): Unique string used to identify this device.
  • initialInterestSet (set of string): Set of interests the device is initially subscribed to which can happen when they are migrated from other competitor products.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Bad request400Failed to read body as a JSON object.
Bad request400Missing APNs token.
Bad request400Missing App Bundle Identifier.
Unauthorized401Incorrect instance credentials.
Unauthorized401Incorrect APNs token supplied.
Instance not found404Could not find the instance.
Something went wrong500Internal server error.

Register new FCM device

1
POST https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Request body

A JSON object with the following keys:

  • token (string|required): The FCM gateway token.
  • metadata (fcmMetadata|optional): The metadata for this device, which contains the following fields:
    • sdkVersion: the version of the SDK.
    • androidVersion: the iOS version the device has.

Response Body

A JSON object with the following fields:

  • id (string): Unique string used to identify this device.
  • initialInterestSet (set of string): Set of interests the device is initially subscribed to which can happen when they are migrated from other competitor products.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad request400Failed to read body as a JSON object.
Bad request400Missing FCM token.
Unauthorized401Incorrect instance credentials.
Unauthorized401Incorrect FCM token supplied.
Instance not found404Could not find the instance.
Something went wrong500Internal server error.

Get APNs device

1
GET https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/apns/<DEVICE_ID>

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Response Body

A JSON object representing the Device with the following fields:

  • id (string): Unique string used to identify this device.
  • userId (string): The User Id this device belongs to.
  • metadata (apnsMetadata): The metadata for this device, which contains the following fields:
    • sdkVersion: the version of the SDK.
    • iosVersion: the iOS version the device has.
    • macosVersion: the macOS version the device has.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Incomplete Request400device-id param is missing from path.
Instance not found404Could not find the instance.
Something went wrong500Internal server error.

Get FCM device

1
GET https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm/<DEVICE_ID>

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Response Body

A JSON object representing the Device with the following fields:

  • id (string): Unique string used to identify this device.
  • userId (string): The User Id this device belongs to.
  • metadata (fcmMetadata): The metadata for this device, which contains the following fields:
    • sdkVersion: the version of the SDK.
    • androidVersion: the iOS version the device has.

Delete APNs device

1
DELETE https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/apns/<DEVICE_ID>

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Something went wrong500Internal server error.

Delete FCM device

1
DELETE https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm/<DEVICE_ID>

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Something went wrong500Internal server error.

Update APNs Device Metadata

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/apns/<DEVICE_ID>/metadata

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Request body

A JSON object with the following keys:

  • sdkVersion: the version of the SDK.
  • iosVersion: the iOS version the device has.
  • macosVersion: the macOS version the device has.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad request400Failed to read body as a JSON object.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Update FCM Device Metadata

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm/<DEVICE_ID>/metadata

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Request body

A JSON object with the following keys:

  • sdkVersion: the version of the SDK.
  • androidVersion: the iOS version the device

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad request400Failed to read body as a JSON object.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Update FCM Device Token

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm/<DEVICE_ID>/token

Request headers

The following headers are necessary:

  • Content-Type: with the value always set to application/json.

Request body

A JSON object with the following keys:

  • token: the updated FCM token for this device.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad request400Failed to read body as a JSON object.
Bad request400Missing token field with the FCM Registration Id.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Set APNs Device User Id

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/apns/<DEVICE_ID>/user

Request headers

The following headers are necessary:

  • Authorization: with the value in the following format: Bearer <BEAMS_USER_JWT_TOKEN>.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad Request400Missing expiration (exp) field in JWT
Bad Request400Missing subject (sub) field in JWT
Bad Request400JWT subject (sub) must be between 1-164 characters long
Bad Request400Missing issuer (iss) field in JWT
Bad Request400A User Id is already associated with this device.
Bad Request400Invalid device id.
Unauthorized401Authorization header token is missing.
Unauthorized401Authorization header token is malformed.
Forbidden403Invalid JWT issuer.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Set FCM Device User Id

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/fcm/<DEVICE_ID>/user

Request headers

The following headers are necessary:

  • Authorization: with the value in the following format: Bearer <BEAMS_USER_JWT_TOKEN>.

Error Responses

TitleStatus CodeDescription
Invalid content type400Only application/json is supported.
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad Request400Missing expiration (exp) field in JWT
Bad Request400Missing subject (sub) field in JWT
Bad Request400JWT subject (sub) must be between 1-164 characters long
Bad Request400Missing issuer (iss) field in JWT
Bad Request400A User Id is already associated with this device.
Bad Request400Invalid device id.
Unauthorized401Authorization header token is missing.
Unauthorized401Authorization header token is malformed.
Forbidden403Invalid JWT issuer.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Get Device Interests

1
GET https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/<DEVICE_PLATFORM>/<DEVICE_ID>/interests

Request Query Parameters

The request can have the following query parameters:

  • limit: the maximum number of interests to be returned from a single request. By default, it's the maximum value of 100.
  • cursor: the cursor returned from a previous request to continue fetching the list of interests.

Response Body

A JSON object with the following fields:

  • interests (array of string): The array of interests the device is currently subscribed to. This array might be incomplete and more requests might be needed to get the complete list.
  • responseMetadata (responseMetadata): which contains the following fields:
    • nextCursor: if present, use this to perform the next request

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad Request400limit given is not valid.
Bad Request400cursor given is not valid.
Instance not found404Could not find the instance.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Set Device Interests

1
PUT https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/<DEVICE_PLATFORM>/<DEVICE_ID>/interests

Request Body

A JSON object with the following keys:

  • interests (array of string): the set of interests this device should be subscribed to. This replaces any other existing interests. Limited to 5000 interests per device.

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad request400Failed to read body as a JSON object.
Invalid interest name400interest-name given is not valid.
Interest set too large400Too many interests are being set for this device. Only 5000 interests per device are allowed.
Instance not found404Could not find the instance.
Device not found404Could not find the device.
Something went wrong500Internal server error.

Add Device Interest

1
POST https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/<DEVICE_PLATFORM>/<DEVICE_ID>/interests/<INTEREST_NAME>

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Bad Request400device-id given is not valid.
Invalid interest name400interest-name given is not valid.
Incomplete Request400interest-name param is missing from path.
Instance not found404Could not find the instance.
Something went wrong500Internal server error.

Remove Device Interest

1
DELETE https://<YOUR_INSTANCE_ID>.pushnotifications.pusher.com/device_api/v1/instances/<YOUR_INSTANCE_ID>/devices/<DEVICE_PLATFORM>/<DEVICE_ID>/interests/<INTEREST_NAME>

Error Responses

TitleStatus CodeDescription
Incomplete Request400instance-id param is missing from path.
Bad Request400instance-id given is not valid.
Incomplete Request400device-id param is missing from path.
Incomplete Request400device-id given is not valid.
Incomplete Request400interest-name param is missing from path.
Instance not found404Could not find the instance.
Something went wrong500Internal server error.