Topics

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

Request

  • Base URL: https://api.notifly.io
  • URL: https://api.notifly.io/v2/topics/{topicKey}/subscriptions
  • Auth: API key in header Authorization

Path parameters

topicKeystring required

The key identifier of the topic

Request body

subscriberIdsstring[]

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

namestring

The name of the topic

contextobject

Example request

{
  "subscriberIds": [
    "subscriberId1",
    "subscriberId2"
  ],
  "subscriptions": [
    {
      "identifier": "subscriber-123-subscription-a",
      "subscriberId": "subscriber-123"
    },
    {
      "identifier": "subscriber-456-subscription-b",
      "subscriberId": "subscriber-456"
    }
  ],
  "name": "My Topic",
  "preferences": [
    {
      "workflowId": "workflow-123",
      "condition": {
        "===": [
          {
            "var": "payload.tier"
          },
          "premium"
        ]
      }
    }
  ]
}

Response

Subscriptions created successfully

Example response

{
  "data": {
    "data": [
      {
        "_id": "64f5e95d3d7946d80d0cb679",
        "identifier": "tk=product-updates:si=subscriber-123",
        "name": "My Subscription",
        "topic": {
          "_id": "64f5e95d3d7946d80d0cb677",
          "key": "product-updates",
          "name": "Product Updates",
          "data": {
            "category": "product",
            "priority": 1
          }
        },
        "subscriber": {
          "_id": "64da692e9a94fb2e6449ad07",
          "subscriberId": "user-123",
          "avatar": "https://example.com/avatar.png",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@example.com"
        },
        "preferences": [
          {
            "subscriptionId": "64f5e95d3d7946d80d0cb679",
            "workflow": {
              "id": "64a1b2c3d4e5f6g7h8i9j0k1",
              "identifier": "welcome-email",
              "name": "Welcome Email Workflow",
              "tags": [
                "user-onboarding",
                "email"
              ],
              "data": {
                "category": "onboarding",
                "priority": "high"
              }
            },
            "enabled": true,
            "condition": {
              "and": [
                {
                  "===": [
                    {
                      "var": "payload.tier"
                    },
                    "premium"
                  ]
                }
              ]
            }
          }
        ],
        "contextKeys": [
          "tenant:org-a",
          "project:proj-123"
        ],
        "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"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.