Create topic subscriptions

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.

POST /v2/topics/{topicKey}/subscriptions

TypeScript

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.topics.subscriptions.create({
    subscriptions: [
      {
        identifier: "subscriber-123-subscription-a",
        subscriberId: "subscriber-123",
      },
      {
        identifier: "subscriber-456-subscription-b",
        subscriberId: "subscriber-456",
      },
    ],
    name: "My Topic",
    context: {
      "key": "org-acme",
    },
    preferences: [
      {
        condition: {
          "===": [
            {
              "var": "tier",
            },
            "premium",
          ],
        },
        workflowId: "workflow-123",
      },
    ],
  }, "<value>");

  console.log(result);
}

run();

201

{
  "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": "[e-mail]"
      },
      "createdAt": "2025-04-24T05:40:21Z",
      "updatedAt": "2025-04-24T05:40:21Z",
      "identifier": "tk=product-updates:si=subscriber-123",
      "name": "My Subscription",
      "preferences": [
        {
          "subscriptionId": "64f5e95d3d7946d80d0cb679",
          "enabled": true,
          "workflow": {
            "id": "64a1b2c3d4e5f6g7h8i9j0k1",
            "identifier": "welcome-email",
            "name": "Welcome Email Workflow",
            "critical": false,
            "tags": [
              "user-onboarding",
              "email"
            ],
            "data": {
              "category": "onboarding",
              "priority": "high"
            }
          },
          "condition": {
            "and": [
              {
                "===": [
                  {
                    "var": "tier"
                  },
                  "premium"
                ]
              }
            ]
          }
        }
      ],
      "contextKeys": [
        "tenant:org-a",
        "project:proj-123"
      ]
    }
  ],
  "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"
    }
  ]
}

Authorizations

Authorization · string · header · required

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

Headers

idempotency-key · string

A header for idempotency purposes

Path Parameters

topicKey · string · required

The key identifier of the topic

Body

application/json

subscriberIds · string[] · deprecated

List of subscriber IDs to subscribe to the topic (max: 100). @deprecated Use the "subscriptions" property instead.

Example:

["subscriberId1", "subscriberId2"]

subscriptions · (string | object)[]

List of subscriptions to subscribe to the topic (max: 100). Can be either a string array of subscriber IDs or an array of objects with identifier and subscriberId

Example:

[
  {
    "identifier": "subscriber-123-subscription-a",
    "subscriberId": "subscriber-123"
  },
  {
    "identifier": "subscriber-456-subscription-b",
    "subscriberId": "subscriber-456"
  }
]

name · string

The name of the topic

Example:

"My Topic"

context · object

Show child attributes

preferences · string · object · object[]

The preferences of the topic. Can be a simple workflow ID string, workflow preference object, or group filter object

Example:

[
  {
    "workflowId": "workflow-123",
    "condition": { "===": [{ "var": "tier" }, "premium"] }
  }
]

Response

201

application/json

Subscriptions created successfully

data · object[] · required

The list of successfully created subscriptions

Show child attributes

meta · object · required

Metadata about the operation

Show child attributes

errors · object[]

The list of errors for failed subscription attempts

Show child attributes