Bulk create subscribers | Novu Documentation

Using this endpoint you can create multiple subscribers at once, to avoid multiple calls to the API. The bulk API is limited to 500 subscribers per request.

Authorization

Authorization<token>

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

In: header

Request Body

application/jsonRequired

subscribersRequiredarray<object>

An array of subscribers to be created in bulk.

Header Parameters

idempotency-keystring

A header for idempotency purposes

Response Body

Created

updatedRequiredarray<object>

An array of subscribers that were successfully updated.

createdRequiredarray<object>

An array of subscribers that were successfully created.

failedRequiredarray<object>

An array of failed operations with error messages and optional subscriber IDs.

export interface Response {
  /**
   * An array of subscribers that were successfully updated.
   */
  updated: UpdatedSubscriberDto[];
  /**
   * An array of subscribers that were successfully created.
   */
  created: CreatedSubscriberDto[];
  /**
   * An array of failed operations with error messages and optional subscriber IDs.
   */
  failed: FailedOperationDto[];
}
export interface UpdatedSubscriberDto {
  /**
   * The ID of the subscriber that was updated.
   */
  subscriberId: string;
}
export interface CreatedSubscriberDto {
  /**
   * The ID of the subscriber that was created.
   */
  subscriberId: string;
}
export interface FailedOperationDto {
  /**
   * The error message associated with the failed operation.
   */
  message?: string;
  /**
   * The subscriber ID associated with the failed operation. This field is optional.
   */
  subscriberId?: string;
}

curl -X POST "https://api.novu.co/v1/subscribers/bulk" \
  -H "idempotency-key: string" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "avatar": "https://example.com/avatar.jpg",
        "locale": "en-US",
        "timezone": "America/New_York",
        "data": {},
        "subscriberId": "string"
      }
    ]
  }'

{
  "updated": [
    {
      "subscriberId": "string"
    }
  ],
  "created": [
    {
      "subscriberId": "string"
    }
  ],
  "failed": [
    {
      "message": "string",
      "subscriberId": "string"
    }
  ]
}