Management
Create a subscriber
Create a subscriber with the subscriber attributes. subscriberId is a required field, rest other fields are optional, if the subscriber already exists, it will be updated
POST
/
v2
/
subscribers
Go
package main
import(
"context"
"github.com/novuhq/novu-go/v3"
"github.com/novuhq/novu-go/v3/models/components"
"log"
)
func main() {
ctx := context.Background()
s := v3.New(
v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
)
res, err := s.Subscribers.Create(ctx, components.CreateSubscriberRequestDto{
FirstName: v3.Pointer("John"),
LastName: v3.Pointer("Doe"),
Email: v3.Pointer("john.doe@example.com"),
Phone: v3.Pointer("+1234567890"),
Avatar: v3.Pointer("https://example.com/avatar.jpg"),
Locale: v3.Pointer("en-US"),
Timezone: v3.Pointer("America/New_York"),
SubscriberID: "<id>",
}, nil, nil)
if err != nil {
log.Fatal(err)
}
if res.SubscriberResponseDto != nil {
// handle response
}
}import { Novu } from "@novu/api";
const novu = new Novu({
secretKey: "YOUR_SECRET_KEY_HERE",
});
async function run() {
const result = await novu.subscribers.create({
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
phone: "+1234567890",
avatar: "https://example.com/avatar.jpg",
locale: "en-US",
timezone: "America/New_York",
subscriberId: "<id>",
});
console.log(result);
}
run();using Novu;
using Novu.Models.Components;
var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");
var res = await sdk.Subscribers.CreateAsync(createSubscriberRequestDto: new CreateSubscriberRequestDto() {
FirstName = "John",
LastName = "Doe",
Email = "john.doe@example.com",
Phone = "+1234567890",
Avatar = "https://example.com/avatar.jpg",
Locale = "en-US",
Timezone = "America/New_York",
SubscriberId = "<id>",
});
// handle responsedeclare(strict_types=1);
require 'vendor/autoload.php';
use novu;
use novu\Models\Components;
$sdk = novu\Novu::builder()
->setSecurity(
'YOUR_SECRET_KEY_HERE'
)
->build();
$createSubscriberRequestDto = new Components\CreateSubscriberRequestDto(
firstName: 'John',
lastName: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890',
avatar: 'https://example.com/avatar.jpg',
locale: 'en-US',
timezone: 'America/New_York',
subscriberId: '<id>',
);
$response = $sdk->subscribers->create(
createSubscriberRequestDto: $createSubscriberRequestDto
);
if ($response->subscriberResponseDto !== null) {
// handle response
}from novu_py import Novu
with Novu(
secret_key="YOUR_SECRET_KEY_HERE",
) as novu:
res = novu.subscribers.create(create_subscriber_request_dto={
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"avatar": "https://example.com/avatar.jpg",
"locale": "en-US",
"timezone": "America/New_York",
"subscriber_id": "<id>",
})
# Handle response
print(res)curl --request POST \
--url https://api.novu.co/v2/subscribers \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"subscriberId": "<string>",
"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": {}
}
'const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
subscriberId: '<string>',
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: {}
})
};
fetch('https://api.novu.co/v2/subscribers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.novu.co/v2/subscribers")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"subscriberId\": \"<string>\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"avatar\": \"https://example.com/avatar.jpg\",\n \"locale\": \"en-US\",\n \"timezone\": \"America/New_York\",\n \"data\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v2/subscribers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subscriberId\": \"<string>\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"avatar\": \"https://example.com/avatar.jpg\",\n \"locale\": \"en-US\",\n \"timezone\": \"America/New_York\",\n \"data\": {}\n}"
response = http.request(request)
puts response.read_body{
"subscriberId": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"channels": [
{
"providerId": "slack",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>",
"integrationIdentifier": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"subscriberId": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"channels": [
{
"providerId": "slack",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>",
"integrationIdentifier": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"errors": {
"fieldName1": {
"messages": [
"Field is required",
"Must be a valid email address"
],
"value": "invalidEmail"
},
"fieldName2": {
"messages": [
"Must be at least 18 years old"
],
"value": 17
},
"fieldName3": {
"messages": [
"Must be a boolean value"
],
"value": true
},
"fieldName4": {
"messages": [
"Must be a valid object"
],
"value": {
"key": "value"
}
},
"fieldName5": {
"messages": [
"Field is missing"
],
"value": null
},
"fieldName6": {
"messages": [
"Undefined value"
]
}
},
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}"API rate limit exceeded"{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}"Please wait some time, then try again."Authorizations
API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".
Headers
A header for idempotency purposes
Query Parameters
If true, the request will fail if a subscriber with the same subscriberId already exists
Body
application/json
Unique identifier of the subscriber
First name of the subscriber
Example:
"John"
Last name of the subscriber
Example:
"Doe"
Email address of the subscriber
Example:
"john.doe@example.com"
Phone number of the subscriber
Example:
"+1234567890"
Avatar URL or identifier
Example:
"https://example.com/avatar.jpg"
Locale of the subscriber
Example:
"en-US"
Timezone of the subscriber
Example:
"America/New_York"
Additional custom data associated with the subscriber
Response
Created
The identifier used to create this subscriber, which typically corresponds to the user ID in your system.
The unique identifier of the organization to which the subscriber belongs.
The unique identifier of the environment associated with this subscriber.
Indicates whether the subscriber has been deleted.
The timestamp indicating when the subscriber was created, in ISO 8601 format.
The timestamp indicating when the subscriber was last updated, in ISO 8601 format.
The internal ID generated by Novu for your subscriber. This ID does not match the subscriberId used in your queries. Refer to subscriberId for that identifier.
The first name of the subscriber.
The last name of the subscriber.
The email address of the subscriber.
The phone number of the subscriber.
The URL of the subscriber's avatar image.
The locale setting of the subscriber, indicating their preferred language or region.
An array of channel settings associated with the subscriber.
Show child attributes
Show child attributes
An array of topics that the subscriber is subscribed to.
Indicates whether the subscriber is currently online.
The timestamp indicating when the subscriber was last online, in ISO 8601 format.
The version of the subscriber document.
Additional custom data for the subscriber
Timezone of the subscriber
Was this page helpful?
⌘I
Go
package main
import(
"context"
"github.com/novuhq/novu-go/v3"
"github.com/novuhq/novu-go/v3/models/components"
"log"
)
func main() {
ctx := context.Background()
s := v3.New(
v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
)
res, err := s.Subscribers.Create(ctx, components.CreateSubscriberRequestDto{
FirstName: v3.Pointer("John"),
LastName: v3.Pointer("Doe"),
Email: v3.Pointer("john.doe@example.com"),
Phone: v3.Pointer("+1234567890"),
Avatar: v3.Pointer("https://example.com/avatar.jpg"),
Locale: v3.Pointer("en-US"),
Timezone: v3.Pointer("America/New_York"),
SubscriberID: "<id>",
}, nil, nil)
if err != nil {
log.Fatal(err)
}
if res.SubscriberResponseDto != nil {
// handle response
}
}import { Novu } from "@novu/api";
const novu = new Novu({
secretKey: "YOUR_SECRET_KEY_HERE",
});
async function run() {
const result = await novu.subscribers.create({
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com",
phone: "+1234567890",
avatar: "https://example.com/avatar.jpg",
locale: "en-US",
timezone: "America/New_York",
subscriberId: "<id>",
});
console.log(result);
}
run();using Novu;
using Novu.Models.Components;
var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");
var res = await sdk.Subscribers.CreateAsync(createSubscriberRequestDto: new CreateSubscriberRequestDto() {
FirstName = "John",
LastName = "Doe",
Email = "john.doe@example.com",
Phone = "+1234567890",
Avatar = "https://example.com/avatar.jpg",
Locale = "en-US",
Timezone = "America/New_York",
SubscriberId = "<id>",
});
// handle responsedeclare(strict_types=1);
require 'vendor/autoload.php';
use novu;
use novu\Models\Components;
$sdk = novu\Novu::builder()
->setSecurity(
'YOUR_SECRET_KEY_HERE'
)
->build();
$createSubscriberRequestDto = new Components\CreateSubscriberRequestDto(
firstName: 'John',
lastName: 'Doe',
email: 'john.doe@example.com',
phone: '+1234567890',
avatar: 'https://example.com/avatar.jpg',
locale: 'en-US',
timezone: 'America/New_York',
subscriberId: '<id>',
);
$response = $sdk->subscribers->create(
createSubscriberRequestDto: $createSubscriberRequestDto
);
if ($response->subscriberResponseDto !== null) {
// handle response
}from novu_py import Novu
with Novu(
secret_key="YOUR_SECRET_KEY_HERE",
) as novu:
res = novu.subscribers.create(create_subscriber_request_dto={
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"avatar": "https://example.com/avatar.jpg",
"locale": "en-US",
"timezone": "America/New_York",
"subscriber_id": "<id>",
})
# Handle response
print(res)curl --request POST \
--url https://api.novu.co/v2/subscribers \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"subscriberId": "<string>",
"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": {}
}
'const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
subscriberId: '<string>',
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: {}
})
};
fetch('https://api.novu.co/v2/subscribers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.novu.co/v2/subscribers")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"subscriberId\": \"<string>\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"avatar\": \"https://example.com/avatar.jpg\",\n \"locale\": \"en-US\",\n \"timezone\": \"America/New_York\",\n \"data\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v2/subscribers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"subscriberId\": \"<string>\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"avatar\": \"https://example.com/avatar.jpg\",\n \"locale\": \"en-US\",\n \"timezone\": \"America/New_York\",\n \"data\": {}\n}"
response = http.request(request)
puts response.read_body{
"subscriberId": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"channels": [
{
"providerId": "slack",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>",
"integrationIdentifier": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"subscriberId": "<string>",
"_organizationId": "<string>",
"_environmentId": "<string>",
"deleted": true,
"createdAt": "<string>",
"updatedAt": "<string>",
"_id": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"email": "<string>",
"phone": "<string>",
"avatar": "<string>",
"locale": "<string>",
"channels": [
{
"providerId": "slack",
"credentials": {
"webhookUrl": "https://example.com/webhook",
"channel": "general",
"deviceTokens": [
"token1",
"token2",
"token3"
],
"alertUid": "12345-abcde",
"title": "Critical Alert",
"imageUrl": "https://example.com/image.png",
"state": "resolved",
"externalUrl": "https://example.com/details"
},
"_integrationId": "<string>",
"integrationIdentifier": "<string>"
}
],
"topics": [
"<string>"
],
"isOnline": true,
"lastOnlineAt": "<string>",
"__v": 123,
"data": {},
"timezone": "<string>"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"errors": {
"fieldName1": {
"messages": [
"Field is required",
"Must be a valid email address"
],
"value": "invalidEmail"
},
"fieldName2": {
"messages": [
"Must be at least 18 years old"
],
"value": 17
},
"fieldName3": {
"messages": [
"Must be a boolean value"
],
"value": true
},
"fieldName4": {
"messages": [
"Must be a valid object"
],
"value": {
"key": "value"
}
},
"fieldName5": {
"messages": [
"Field is missing"
],
"value": null
},
"fieldName6": {
"messages": [
"Undefined value"
]
}
},
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}"API rate limit exceeded"{
"statusCode": 404,
"timestamp": "2024-12-12T13:00:00Z",
"path": "/api/v1/resource",
"message": "xx xx xx ",
"ctx": {
"workflowId": "some_wf_id",
"stepId": "some_wf_id"
},
"errorId": "abc123"
}"Please wait some time, then try again."