Push Applications (GET)

Description

Retrieves all the applications.

Method

GET

Path

/apps/

Example:

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

Query Parameters

Query parameters are optional.
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

application/json

Response

The details of all the applications.

JSON Example:

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

Response Properties

The response has the following 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

POST

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

application/json

Payload input

The details of the application.

JSON Example:

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

Payload Properties

The payload has the following properties:
applicationId
The application Id.
enabled
Optinal. The status of the applicaton. Default is true

Response

The details of the application.

JSON Example:

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

Response Properties

The response has the following 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

GET

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

application/json

Response

The details of the application.

JSON Example:

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

Response Properties

The response has the following 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

DELETE

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

GET

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

application/json

Response

Retrieve application settings.

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

The response has the following 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

GET

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

application/octet-stream

Response

Retrieves APNS certificate for the application.

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

GET

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

application/json

Response

Retrieves APNS settings for the application.

JSON Example:

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

Response Properties

The response has the following 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

PUT

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

multipart/form-data

Produces

application/json

Response

Successfully updated the APNS settings.

JSON Example:

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

Response Properties

The response has the following 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

DELETE

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

GET

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

application/json

Response

Retrieves GCM settings for the application.

JSON Example:

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

Response Properties

The response has the following 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

PUT

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

application/json

Produces

application/json

Payload input

The details of the gcm settings.

JSON Example:

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

Payload Properties

The payload has the following properties:
apiKey
The GCM API Key.
senderId
The GCM SenderId.

Response

Retrieves GCM settings for the application.

JSON Example:

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

Response Properties

The response has the following 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

DELETE

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

GET

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

application/json

Response

Retrieves GCM settings for the application.

JSON Example:

{
  "senderId" : "123456789",
}

Response Properties

The response has the following 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

GET

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

application/json

Response

Retrieves SMS settings for the application.

JSON Example:

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

Response Properties

The response has the following 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

PUT

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

application/json

Produces

application/json

Payload input

The details of the sms settings.

JSON Example:

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

Payload Properties

The payload has the following 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

Successfully updated the SMS settings.

JSON Example:

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

Response Properties

The response has the following 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

DELETE

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

GET

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

application/json

Response

Retrieves WNS settings for the application.

JSON Example:

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

Response Properties

The response has the following 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

PUT

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

application/json

Produces

application/json

Payload input

The details of the wns settings.

JSON Example:

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

Payload Properties

The payload has the following properties:
clientSecret
The Client secret.
packageSID
Package SID

Response

Successfully updated the WNS settings.

JSON Example:

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

Response Properties

The response has the following 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

DELETE

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

GET

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

application/json

Response

The status of the application.

JSON Example:

{
  "enabled" : "true",
}

Response Properties

The response has the following 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

PUT

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

application/json

Produces

application/json

Payload input

The details of the application.

JSON Example:

{
  "enabled" : "true",
}

Payload Properties

The payload has the following properties:
enabled
The status of the application

Response

The details of the application.

JSON Example:

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

Response Properties

The response has the following 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

GET

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

Query parameters are optional.
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

application/json

Response

The details of the device registration that is retrieved.

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

The response has the following 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

POST

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

application/json

Produces

application/json

Payload input

The details of the device registration.

JSON Example:

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

Payload Properties

The payload has the following 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

The details of the application.

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

The response has the following 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

GET

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

application/json

Response

The details of the device registration that is retrieved.

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

The response has the following 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

PUT

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

application/json

Produces

application/json

Payload input

The details of the device registration will be updated.

JSON Example:

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

Payload Properties

The payload has the following 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

The details of the device registration that is updated.

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

The response has the following 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

DELETE

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

application/json

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

POST

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

application/json

Produces

application/json

Payload input

The payload in JSON format has values for message, target, and settings.

JSON Example:

{
  "message" : {
    "alert" : "Test message",
  },
  "notificationType" : 1,
  "settings" : {
    "apns" : {
      "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

The payload has the following 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:

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

The details of the message that is retrieved.

JSON Example:

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

Response Properties

The response has the following 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

POST

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

application/json

Produces

application/json

Payload input

The payload in JSON format has values for array of messages, target, and settings.

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

The payload has the following 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.

  • imfpush/mfp.push.messages.persist.size (Queue size to store messages before writing to Database).
  • imfpush/mfp.push.messages.persist.delay.mins (Delay in minitues to write sent messages in Database).
  • Method

    GET

    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

    application/json

    Response

    The details of the message that is retrieved.

    JSON Example:

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

    Response Properties

    The response has the following 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

    DELETE

    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

    GET

    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

    Query parameters are optional.
    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

    application/json

    Response

    The details of the device subscription that is retrieved.

    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

    The response has the following 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

    POST

    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

    application/json

    Produces

    application/json

    Payload input

    The details of the device and the tag name to which it has to subscribe.

    JSON Example:

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

    Payload Properties

    The payload has the following properties:
    deviceId
    The unique id of the device.
    tagName
    The tag name to subscribe.

    Response

    The details of the device subscription that is updated.

    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

    The response 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 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

    DELETE

    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

    Query parameters are optional.
    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

    application/json

    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

    GET

    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

    Query parameters are optional.
    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

    application/json

    Response

    The details of the tag that is retrieved.

    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

    The response has the following 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

    POST

    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

    application/json

    Produces

    application/json

    Payload input

    The details of the tag.

    JSON Example:

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

    Payload Properties

    The payload has the following properties:
    description
    The description of the tag
    name
    An unique name of the tag in the application

    Response

    The details of the tag.

    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

    The response 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

    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

    GET

    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

    application/json

    Response

    The details of the tag that is retrieved.

    JSON Example:

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

    Response Properties

    The response has the following 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

    PUT

    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

    application/json

    Payload input

    The details of the tag.

    JSON Example:

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

    Payload Properties

    The payload has the following properties:
    description
    The description of the tag
    name
    An unique name of the tag in the application

    Response

    The details of the tag.

    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

    The response 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

    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

    DELETE

    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

    application/json

    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

    POST

    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

    application/json

    Payload input

    The details of the webhook.

    JSON Example:

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

    Payload Properties

    The payload has the following 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

    The details of the webhook.

    JSON Example:

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

    Response Properties

    The response has the following 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

    PUT

    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

    application/json

    Payload input

    The details of the webhook.

    JSON Example:

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

    Payload Properties

    The payload has the following 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

    The details of the webhook.

    JSON Example:

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

    Response Properties

    The response has the following 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

    DELETE

    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

    application/json

    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

    GET

    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

    application/json

    Errors

    406
    Unsupported Accept type - The content type specified in Accept header is not application/json.
    500
    An internal error occurred.