Create or Overwrite an Installation

Article
04/11/2016

Updated: March 11, 2016

Creates or overwrites an installation.

Request

Method	Request URI	HTTP version
PUT	https://{namespace}.servicebus.windows.net/{NotificationHub}/installations/{id}?api-version=2015-01	HTTP/1.1

Request Headers

The following table describes required and optional request headers.

Request Header	Description
Content-Type	application/json
Authorization	Token generated as specified in Shared Access Signature Authentication with Service Bus, or Service Bus authentication and authorization with Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS).
x-ms-version	2015-01

Request Body

The following table describes the properties of the JSON request body for installations:

Name	Type	Required	Read-Only	Description
installationId	String	Yes	No	Globally unique identifier string
lastActiveOn	String	No	Yes	This is the date when the installation was made inactivate by the PNS.
expirationTime	String	No	Yes	This is a string containing the date and time in W3C DTF, YYYY-MM-DDThh:mmTZD (e.g. 1997-07-16T19:20+01:00)) in which the registration will expire. The value can be set at the hub level on create or update, and will default to never expire (9999-12-31T23:59:59).
lastUpdate	String	Ignored when updating. Returned when reading.	Yes	Date in W3C format of last update to this installation.
platform	String	Yes	No	Can be {apns, wns, mpns, adm, gcm}.
pushChannel	String	Yes	No	The PNS handle for this installation (in case of WNS the ChannelUri of the ApplicationTile).
expiredPushChannel	Boolean	Ignored when updating. Returned when reading.	Yes	This is true if the PNS expired the channel.
tags	Array of strings	No	No	An array of tags. Tags are strings as defined in hub specs.
templates	JSON object	No	No	A JSON object representing a dictionary of templateNames to template description.
templates.{name}	String	No	No	JSON object representing a template.
templates.{name}.body	String	Yes, if template present	No	Template for the body of notification payload.
templates.{name}.headers	JSON object	No. Can be present only if platform is wns or mpns.	No	JSON object where each property is a header name and value is a template expression.
templates.{name}.expiry	String	No. Can be present only if platform is apns	No	Template expression evaluating in W3D date format.
templates.{name}.tags	Array of strings	No	No	Array of tags for this template.
secondaryTiles	JSON object	No. Can be present only if platform is wns.	No	JSON object containing a dictionary of tileId and secondaryTiles objects.
secondaryTile.{tileId}	JSON object	No	No	JSON object with push properties for secondary tiles.
secondaryTile.{tileId}.pushChannel	String	Yes, if tileId is present	No	ChannelUri for secondary tile.
secondaryTile.{tileId}.tags	Array of strings	No	No	Tags for native notifications to secondary tile.
secondaryTile.{tileId}.templates	JSON object	No	No	Same as templates property but for each secondary tile.

In JSON, the order of elements is not important.
Template body has to be JSON for APNS, GCM, ADM.
Template body must be XML for WNS and MPNS (except when raw).
Templates for WNS must include X-WNS-Type header.
Templates for MPNS must have compatible headers as mentioned in Sending push notifications for Windows Phone 8.

Some JSON examples follow.

Example to register with APNS:

{ 
    "installationId": "12234", 
    "tags": ["foo", "bar"], 
    "platform": "apns", 
    "pushChannel": "ABCDEF-123456-…" 
}

Note

The Tags element is optional.

Example to register natively with WNS including a template and no tags:

{ 
    "installationId": "12234", 
    "platform": "wns", 
    "pushChannel": "https://db3...", 
    "templates": { 
        "myTemplate" : { 
            body : '<toast><visual lang="en-US"><binding template="ToastTest01"><text id="1">$myTextProp1</text></binding></visual></tile>',
            headers: { "X-WNS-Type": "wns/toast" }, 
            "tags": ["foo", "bar"] 
            } 

        } 
}

A skeleton listing of many possible elements

{ 
    installationId: "", 
    expirationTime: "", 
    tags: ["foo", "bar"],
    lastUpdate: “”, 
    user: "", 
    advertisingId: "", 
    appId: "" 
    platform: "", 
    pushChannel: "", 

    templates: { 
        "templateName1" : { 
            body: "", 
            headers: { "X-WNS-Type": "wns/tile" }, 
            expiration: "",
            tags: ["foo", "bar"] 
            } 
        } 

    secondaryTiles: { 
        "tileId1": { 
            pushChannel: "", 
            tags: ["foo", "bar"], 

            templates: { 
                "otherTemplate": { 
                    bodyTemplate: "", 
                    headers: { ... }, 
                    tags: ["foo"] 
                    } 
                } 
            } 
        }
}

Response

The response includes an HTTP status code and a set of response headers.

Response Codes

Code	Description
200	The installation was created successfully.
400	The installation could not be created/overwritten because the request was malformed.
401	Authorization failure. The access key was incorrect.
403	Too many installations in this namespace - Installations not created .
403	Request rejected because API call rate is too high.

For information about status codes, see Status and Error Codes.

Response Headers

Response Header	Description
Content-type	application/json
Content-Location	The location of the installation in the format: https://{namespace}.servicebus.windows.net/{NotificationHub}/installations/<installationId>

Content-type

application/json

Content-Location

The location of the installation in the format:

https://{namespace}.servicebus.windows.net/{NotificationHub}/installations/<installationId>

Response Body

None.