Server Reference

Server implementation is optional. Use the Instance ID service if you want to perform these operations:

Get information about app instances

To get information about an app instance, call the Instance ID service at this endpoint, providing the app instance's token as shown:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Parameters

  • Authorization: key=YOUR_API_KEY. Set this parameter in the header.
  • [optional] boolean details: set this query parameter to true to get available IID token details, including connection information and FCM or GCM topic subscription information (if any) for the device associated with this token. When not specified, defaults to false.

Results

On success the call returns HTTP status 200 and a JSON object containing:

  • application - package name associated with the token.
  • authorizedEntity - projectId authorized to send to the token.
  • applicationVersion - version of the application.
  • appSigner - sha1 fingerprint for the signature applied to the package. Indicates which party signed the app; for example,Play Store.
  • attestStatus - returns ROOTED, NOT_ROOTED, or UNKNOWN to indicate whether or not the device is rooted.
  • platform - returns ANDROID, IOS, or CHROME to indicate the device platform to which the token belongs.

If the details flag is set:

  • connectionType - returns WIFI, MOBILE or OTHER. Returns nothing if the connection is uninitialized.
  • connectDate - the most recent day that the device has established a connection with GCM.
  • rel - relations associated with the token. For example, a list of topic subscriptions.

Example GET request

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?details=true
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Example result

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "attestStatus":"ROOTED",
  "appSigner":"1a2bc3d4e5",
  "connectionType":"WIFI",
  "connectDate":"2015-05-12
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

Create relationship maps for app instances

The Instance ID API lets you create relationship maps for app instances. For example, you can map a registration token to a Google Cloud Messaging topic, subscribing the app instance to the topic. The API provides methods for creating such relationships both indivdually, and in bulk.

Create a relation mapping for an app instance

Given a registration token and a supported relationship, you can create a mapping. For example, you can subscribe an app instance to a Google Cloud Messaging topic by calling the Instance ID service at this endpoint, providing the app instance's token as shown:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Parameters

  • Authorization: key=YOUR_API_KEY. Set this parameter in the header.

Results

On success the call returns HTTP status 200.

Example POST request

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Example result

HTTP 200 OK
{}

Manage relationship maps for multiple app instances

Using the Instance ID service's batch methods, you can perform batch management of app instances. For example, you can perform bulk addition or removal of app instances to an FCM or GCM topic. To manage app instances, call the Instance ID service at this endpoint, providing the app instance tokens in the JSON body:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Parameters

  • Authorization: key=YOUR_API_KEY. Set this parameter in the header.
  • to : The topic name.
  • registration_tokens : The array of IID tokens for the app instances you want to add or remove.

Results

On success the call returns HTTP status 200. Empty results indicate successful subscription for the token. For failed subscriptions, the result contains one of these error codes:

  • NOT_FOUND — The registration token has been deleted or the app has been uninstalled.
  • INVALID_ARGUMENT — The registration token provided is not valid for the Sender ID.
  • INTERNAL — The backend server failed for unknown reasons. Retry the request.
  • TOO_MANY_TOPICS — Excessive number of topics per app instance.

Example POST request

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

Example result

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Create registration tokens for APNs tokens

Using the Instance ID service's batchImport method, you can bulk import existing iOS APNs tokens to Google Cloud Messaging or Firebase Cloud Messaging, mapping them to valid registration tokens. Call the Instance ID service at this endpoint, providing a list of APNs tokens in the JSON body:

 https://iid.googleapis.com/iid/v1:batchImport

The response body contains an array of Instance ID registration tokens ready to be used for sending FCM or GCM messages to the corresponding APNs device token.

Parameters

  • Authorization: key=YOUR_API_KEY. Set this parameter in the header.
  • application : Bundle id of the app.
  • sandbox : Boolean to indicate sandbox environment (TRUE) or production (FALSE)
  • apns_tokens : The array of APNs tokens for the app instances you want to add or remove. Maximum 100 tokens per request.

Results

On success the call returns HTTP status 200 and a JSON result body. For each APNs token provided in the request, the results list includes:

  • The APNs token.
  • Status. Either OK, or an error message describing the failure.
  • For successful results, the registration token that FCM or GCM maps to the APNs token.

Example POST request

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Example result

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Manage registration tokens for push subscriptions

Using the Instance ID service's Web methods, you can import existing push subscriptions for Firebase Cloud Messaging. You can also update and delete them.

When you import a push subscription, you receive a registration token. This token allows you to use FCM features like topic messaging and device group messaging to target notifications to your web apps.

Import push subscriptions

You can import push subscriptions using InstanceID's web endpoint:

 https://iid.googleapis.com/v1/web/iid

The request must contain an authorization header set to your server key, and the PushSubscription object in the request body.

The response body contains a registration token ready to be used for sending FCM or GCM messages to the corresponding web app instance without having to encrypt the payload.

If you opt for a VAPID public key, use this specific FCM public key:

 BDOU99-h67HcA6JeFXHbSNMu7e2yNNu3RzoMj8TM4W88jITfq7ZmPvIM1Iv-4_l2LxQcYwhqby2xGpWwzjfAnG4

This key allows FCM to deliver messages to your web application.

Parameters

  • Authorization: key=YOUR_SERVER_KEY. Set this parameter in the header.
  • Request body: PushSubscription.toJson(). Pass the push subscription to the HTTP body without parsing it. The content matches W3C encoding of PushSubscription.

Response

On success the call returns HTTP status 201 Created and a JSON result body containing the IID token.

Example POST request

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Example result

HTTP 201 Created
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Update push subscriptions

You can update the push subscription associated with your registration token using the following endpoint:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Parameters

  • Authorization: key=YOUR_SERVER_KEY. Set this parameter in the header.
  • Request body: PushSubscription.toJson(). Pass the push subscription to the HTTP body without parsing it. The content matches W3C encoding of PushSubscription.

Results

On success the call returns HTTP status 200 and a registration token. This may be the same token you passed in the request, or a new token.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Example POST request

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Example result

 HTTP 200 OK
 {"token":"KctODamlM4:CI2k_HHw...3P1"}

Delete push subscriptions

A DELETE request removes the push subscription details from FCM database. You can still receive messages in your web application using the Push API protocol.

To delete a push subscription, send a DELETE request to:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Example DELETE request

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Example result

 HTTP 204 No-Content

Error responses

Calls to the Instance ID server API return the following HTTP error codes:

  • HTTP status 400 (Bad request) - request parameters are missing or invalid. Check error messages for detailed information.
  • HTTP status 401 (Unauthorized) - authorization header is invalid.
  • HTTP status 403 (Forbidden) - authorization header doesn't match the authorizedEntity.
  • HTTP status 404 (Not found) - Invalid HTTP path or IID token not found. Check error messages for detailed information.
  • HTTP status 503 (Service unavailable) - service is unavailable. Retry the request with exponential backoff.

Send feedback about...

Instance ID