Push Applications (GET)

Description

Retrieves all the applications.

Method

Path

/apps/

Example:

https://example.com:443/imfpush/v1/apps/?expand=true&filter=platform==A&offset=0&size=10

Query Parameters

expand

Retrieves detailed information about applications.

filter

Search criteria filter. Refer to the filter section for detailed syntax.

offset

Pagination offset that is normally used along with the size.

size

Pagination size that is normally used along with the offset to retrieve a subset.

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.read" and "push.application.*" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "applications" : [
    {
      "applicationId" : "testApp",
    },
    ...
  ],
  "pageInfo" : {
    "count" : "2",
    "next" : "",
    "previous" : "",
    "totalCount" : "10",
  },
}

Response Properties

applications

The array of applications.

pageInfo

The pagination information

The applications has the following properties:

applicationId

The applicationId.

The pageInfo has the following properties:

count

The number of applications that are retrieved

next

A hyperlink to the next page

previous

A hyperlink to the previous page

totalCount

The total number of applications present for the given search criteria

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Application (POST)

Description

Creates a new server application for the push service.

The applicationId is an unique application ID for this application. Application is a parent resource for devices, subscriptions, tags and messages. The application must be created before accessing any of the child resources. If the application is deleted, all the children are deleted. The application holds the configurations, such as the Apple Push Notification Service (APNS) and Google Cloud Message (GCM) configuration, which is required by the push service to send messages. The API first creates the application and then sets the APNS and GCM settings.

Method

Path

/apps/

Example:

https://example.com:443/imfpush/v1/apps/

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Produces

Payload input

JSON Example:

{
  "applicationId" : "testApp",
  "enabled" : "true",
}

Payload Properties

applicationId

The application Id.

enabled

Optinal. The status of the applicaton. Default is true

Response

JSON Example:

{
  "applicationId" : "testApp",
  "enabled" : "true",
}

Response Properties

applicationId

The application Id.

enabled

The status of the application.

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Application (GET)

Description

Retrieves the application, which is referenced by the applicationId parameter.

Method

Path

/apps/<applicationId>

Example:

https://example.com:443/imfpush/v1/apps/myapp

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "applicationId" : "testApp",
  "enabled" : "true",
}

Response Properties

applicationId

The application Id.

enabled

The status of the application.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push Application (DELETE)

Description

Deletes an application, which is referenced by the applicationId parameter.

After the application is deleted the tags, devices, subscriptions and message resources associated with the application are also deleted.

Method

Path

/apps/<applicationId>

Example:

https://example.com:443/imfpush/v1/apps/myapp

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push Application Settings (GET)

Description

Retrieves appplication settings

This can be used to find the mode of the application.

Method

Path

/apps/<applicationId>/settings

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "settings.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "apnsConf" : "https://example.com:443/imfpush/v1/apps/testApp/settings/apnsConf",
  "applicationId" : "testApp",
  "gcmConf" : "https://example.com:443/imfpush/v1/apps/testApp/settings/gcmConf",
  "mode" : "PRODUCTION",
}

Response Properties

apnsConf

Reference link to APNS settings.

applicationId

The application Id.

gcmConf

Reference link to GCM settings.

mode

The operation mode

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push APNS Certificate Settings (GET)

Description

Retrieves APNS certificate for the application

Method

Path

/apps/<applicationId>/settings/apnsCert

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/apnsCert

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apnsCert.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push APNS Settings (GET)

Description

Retrieves APNS settings for the application

Method

Path

/apps/<applicationId>/settings/apnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/apnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apnsConf.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "certificate" : "apns-certificate.p12",
  "isSandBox" : "true",
  "validUntil" : "2016-09-06T05:51:11.000Z",
}

Response Properties

certificate

The name of the certificate.

isSandBox

The certificate type.

validUntil

The certificate validity date.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push APNS settings (PUT)

Description

Uploads an APNS certificate to the application referenced by the applicationId

Form-data Parameters

certificate

(file) The APNS certificate.

password

(String) Password for the APNS certificate

isSandBox

(boolean) The APNS certificate type.

Method

Path

/apps/<applicationId>/settings/apnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/apnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apnsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the content type. For example: multipart/form-data. This parameter has to be mandatorily set.

Consumes

Produces

Response

JSON Example:

{
  "certificate" : "apns-certificate.p12",
  "isSandBox" : "true",
  "validUntil" : "2016-09-06T05:51:11.000Z",
}

Response Properties

certificate

The name of the APNS certificate.

isSandBox

The APNS certificate type.

validUntil

The APNS certificate validity date.

Errors

400

Bad Request - The request was not understood by the push server. An invalid data in the input.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push APNS settings (DELETE)

Description

Deletes APNS settings for the application

Method

Path

/apps/<applicationId>/settings/apnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/apnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apnsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push GCM Settings (GET)

Description

Retrieves GCM settings for the application

Method

Path

/apps/<applicationId>/settings/gcmConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/gcmConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "gcmConf.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "apiKey" : "AxBNGYUwehjokn",
  "senderId" : "123456789",
}

Response Properties

apiKey

The GCM API Key.

senderId

The GCM SenderId.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push GCM Settings (PUT)

Description

Updates GCM settings referenced by the applicationId

Method

Path

/apps/<applicationId>/settings/gcmConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/gcmConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apnsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "apiKey" : "AxBNGYUwehjokn",
  "senderId" : "123456789",
}

Payload Properties

apiKey

The GCM API Key.

senderId

The GCM SenderId.

Response

JSON Example:

{
  "apiKey" : "AxBNGYUwehjokn",
  "senderId" : "123456789",
}

Response Properties

apiKey

The GCM API Key.

senderId

The GCM SenderId.

Errors

400

Bad Request - The request was not understood by the push server. An invalid data in the input.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push GCM Settings (DELETE)

Description

Deletes GCM settings for the application

Method

Path

/apps/<applicationId>/settings/gcmConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/gcmConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "gcmConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push GCM Public Settings (GET)

Description

Retrieves GCM settings for the application

Method

Path

/apps/<applicationId>/settings/gcmConfPublic

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/gcmConfPublic

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "gcmConfPublic.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "senderId" : "123456789",
}

Response Properties

senderId

The GCM SenderId.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push SMS Settings (GET)

Description

Retrieves SMS settings for the application

Method

Path

/apps/<applicationId>/settings/smsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/smsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "smsConf.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "host" : "xyz.com",
  "name" : "TestGateway",
  "parameters" : [
    {
      "encode" : "true",
      "name" : "TestKey",
      "value" : "TestValue",
    },
    ...
  ],
  "port" : "80",
  "programName" : "/sendsms",
}

Response Properties

host

The host name of the SMS Gateway

name

The name of the SMS Gateway

parameters

The array of parameters

port

The port number of the SMS Gateway

programName

The path of the SMS Gateway

The parametersArray has the following properties:

encode

The parameter should be encoded or not

name

The name of the parameter

value

The value of the parameter

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push SMS Settings (PUT)

Description

Updates SMS settings referenced by the applicationId

Method

Path

/apps/<applicationId>/settings/smsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/smsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "smsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "host" : "xyz.com",
  "name" : "TestGateway",
  "parameters" : [
    {
      "encode" : "true",
      "name" : "TestKey",
      "value" : "TestValue",
    },
    ...
  ],
  "port" : "80",
  "programName" : "/sendsms",
}

Payload Properties

host

The host name of the SMS Gateway

name

The name of the SMS Gateway

parameters

The array of parameters

port

The port number of the SMS Gateway

programName

The path of the SMS Gateway

The parametersArray has the following properties:

encode

The parameter should be encoded or not

name

The name of the parameter

value

The value of the parameter

Response

JSON Example:

{
  "host" : "xyz.com",
  "name" : "TestGateway",
  "parameters" : [
    {
      "encode" : "true",
      "name" : "TestKey",
      "value" : "TestValue",
    },
    ...
  ],
  "port" : "80",
  "programName" : "/sendsms",
}

Response Properties

host

The host name of the SMS Gateway

name

The name of the SMS Gateway

parameters

The array of parameters

port

The port number of the SMS Gateway

programName

The path of the SMS Gateway

The parametersArray has the following properties:

encode

The parameter should be encoded or not

name

The name of the parameter

value

The value of the parameter

Errors

400

Bad Request - The request was not understood by the push server. An invalid data in the input.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push SMS settings (DELETE)

Description

Deletes SMS settings for the application

Method

Path

/apps/<applicationId>/settings/smsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/smsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "smsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push WNS Settings (GET)

Description

Retrieves WNS settings for the application

Method

Path

/apps/<applicationId>/settings/wnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/wnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "wnsConf.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "clientSecret" : "Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7",
  "packageSID" : "ms-app://S-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962",
}

Response Properties

clientSecret

The Client secret.

packageSID

Package SID

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push WNS Settings (PUT)

Description

Updates WNS settings referenced by the applicationId

Method

Path

/apps/<applicationId>/settings/wnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/wnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "wnsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "clientSecret" : "Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7",
  "packageSID" : "ms-app://S-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962",
}

Payload Properties

clientSecret

The Client secret.

packageSID

Package SID

Response

JSON Example:

{
  "clientSecret" : "Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7",
  "packageSID" : "ms-app://S-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962",
}

Response Properties

clientSecret

The Client secret.

packageSID

Package SID

Errors

400

Bad Request - The request was not understood by the push server. An invalid data in the input.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push WNS settings (DELETE)

Description

Deletes WNS settings for the application

Method

Path

/apps/<applicationId>/settings/wnsConf

Example:

https://example.com:443/imfpush/v1/apps/myapp/settings/wnsConf

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "wnsConf.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push Application (GET)

Description

Retrieves the application, which is referenced by the applicationId parameter.

Method

Path

/apps/<applicationId>/status

Example:

https://example.com:443/imfpush/v1/apps/myapp/status

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "enabled" : "true",
}

Response Properties

enabled

The status of the application.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push Application (PUT)

Description

Updates an existing application status. The API can be used to enable or disable an application.

Method

Path

/apps/<applicationId>/status

Example:

https://example.com:443/imfpush/v1/apps/myapp/status

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "apps.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "enabled" : "true",
}

Payload Properties

enabled

The status of the application

Response

JSON Example:

{
  "applicationId" : "testApp",
  "enabled" : "true",
}

Response Properties

applicationId

The application Id.

enabled

The status of the application.

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The applicationId does not exist.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Registrations (GET)

Description

Retrieves all or a subset of existing device registration(s) of push.

Device registrations for the push service are retrieved for the specified criteria

Method

Path

/apps/<applicationId>/devices

Example:

https://example.com:443/imfpush/v1/apps/myapp/devices?expand=true&filter=platform==A&offset=0&size=10&userId=admin

Path Parameters

applicationId

The name or identifier of the application

Query Parameters

expand

Retrieves additional metadata for every device registration that is returned in the response.

filter

Search criteria filter. Refer to the filter section for detailed syntax.

offset

Pagination offset that is normally used along with the size.

size

Pagination size that is normally used along with the offset to retrieve a subset.

userId

Retrieves device registrations only for the specified user.

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages.. Default:en-US

Authorization

The token with the scope "devices.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "devices" : [
    {
      "deviceId" : "12345-6789",
      "href" : "http://localhost:9080/imfpush/v1/apps/appName/devices/12345-6789",
      "phoneNumber" : "123456789",
      "platform" : "A",
      "token" : "xyz",
      "userId" : "admin",
    },
    ...
  ],
  "pageInfo" : {
    "count" : "2",
    "next" : "",
    "previous" : "",
    "totalCount" : "10",
  },
}

Response Properties

devices

The array of device registrations with Push.

pageInfo

The pagination information

The devices has the following properties:

deviceId

The unique id of the device.

href

The REST URL to get device details

phoneNumber

Phone number to be used for SMS based notification.

platform

The device platform.

token

The unique push token of the device.

userId

The userId of the device.

The pageInfo has the following properties:

count

The number of device registration that are retrieved

next

A hyperlink to the next page

previous

A hyperlink to the previous page

totalCount

The total number of device registration present for the given search criteria

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Registration (POST)

Description

Creates a device registration with the push service.

The device registrations happens from the device. The deviceId is the unique ID for the device for the application.

Method

Path

/apps/<applicationId>/devices

Example:

https://example.com:443/imfpush/v1/apps/myapp/devices

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "devices.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "deviceId" : "12345-6789",
  "phoneNumber" : "123456789",
  "platform" : "A",
  "token" : "xyz",
}

Payload Properties

deviceId

Unique id of the device.

phoneNumber

Phone number to be used for SMS based notification.

platform

The device platform. 'A' refers to Apple(iOS) devices, 'G' refers to Google(Android) and 'W' refers to Microsoft(Windows) devices

token

Device token obtained via the service provider

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-05-20T11:42:11Z",
  "deviceId" : "12345-6789",
  "href" : "http://localhost:9080/imfpush/v1/apps/appName/devices/12345-6789",
  "lastUpdatedTime" : "2015-05-20T11:42:11Z",
  "phoneNumber" : "123456789",
  "platform" : "A",
  "token" : "xyz",
  "userAgent" : "TestUserAgent",
  "userId" : "admin",
}

Response Properties

createdMode

The mode of creation.

createdTime

The date and time when the push device registration was created on the server in ISO 8601 format.

deviceId

Unique id of the device.

href

The REST URL to get device details

lastUpdatedTime

The date and time when the push device registration was last updated on the server in ISO 8601 format.

phoneNumber

Phone number to be used for SMS based notification.

platform

The device platform. 'A' refers to Apple(iOS) devices, 'G' refers to Google(Android) and 'W' refers to Microsoft(Windows) devices

token

Device token obtained via the service provider

userAgent

The user agent for the the device registration

userId

The user identifier for the the device registration

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Registration (GET)

Description

Retrieves an existing device registration of push

Device registrations for a push service that are retrieved for a specific deviceId.

Method

Path

/apps/<applicationId>/devices/<deviceId>

Example:

https://example.com:443/imfpush/v1/apps/myapp/devices/12345-6789

Path Parameters

deviceId

The device identifier

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "devices.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-05-20T11:42:11Z",
  "deviceId" : "12345-6789",
  "href" : "http://localhost:9080/imfpush/v1/apps/appName/devices/12345-6789",
  "lastUpdatedTime" : "2015-05-20T11:42:11Z",
  "phoneNumber" : "123456789",
  "platform" : "A",
  "token" : "12345-6789",
  "userId" : "admin",
}

Response Properties

createdMode

The mode of creation.

createdTime

The date and time when the push device registration was created on the server in ISO 8601 format.

deviceId

The unique id of the device.

href

The REST Url to get device details

lastUpdatedTime

The date and time when the push device registration was last updated on the server in ISO 8601 format.

phoneNumber

Phone number to be used for SMS based notification.

platform

The device platform.

token

The unique push token of the device.

userId

The userId of the device.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A device registration with the specified deviceId is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Registration (PUT)

Description

Updates an existing device registration for the push service.

The push device registration is updated with the new user ID or the token specified. In most use cases this call is used to update the userId only.

Method

Path

/apps/<applicationId>/devices/<deviceId>

Example:

https://example.com:443/imfpush/v1/apps/myapp/devices/12345-6789

Path Parameters

deviceId

The device identifier

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "devices.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "deviceId" : "12345-6789",
  "phoneNumber" : "123456789",
  "token" : "xyz",
  "userId" : "admin",
}

Payload Properties

deviceId

The unique id of the device.

phoneNumber

Phone number to be used for SMS based notification.

token

The token of the device. Its optional to set this.

userId

The userId of the device. Its optional to set this.

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-05-20T11:42:11Z",
  "deviceId" : "12345-6789",
  "href" : "http://localhost:9080/imfpush/v1/apps/appName/devices/12345-6789",
  "lastUpdatedTime" : "2015-05-20T11:42:11Z",
  "phoneNumber" : "123456789",
  "platform" : "A",
  "token" : "xyz",
  "userId" : "admin",
}

Response Properties

createdMode

The mode of creation.

createdTime

The date and time when the push device registration was created on the server in ISO 8601 format.

deviceId

The unique id of the device.

href

The REST Url to get device details

lastUpdatedTime

The date and time when the push device registration was last updated on the server in ISO 8601 format.

phoneNumber

Phone number to be used for SMS based notification.

platform

The device platform.

token

The unique push token of the device.

userId

The userId of the device.

Errors

400

A device registration has userId longer than 254 characters.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A device registration with the specified deviceId is not found.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Registration (DELETE)

Description

Deletes(unregisters) an existing device registration from the push service

The device registrations of push service is deleted for the given deviceId. The call returns HTTP response code 204 with no content on successful deletion of the device registration.

Method

Path

/apps/<applicationId>/devices/<deviceId>

Example:

https://example.com:443/imfpush/v1/apps/myapp/devices/12345-6789

Path Parameters

deviceId

The device identifier

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages.. Default:en-US

Authorization

The token with the scope "devices.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A device registration with the specified deviceId is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Message (POST)

Description

Send message with different options.

Sends a push notifications to the specified targets and returns HTTP return code 202 when the request to send the message is accepted.

Method

Path

/apps/<applicationId>/messages

Example:

https://example.com:443/imfpush/v1/apps/myapp/messages

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "messages.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "message" : {
    "alert" : "Test message",
  },
  "notificationType" : 1,
  "settings" : {
    "apns" : {
      "attachmentUrl": "http://test.com/test.png",
      "subtitle": "Sub Title",
      "title": "Title",      
      "badge" : 1,
      "category" : 1,
      "iosActionKey" : "Ok",
      "payload" : {"custom":"data"},
      "sound" : "song.mp3",
      "type" : "SILENT",
    },
    "gcm" : {
      "bridge" : false,
      "category" : "email",
      "collapseKey" : "testkey",
      "delayWhileIdle" : false,
      "payload" : {"custom":"data"},
      "priority" : "low",
      "redact" : "Test Redact Message",
      "sound" : "song.mp3",
      "sync" : false,
      "timeToLive" : 10,
      "visibility" : "public",
    },
    "wns" : {
      "badge" : {"value":"10"},
      "cachePolicy" : false,
      "expirationTime" : 20,
      "raw" : {"payload":{"custom":"data"}},
      "tile" : {"visual":{"binding":[{"template":"TileSquareText04", "text": [{"content":"Text1"}]}, {"template":"TileWideText04","text": [{"content":"Text1"}]}]}},
      "toast" : {"launch":{"custom":"data"}, "visual":{"binding":{"template":"ToastText04","text":[{"content":"Text1"},{"content":"Text2"},{"content":"Text3"}]}},
    },
  },
  "target" : {
    "deviceIds" : [ "MyDeviceId1", ... ],
    "platforms" : [ "A,G", ... ],
    "tagNames" : [ "Gold", ... ],
    "userIds" : [ "MyUserId", ... ],
  },
}

Payload Properties

message

The alert message to be sent

notificationType

Integer value to indicate the channel (Push/SMS) used to send message. Allowed values are 1 (only Push), 2 (only SMS) and 3 (Push and SMS)

settings

The settings are the different attributes of the notification.

target

Set of targets can be user Ids, devices, platforms, or tags. Only one of the targets can be set.

The message has the following properties:

alert

A string to be displayed in the alert.

The settings has the following properties:

apns

Attributes for sending message to an iOS device.

gcm

Attributes for sending message to an Android device.

wns

Attributes for sending message to a windows device.

The apns has the following properties:

attachmentUrl

The link to the iOS notifications media (video, audio, GIF, images - Supported only on iOS 10 and above).

subtitle

The subtitle of the Rich Notifications.(Supported only on iOS 10 and above).

title

The title of Rich Push notifications (Supported only on iOS 10 and above).

badge

An integer value to be displayed in a badge on the application icon.

category

Name of the category for iOS8 interactive push notifications.

iosActionKey

The label of the dialog box button that allows the user to open the app upon receiving the notification.

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

sound

The name of a file to play when the notification arrives.

type

Specify the type of APNS notification. It should be either DEFAULT, MIXED or SILENT

The gcm has the following properties:

bridge

A Boolean value that indicates whether the notification should be bridged or not to other devices connected to this handheld device. Only applies to Android 5.0 or higher.

category

A string value that indicates the category to which this notification belongs. Allowed values are 'call', 'alarm', 'email', 'err', 'event', 'msg', 'progress', 'promo', 'recommendation', 'service', 'social', 'status', and 'transport'. Only applies to Android 5.0 or higher.

collapseKey

A string value that indicates that the message can be replaced. When multiple messages are queued up in GCM Servers with the same key, only the last one is delivered.

delayWhileIdle

A Boolean value that indicates that the message must not be sent if the device is idle. The server waits for the device to become active before the message is sent. Default value is false

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

priority

A string value that indicates the priority of this notification. Allowed values are 'max', 'high', 'default', 'low' and 'min'. High/Max priority notifications along with 'sound' field may be used for Heads up notification in Android 5.0 or higher.

redact

A string to be displayed in the alert as a redacted version of the original content when the visibility level is 'private'. Only applies to Android 5.0 or higher.

sound

The name of a sound file on the device to play when the notification arrives to the device.

sync

A Boolean value that indicates whether the notification should be sync'd between devices of the same user, that is, if a notification is handled on a device it gets dismissed on the other devices of the same user

timeToLive

The duration (in seconds) that the message is kept on GCM storage if the device is offline. Default value is 4 weeks, and must be set as a JSON number.

visibility

A string value that indicates the visibility level of notification content on the secured lock screen in Android L devices. Allowed values are 'public, 'private' and 'secret'. Only applies to Android 5.0 or higher.

The wns has the following properties:

badge

cachePolicy

A boolean value that indicates if the notification should be cached or not.

expirationTime

Optional. Expriry time of the notification.

raw

tile

toast

The badge has the following properties:

value

Optional. A numeric or string value that indicates a prdefined glyph to be displayed.

version

Optional. Version of the payload.

The raw has the following properties:

payload

Optional. A JSON block that is transferred to the application only if the application is already open.

The tile has the following properties:

tag

Optional. A string value that is set as label for the notification. Used in notification cycling.

visual

The visual has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

binding

For tile notifications, its a JSON array containing JSON blocks of binding attributes. For toast notification, its a JSON block of binding attributes.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

lang

Optional. Locale of the payload.

version

Optional. Version of the payload.

The binding has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

fallback

Optional. Template to be used as a fallback.

image

Optional. A JSON array containing JSON blocks of following image attributes.

lang

Optional. Locale of the payload.

template

Mandatory. Template type of the notification.

text

Optional. A JSON array containing JSON blocks of following text attributes.

The image has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

alt

Optional. Image description.

src

Mandatory. Image URI.

The text has the following properties:

content

Mandatory. A string value that is displayed in the toast.

lang

Optional. Locale of the payload.

The toast has the following properties:

audio

duration

Optional. Notification will be displayed for the specified duration. Should be 'short' or 'long'.

launch

Optional. A string value that is passed to the application when it is launched by tapping or clicking the toast notification.

visual

The audio has the following properties:

loop

Optional. A boolean value to indicate if the sound should be repeated or not.

silent

Optional. A boolean value to indicate if the sound should be played or not.

src

Optional. A string value that specifies the notification sound type or path to local audio file.

The target has the following properties:

deviceIds

An array of the devices represented by the device identifiers. Devices with these ids receive the notification. This is a unicast notification

platforms

An array of device platforms. Devices running on these platforms receive the notification. Supported values are A (Apple/iOS), G (Google/Android) and W (Microsoft/Windows).

tagNames

An array of tags specified as tagNames. Devices that are subscribed to these tags receive the notification. Use this type of target for tag based notifications

userIds

An array of users represented by their userIds to send the notification. This is a unicast notification.

Response

JSON Example:

{
  "message" : {
    "message" : {
      "alert" : "TestMessage",
    },
  },
  "messageId" : "1234",
}

Response Properties

message

The array of messages to be sent

messageId

The unique identifier of the message.

The messages has the following properties:

message

The message to be sent

The message has the following properties:

alert

The message text.

Errors

400

Invalid JSON.

403

The user is not authorized to call this service.

404

The corresponding runtime is not found or not running.

500

An internal error occurred.

Bulk Push Messages (POST)

Description

Send bulk messages with different options that you can specify.

Method

Path

/apps/<applicationId>/messages/bulk

Example:

https://example.com:443/imfpush/v1/apps/myapp/messages/bulk

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Authorization

The token with the scope "messages.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "//ArrayOfMessageBody" : [
    {
      "messages" : {
        "alert" : "Test message",
      },
      "notificationType" : 1,
      "settings" : {
        "apns" : {
          "badge" : 1,
          "iosActionKey" : "Ok",
          "payload" : {"custom":"data"},
          "sound" : "song.mp3",
          "type" : "SILENT",
        },
        "gcm" : {
          "delayWhileIdle" : false,
          "payload" : {"custom":"data"},
          "sound" : "song.mp3",
          "timeToLive" : 10,
        },
        "wns" : {
          "badge" : {"value":"10"},
          "cachePolicy" : false,
          "expirationTime" : 20,
          "raw" : {"payload":{"custom":"data"}},
          "tile" : {"visual":{"binding":[{"template":"TileSquareText04", "text": [{"content":"Text1"}]}, {"template":"TileWideText04","text": [{"content":"Text1"}]}]}},
          "toast" : {"launch":{"custom":"data"}, "visual":{"binding":{"template":"ToastText04","text":[{"content":"Text1"},{"content":"Text2"},{"content":"Text3"}]}},
        },
      },
      "target" : {
        "deviceIds" : [ "MyDeviceId1", ... ],
        "platforms" : [ "A,G", ... ],
        "tagNames" : [ "Gold", ... ],
        "userIds" : [ "MyUserId", ... ],
      },
    },
    ...
  ],
}

Payload Properties

//ArrayOfMessageBody

The array of message

The bulk-messages has the following properties:

messages

The array of message

notificationType

Integer value to indicate the channel (Push/SMS) used to send message. Allowed values are 1 (only Push), 2 (only SMS) and 3 (Push and SMS)

settings

The settings are the different attributes of the notification.

target

Set of targets can be userIds, devices, platforms, or tags.

The message has the following properties:

alert

A string to be displayed in the alert.

The settings has the following properties:

apns

Attributes for sending message to an iOS device.

gcm

Attributes for sending message to an Android device.

wns

Attributes for sending message to a windows device.

The apns has the following properties:

badge

An integer value to be displayed in a badge on the application icon.

iosActionKey

The label of the dialog box button that allows the user to open the app upon receiving the notification.

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

sound

The name of a file to play when the notification arrives.

type

Specify the type of APNS notification. It should be either DEFAULT, MIXED or SILENT

The gcm has the following properties:

delayWhileIdle

A Boolean value that indicates that the message must not be sent if the device is idle. The server waits for the device to become active before the message is sent.

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

sound

The name of a sound file on the device to play when the notification arrives to the device.

timeToLive

The duration (in seconds) that the message is kept on GCM storage if the device is offline. Default value is 4 weeks, and must be set as a JSON number.

The wns has the following properties:

badge

cachePolicy

A boolean value that indicates if the notification should be cached or not.

expirationTime

Optional. Expriry time of the notification.

raw

tile

toast

The badge has the following properties:

value

Optional. A numeric or string value that indicates a prdefined glyph to be displayed.

version

Optional. Version of the payload.

The raw has the following properties:

payload

Optional. A JSON block that is transferred to the application only if the application is already open.

The tile has the following properties:

tag

Optional. A string value that is set as label for the notification. Used in notification cycling.

visual

The visual has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

binding

For tile notifications, its a JSON array containing JSON blocks of binding attributes. For toast notification, its a JSON block of binding attributes.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

lang

Optional. Locale of the payload.

version

Optional. Version of the payload.

The binding has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

fallback

Optional. Template to be used as a fallback.

image

Optional. A JSON array containing JSON blocks of following image attributes.

lang

Optional. Locale of the payload.

template

Mandatory. Template type of the notification.

text

Optional. A JSON array containing JSON blocks of following text attributes.

The image has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

alt

Optional. Image description.

src

Mandatory. Image URI.

The text has the following properties:

content

Mandatory. A string value that is displayed in the toast.

lang

Optional. Locale of the payload.

The toast has the following properties:

audio

duration

Optional. Notification will be displayed for the specified duration. Should be 'short' or 'long'.

launch

Optional. A string value that is passed to the application when it is launched by tapping or clicking the toast notification.

visual

The audio has the following properties:

loop

Optional. A boolean value to indicate if the sound should be repeated or not.

silent

Optional. A boolean value to indicate if the sound should be played or not.

src

Optional. A string value that specifies the notification sound type or path to local audio file.

The target has the following properties:

deviceIds

An array of the devices represented by the device identifiers. Devices with these ids receive the notification. This is a unicast notification

platforms

An array of device platforms. Devices running on these platforms receive the notification. Supported values are A (Apple/iOS), G (Google/Android) and W (Microsoft/Windows).

tagNames

An array of tags specified as tagNames. Devices that are subscribed to these tags receive the notification. Use this type of target for tag based notifications

userIds

An array of users represented by their userIds to send the notification. This is a unicast notification.

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Push Message (GET)

Description

Retrieves the message details by messageId

Requires below JNDI properties to be set for the MobileFirst Push.

Method

Path

/apps/<applicationId>/messages/<messageId>

Example:

https://example.com:443/imfpush/v1/apps/myapp/messages/mymessage

Path Parameters

applicationId

The name or identifier of the application

messageId

The identifier of the message

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "messages.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "alert" : "TestMessage",
  "messageId" : "1234",
}

Response Properties

alert

The message text.

messageId

The unique identifier of the message.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The message with the specified messageId is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Message (DELETE)

Description

Deletes the message details by messageId

Method

Path

/apps/<applicationId>/messages/<messageId>

Example:

https://example.com:443/imfpush/v1/apps/myapp/messages/mymessage

Path Parameters

applicationId

The name or identifier of the application

messageId

The identifier of the message

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "messages.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The message with the specified messageId is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Subscriptions (GET)

Description

Retrieves all or a subset of existing subscriptions

Retrieves subscriptions for the push service for the specified criteria.

Method

Path

/apps/<applicationId>/subscriptions

Example:

https://example.com:443/imfpush/v1/apps/myapp/subscriptions?deviceId=12345-6789&expand=true&filter=tagName=@tag&offset=0&size=10&tagName=sports&userId=user1

Path Parameters

applicationId

The name or identifier of the application

Query Parameters

deviceId

Retrieves subscriptions only for the specified deviceId

expand

Retrieves additional metadata for every subscription that is returned in the response

filter

The filter specifies the search criteria. Refer to the filter section for detailed syntax

offset

Pagination offset that is normally used along with the size

size

Pagination size that is normally used along with the offset to retrieve a subset

tagName

Retrieves subscriptions only for the specified tagName

userId

Retrives subscriptions only for the specified userId

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "subscriptions.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "pageInfo" : {
    "count" : "2",
    "next" : "",
    "previous" : "",
    "totalCount" : "10",
  },
  "subscriptions" : [
    {
      "deviceId" : "12345-6789",
      "href" : "http://localhost:9080/imfpush/v1/apps/appName/subscriptions?deviceId=12345-6789&tagName=testTag",
      "subscriptionId" : "1",
      "tagName" : "testTag",
      "userId" : "admin",
    },
    ...
  ],
}

Response Properties

pageInfo

The pagination information

subscriptions

The array of device subscriptions.

The pageInfo has the following properties:

count

The number of device registration that are retrieved

next

A hyperlink to the next page

previous

A hyperlink to the previous page

totalCount

The total number of device registration present for the given search criteria

The subscriptions has the following properties:

deviceId

The unique id of the device.

href

The REST URL to get subscriptions details.

subscriptionId

The unique id of subscription

tagName

The tag name to subscribe

userId

The userId of the device.

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Subscription (POST)

Description

Creates a new subscription for a tag.

Given the deviceId and the tag name, the request creates a new subscription which subscribes the device to the tag specified

Method

Path

/apps/<applicationId>/subscriptions

Example:

https://example.com:443/imfpush/v1/apps/myapp/subscriptions

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "subscriptions.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "deviceId" : "12345-6789",
  "tagName" : "testTag",
}

Payload Properties

deviceId

The unique id of the device.

tagName

The tag name to subscribe.

Response

JSON Example:

{
  "deviceId" : "12345-6789",
  "href" : "http://localhost:9080/imfpush/v1/apps/appName/subscriptions?deviceId=12345-6789&tagName=testTag",
  "subscriptionId" : "1",
  "tagName" : "testTag",
  "userId" : "admin",
}

Response Properties

deviceId

The unique id of the device.

href

The REST URL to get subscriptions details.

subscriptionId

The unique id of subscription

tagName

The tag name to subscribe.

userId

The user id for subscription

Errors

400

A device registraion has userId longer than 254 characters.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A device registraion with the specified deviceId is not found.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Device Subscription By Tag Name (DELETE)

Description

Unsubscribes the specified device from a tag.

Given the deviceId and the tag name, the request deletes a existing subscription from a tag specified. It will return HTTP response code 204 with no content on successfully unsubscribing

Method

Path

/apps/<applicationId>/subscriptions

Example:

https://example.com:443/imfpush/v1/apps/myapp/subscriptions?deviceId=12345-6789&tagName=testTag

Path Parameters

applicationId

The name or identifier of the application

Query Parameters

deviceId

The unique ID for the device

tagName

The tag name to unsubscribe

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "subscriptions.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Errors

400

A device registraion has userId longer than 254 characters.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A device registraion with the specified deviceId is not found.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Tags (GET)

Description

Retrieves all tags of Push

Method

Path

/apps/<applicationId>/tags

Example:

https://example.com:443/imfpush/v1/apps/myapp/tags?expand=true&filter=platform==A&offset=0&size=10&subscriptionCount=10

Path Parameters

applicationId

The name or identifier of the application

Query Parameters

expand

Retrieves detailed information about applications.

filter

Search criteria filter. Refer to the filter section for detailed syntax.

offset

Pagination offset that is normally used along with the size.

size

Pagination size that is normally used along with the offset to retrieve a subset.

subscriptionCount

Retrieves the number of tag subscriptions

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "tags.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "pageInfo" : {
    "count" : "2",
    "next" : "",
    "previous" : "",
    "totalCount" : "10",
  },
  "tags" : [
    {
      "createdMode" : "API",
      "createdTime" : "2015-08-22T18:19:58Z",
      "description" : "Description about SampleTag",
      "href" : "https://example.com:443/imfpush/v1/apps/testApp/tags/SampleTag",
      "lastUpdatedTime" : "2015-08-22T18:19:58Z",
      "name" : "SampleTag",
    },
    ...
  ],
}

Response Properties

pageInfo

The pagination information

tags

The array of applications.

The pageInfo has the following properties:

count

The number of tags that are retrieved

next

A hyperlink to the next page

previous

A hyperlink to the previous page

totalCount

The total number of application tags present for the given search criteria

The tagnames has the following properties:

createdMode

Defaults to API

createdTime

The time at which the tag was created

description

The description of the tag

href

The URL to the tag

lastUpdatedTime

The time at which the tag was last updated

name

An unique name of the tag in the application

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

A tag with the specified name is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Tag (POST)

Description

Creates a tag.

Creates a tag with the unique name in the application, which is referenced by the applicationId parameter. The tag has associated with a description about the tag. The tag name cannot be updated after it is created

Method

Path

/apps/<applicationId>/tags

Example:

https://example.com:443/imfpush/v1/apps/myapp/tags

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "tags.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Consumes

Produces

Payload input

JSON Example:

{
  "description" : "Description about SampleTag",
  "name" : "SampleTag",
}

Payload Properties

description

The description of the tag

name

An unique name of the tag in the application

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-08-22T18:19:58Z",
  "description" : "Description about SampleTag",
  "href" : "https://example.com:443/imfpush/v1/apps/testApp/tags/SampleTag",
  "lastUpdatedTime" : "2015-08-22T18:19:58Z",
  "name" : "SampleTag",
}

Response Properties

createdMode

Defaults to API

createdTime

The time at which the tag was created

description

The description of the tag

href

The URL to the tag

lastUpdatedTime

The time at which the tag was last updated

name

An unique name of the tag in the application

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Tag (GET)

Description

Retrieves an existing tag of Push

Method

Path

/apps/<applicationId>/tags/<tagName>

Example:

https://example.com:443/imfpush/v1/apps/myapp/tags/sports

Path Parameters

applicationId

The name or identifier of the application

tagName

The name of the tag

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "tags.read" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-08-22T18:19:58Z",
  "description" : "Description about SampleTag",
  "lastUpdatedTime" : "2015-08-22T18:19:58Z",
  "name" : "SampleTag",
}

Response Properties

createdMode

Defaults to API

createdTime

The time at which the tag was created

description

The description of the tag

lastUpdatedTime

The time at which the tag was last updated

name

An unique name of the tag in the application

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The tag with the specified tagName is not found.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Tag (PUT)

Description

Updates tag information

Updates the tag referenced by the tagName of the application referenced by the applicationId.

Method

Path

/apps/<applicationId>/tags/<tagName>

Example:

https://example.com:443/imfpush/v1/apps/myapp/tags/sports

Path Parameters

applicationId

The name or identifier of the application

tagName

The name of the tag

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "tags.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Produces

Payload input

JSON Example:

{
  "description" : "Description about SampleTag",
  "name" : "SampleTag",
}

Payload Properties

description

The description of the tag

name

An unique name of the tag in the application

Response

JSON Example:

{
  "createdMode" : "API",
  "createdTime" : "2015-08-22T18:19:58Z",
  "description" : "Description about SampleTag",
  "href" : "https://example.com:443/imfpush/v1/apps/testApp/tags/SampleTag",
  "lastUpdatedTime" : "2015-08-22T18:19:58Z",
  "name" : "SampleTag",
}

Response Properties

createdMode

Defaults to API

createdTime

The time at which the tag was created

description

The description of the tag

href

The URL to the tag

lastUpdatedTime

The time at which the tag was last updated

name

An unique name of the tag in the application

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The tag with the specified tagName is not found.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Tag (DELETE)

Description

Delete the tag in the application.

Method

Path

/apps/<applicationId>/tags/<tagName>

Example:

https://example.com:443/imfpush/v1/apps/myapp/tags/sports

Path Parameters

applicationId

The name or identifier of the application

tagName

The name of the tag

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "tags.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The tag with the specified tagName is not found.

500

An internal error occurred.

Push Webhooks (POST)

Description

Creates a webhook.

Creates a webhook with the unique name in the application, which is referenced by the applicationId parameter. The webhook has associated with a name, url and event types. The webhook name cannot be updated after it is created

Method

Path

/apps/<applicationId>/webhooks

Example:

https://example.com:443/imfpush/v1/apps/myapp/webhooks

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "webhooks.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Produces

Payload input

JSON Example:

{
  "eventTypes" : "onDeviceRegister,onDeviceUpdate,onDeviceUnregister,onSubscribe,onUnsubscribe",
  "name" : "SampleWebhook",
  "url" : "http://samplewebhook.com",
}

Payload Properties

eventTypes

The list of event types comma separated

name

An unique name of the webhook in the application

url

The url of the webhook

Response

JSON Example:

{
  "eventTypes" : "onDeviceRegister,onDeviceUpdate,onDeviceUnregister,onSubscribe,onUnsubscribe",
  "name" : "SampleWebhook",
  "url" : "http://samplewebhook.com",
}

Response Properties

eventTypes

The list of event types comma separated

name

An unique name of the webhook in the application

url

The description of the webhook

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Webhooks (PUT)

Description

Updates an existing webhook.

Method

Path

/apps/<applicationId>/webhooks/<webhookName>

Example:

https://example.com:443/imfpush/v1/apps/myapp/webhooks/mywebhook

Path Parameters

applicationId

The name or identifier of the application

webhookName

The identifier of the webhook

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "webhooks.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Content-Type

Specify the JSON content type. For example: application/json. This parameter has to be mandatorily set.

Produces

Payload input

JSON Example:

{
  "eventTypes" : "onDeviceRegister,onDeviceUpdate,onDeviceUnregister,onSubscribe,onUnsubscribe",
  "name" : "SampleWebhook",
  "url" : "http://samplewebhook.com",
}

Payload Properties

eventTypes

The list of event types comma separated

name

An unique name of the webhook in the application

url

The url of the webhook

Response

JSON Example:

{
  "eventTypes" : "onDeviceRegister,onDeviceUpdate,onDeviceUnregister,onSubscribe,onUnsubscribe",
  "name" : "SampleWebhook",
  "url" : "http://samplewebhook.com",
}

Response Properties

eventTypes

The list of event types comma separated

name

An unique name of the webhook in the application

url

The description of the webhook

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The webhook does not exist.

405

Unsupported Content type - The content type specified in Content-Type header is not application/json.

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.

Push Webhook (DELETE)

Description

Delete the webhook in the application.

Method

Path

/apps/<applicationId>/webhooks/<webhookName>

Example:

https://example.com:443/imfpush/v1/apps/myapp/webhooks/mywebhook

Path Parameters

applicationId

The name or identifier of the application

webhookName

The identifier of the webhook

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Authorization

The token with the scope "webhooks.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Produces

Errors

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The webhook with the specified name is not found.

500

An internal error occurred.

Push Health Checker (GET)

Description

Checks the status of Push Service.

Method

Path

/health/status

Example:

https://example.com:443/imfpush/v1/health/status

Header Parameters

Accept-Language

(Optional) The preferred language to use for error messages. Default:en-US

Produces

Errors

406

Unsupported Accept type - The content type specified in Accept header is not application/json.

500

An internal error occurred.