---
title: Subscription keys
slug: cms-13/docs/subscription-keys
createdAt: 2026-07-30T20:22:10.689Z
---

The Subscription API links users to URI-formatted keys and provides lookup methods for notification recipients. Use it to build recipient lists for notification messages based on content or workflow events.

Access the API through `ISubscriptionService`. This interface provides methods to subscribe users, unsubscribe users, and find subscribers for a given key.

The Subscription API operates independently from user notifications. Neither system calls the other. For an overview of the notification framework, see [User notifications](docId\:HvplEiyWgPcXh-KRb85lg). Populate the recipient field of a notification message by querying subscriptions when an event occurs. Filter the sender from the subscriber list before posting the notification.

## Subscription keys

A subscription key uses URI format and identifies an item that triggers notifications. The format is unconstrained but should represent the item it identifies.

Subscribing to a key indicates interest in that item and all items below it in the URI hierarchy. Items below a key are those whose key begins with the subscribed key.

## Subscribe and unsubscribe

The `ISubscriptionService` interface provides methods to add and remove users from subscriptions.

Call `SubscribeAsync` to add one or more users to a subscription. Call `UnsubscribeAsync` to remove one or more users.

Subscribe to the `UserSubscribed` and `UserUnsubscribed` events to track changes. These events fire only on the first change. Adding a user to a subscription a second time does not trigger the event.

## Clear subscriptions

Use `ClearUserAsync` and `ClearSubscriptionAsync` to remove subscriptions in bulk when cleaning up users or keys.

Call `ClearUserAsync` to remove all subscriptions for a user when deleting that user from the system. Call `ClearSubscriptionAsync` to remove all users from a specific subscription. The `UserCleared` and `SubscriptionCleared` events fire for these operations.

## List subscriptions

`ListSubscriptionsAsync` returns all subscriptions for a specific user. Display or audit a user's subscription state with this method.

## Find subscribers

Use `ListSubscribersAsync` and `FindSubscribersAsync` to identify users subscribed to a key and build recipient lists for notifications.

`ListSubscribersAsync` returns users subscribed to a specific key. `FindSubscribersAsync` returns users that match a key fully or partially through a begins-with comparison on whole URI path segments.

:::hint{type="info"}
**Note**
Partial matching operates on whole segments delimited by slashes in the URI path.
:::