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

- [Get information about app instances](https://developers.google.com/instance-id/reference/server#get_information_about_app_instances). Verify app tokens or get more information about the app instance that created the token.
- [Create relationship maps for app instances](https://developers.google.com/instance-id/reference/server#create_relationship_maps_for_app_instances). Create relationships between app instances and entities.
- [Create registration tokens for APNs tokens](https://developers.google.com/instance-id/reference/server#create_registration_tokens_for_apns_tokens). This API lets you bulk import existing APNs tokens, mapping them to valid registration tokens for FCM.

## Get information about app instances

> [!CAUTION]
> **Caution:** The API will be removed on September 29, 2027. If you use the API to validate a token, use [FCM send API](https://developers.google.com/docs/reference/fcm/rest/v1/projects.messages/send) and set validate_only parameter to true. If you use the API to get topic subscription info, use [the new topic subscription API](https://developers.google.com/docs/reference/fcm/fcmtopics/rest).

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: Bearer <access_token>`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).
- `access_token_auth: true`. Set this parameter in the header.
- \[optional\] boolean `details`: set this query parameter to `true` to get FCM topic subscription information (if any) 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.
- `platform` - returns `ANDROID`, `IOS`, or `CHROME` to indicate the device platform to which the token belongs.

If the `details` flag is set:

- `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
    Content-Type:application/json
    Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
    access_token_auth: true

## Example result

    HTTP 200 OK
    {
      "application":"com.iid.example",
      "authorizedEntity":"123456782354",
      "platform":"Android",
      "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

> [!CAUTION]
> **Caution:** The API will be removed on September 29, 2027. Use [the new topic subscription API](https://developers.google.com/docs/reference/fcm/fcmtopics/rest).

The Instance ID API lets you create relationship maps for app instances.
For example, you can map a registration token to an FCM topic,
subscribing the app instance to the topic. The API provides methods for creating
such relationships both individually, 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 an FCM 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: Bearer <access_token>`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).
- `access_token_auth: true`. 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
    access_token_auth: true

#### 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 topic.
To update up to 1000 app instances per API call, 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: Bearer <access_token>`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).
- `access_token_auth: true`. 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.
- RESOURCE_EXHAUSTED --- Too many subscription or unsubscription requests in a short period of time. Retry with exponential backoff.

#### Example `POST` request

    https://iid.googleapis.com/iid/v1:batchAdd
    Content-Type:application/json
    Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
    access_token_auth: true
    {
       "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

> [!CAUTION]
> **Caution:** The API will be removed on September 29st, 2027. Use [FCM iOS SDK](https://firebase.google.com/docs/cloud-messaging/ios/get-started) to register an app instance with FCM.

Using the Instance ID service's `batchImport` method, you can bulk import
existing iOS APNs tokens to 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 messages to the corresponding APNs device token.

> [!NOTE]
> **Note:** The list of APNs tokens in each request cannot exceed 100.

### Parameters

- `Authorization: Bearer <access_token>`. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the `Authorization` header. For more information on obtaining this token, see [Provide credentials manually](https://firebase.google.com/docs/cloud-messaging/auth-server#provide-credentials-manually).
- `access_token_auth: true`. 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 maps to the APNs token.

### Example `POST` request

    https://iid.googleapis.com/iid/v1:batchImport
    Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
    access_token_auth:true
    {
      "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"
            },
         ]
      }

## 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.