Create topic subscriptions | Novu Documentation

This api will create subscription for subscriberIds for a topic. Its like subscribing to a common interest group. if topic does not exist, it will be created.

Authorization

Authorization<token>

API key authentication. Allowed headers-- "Authorization: ApiKey <api_key>".

In: header

Request Body

application/jsonRequired

subscriberIdsRequiredarray<string>

List of subscriber identifiers to subscribe to the topic (max: 100)

Path Parameters

topicKeyRequiredstring

The key identifier of the topic

Header Parameters

idempotency-keystring

A header for idempotency purposes

Response Body

Subscriptions created successfully

dataRequiredarray<object>

The list of successfully created subscriptions

metaRequiredobject

Metadata about the operation

errorsarray<object>

The list of errors for failed subscription attempts

export interface Response {
  /**
   * The list of successfully created subscriptions
   */
  data: SubscriptionDto[];
  /**
   * Metadata about the operation
   */
  meta: MetaDto;
  /**
   * The list of errors for failed subscription attempts
   */
  errors?: SubscriptionErrorDto[];
}
export interface SubscriptionDto {
  /**
   * The unique identifier of the subscription
   */
  _id: string;
  /**
   * The topic information
   */
  topic: TopicDto;
  /**
   * The subscriber information
   */
  subscriber: SubscriberDto;
  /**
   * The creation date of the subscription
   */
  createdAt: string;
  /**
   * The last update date of the subscription
   */
  updatedAt: string;
}
export interface TopicDto {
  /**
   * The internal unique identifier of the topic
   */
  _id: string;
  /**
   * The key identifier of the topic used in your application. Should be unique on the environment level.
   */
  key: string;
  /**
   * The name of the topic
   */
  name?: string;
}
export interface SubscriberDto {
  /**
   * The identifier of the subscriber
   */
  _id: string;
  /**
   * The external identifier of the subscriber
   */
  subscriberId: string;
  /**
   * The avatar URL of the subscriber
   */
  avatar?: string | null;
  /**
   * The first name of the subscriber
   */
  firstName?: string | null;
  /**
   * The last name of the subscriber
   */
  lastName?: string | null;
  /**
   * The email of the subscriber
   */
  email?: string | null;
}
export interface MetaDto {
  /**
   * The total count of subscriber IDs provided
   */
  totalCount: number;
  /**
   * The count of successfully created subscriptions
   */
  successful: number;
  /**
   * The count of failed subscription attempts
   */
  failed: number;
}
export interface SubscriptionErrorDto {
  /**
   * The subscriber ID that failed
   */
  subscriberId: string;
  /**
   * The error code
   */
  code: string;
  /**
   * The error message
   */
  message: string;
}

curl -X POST "https://api.novu.co/v2/topics/string/subscriptions" \
  -H "idempotency-key: string" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberIds": [
      "subscriberId1",
      "subscriberId2"
    ]
  }'

{
  "data": [
    {
      "_id": "64f5e95d3d7946d80d0cb679",
      "topic": {
        "_id": "64f5e95d3d7946d80d0cb677",
        "key": "product-updates",
        "name": "Product Updates"
      },
      "subscriber": {
        "_id": "64da692e9a94fb2e6449ad07",
        "subscriberId": "user-123",
        "avatar": "https://example.com/avatar.png",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      },
      "createdAt": "2025-04-24T05:40:21Z",
      "updatedAt": "2025-04-24T05:40:21Z"
    }
  ],
  "meta": {
    "totalCount": 3,
    "successful": 2,
    "failed": 1
  },
  "errors": [
    {
      "subscriberId": "invalid-subscriber-id",
      "code": "SUBSCRIBER_NOT_FOUND",
      "message": "Subscriber with ID invalid-subscriber-id could not be found"
    }
  ]
}