Push Notifications

curl --request POST \
  --url https://api.lerix.dev/v1/{project-id}/notifications/send \
  --header 'Content-Type: application/json' \
  --header 'lerix-key: <api-key>' \
  --data '
{
  "title": "<string>",
  "body": "<string>",
  "deviceTokens": [
    "<string>"
  ],
  "externalUserIds": [
    "<string>"
  ],
  "sendByTopic": true,
  "topic": "<string>",
  "sound": "<string>",
  "imageUrl": "<string>",
  "metadata": {},
  "projectSlug": "<string>",
  "apiKey": "<string>",
  "source": "<string>",
  "sentAt": "<string>"
}
'

import requests

url = "https://api.lerix.dev/v1/{project-id}/notifications/send"

payload = {
    "title": "<string>",
    "body": "<string>",
    "deviceTokens": ["<string>"],
    "externalUserIds": ["<string>"],
    "sendByTopic": True,
    "topic": "<string>",
    "sound": "<string>",
    "imageUrl": "<string>",
    "metadata": {},
    "projectSlug": "<string>",
    "apiKey": "<string>",
    "source": "<string>",
    "sentAt": "<string>"
}
headers = {
    "lerix-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'lerix-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    body: JSON.stringify('<string>'),
    deviceTokens: ['<string>'],
    externalUserIds: ['<string>'],
    sendByTopic: true,
    topic: '<string>',
    sound: '<string>',
    imageUrl: '<string>',
    metadata: {},
    projectSlug: '<string>',
    apiKey: '<string>',
    source: '<string>',
    sentAt: '<string>'
  })
};

fetch('https://api.lerix.dev/v1/{project-id}/notifications/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lerix.dev/v1/{project-id}/notifications/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'body' => '<string>',
    'deviceTokens' => [
        '<string>'
    ],
    'externalUserIds' => [
        '<string>'
    ],
    'sendByTopic' => true,
    'topic' => '<string>',
    'sound' => '<string>',
    'imageUrl' => '<string>',
    'metadata' => [
        
    ],
    'projectSlug' => '<string>',
    'apiKey' => '<string>',
    'source' => '<string>',
    'sentAt' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "lerix-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lerix.dev/v1/{project-id}/notifications/send"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("lerix-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.lerix.dev/v1/{project-id}/notifications/send")
  .header("lerix-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lerix.dev/v1/{project-id}/notifications/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["lerix-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "matchedUsers": 123,
  "matchedDevices": 123,
  "unknownUserIds": [
    "<string>"
  ]
}

POST

{project-id}

notifications

send

Push Notifications

curl --request POST \
  --url https://api.lerix.dev/v1/{project-id}/notifications/send \
  --header 'Content-Type: application/json' \
  --header 'lerix-key: <api-key>' \
  --data '
{
  "title": "<string>",
  "body": "<string>",
  "deviceTokens": [
    "<string>"
  ],
  "externalUserIds": [
    "<string>"
  ],
  "sendByTopic": true,
  "topic": "<string>",
  "sound": "<string>",
  "imageUrl": "<string>",
  "metadata": {},
  "projectSlug": "<string>",
  "apiKey": "<string>",
  "source": "<string>",
  "sentAt": "<string>"
}
'

import requests

url = "https://api.lerix.dev/v1/{project-id}/notifications/send"

payload = {
    "title": "<string>",
    "body": "<string>",
    "deviceTokens": ["<string>"],
    "externalUserIds": ["<string>"],
    "sendByTopic": True,
    "topic": "<string>",
    "sound": "<string>",
    "imageUrl": "<string>",
    "metadata": {},
    "projectSlug": "<string>",
    "apiKey": "<string>",
    "source": "<string>",
    "sentAt": "<string>"
}
headers = {
    "lerix-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'lerix-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    body: JSON.stringify('<string>'),
    deviceTokens: ['<string>'],
    externalUserIds: ['<string>'],
    sendByTopic: true,
    topic: '<string>',
    sound: '<string>',
    imageUrl: '<string>',
    metadata: {},
    projectSlug: '<string>',
    apiKey: '<string>',
    source: '<string>',
    sentAt: '<string>'
  })
};

fetch('https://api.lerix.dev/v1/{project-id}/notifications/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lerix.dev/v1/{project-id}/notifications/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'body' => '<string>',
    'deviceTokens' => [
        '<string>'
    ],
    'externalUserIds' => [
        '<string>'
    ],
    'sendByTopic' => true,
    'topic' => '<string>',
    'sound' => '<string>',
    'imageUrl' => '<string>',
    'metadata' => [
        
    ],
    'projectSlug' => '<string>',
    'apiKey' => '<string>',
    'source' => '<string>',
    'sentAt' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "lerix-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lerix.dev/v1/{project-id}/notifications/send"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("lerix-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.lerix.dev/v1/{project-id}/notifications/send")
  .header("lerix-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lerix.dev/v1/{project-id}/notifications/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["lerix-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"body\": \"<string>\",\n  \"deviceTokens\": [\n    \"<string>\"\n  ],\n  \"externalUserIds\": [\n    \"<string>\"\n  ],\n  \"sendByTopic\": true,\n  \"topic\": \"<string>\",\n  \"sound\": \"<string>\",\n  \"imageUrl\": \"<string>\",\n  \"metadata\": {},\n  \"projectSlug\": \"<string>\",\n  \"apiKey\": \"<string>\",\n  \"source\": \"<string>\",\n  \"sentAt\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "matchedUsers": 123,
  "matchedDevices": 123,
  "unknownUserIds": [
    "<string>"
  ]
}

Send a push notification to one of three targets:

deviceTokens: specific registered devices.
externalUserIds: your own user IDs. Lerix delivers to every device each user signed in on (iOS, Android, web and macOS) in one request. Your apps link a device to a user with setUser; see Identify users.
topic (with sendByTopic: true): every device subscribed to a topic.

Use one target per request. externalUserIds can’t be combined with deviceTokens or sendByTopic: that request is rejected with NOTIFICATION_TARGET_INVALID.

See the API introduction to set up your base URL and private key before making requests.

Parameters

string

required

Your project ID from Project Settings in the dashboard.

string

required

Notification title shown to the user.

string

required

Notification message body.

string[]

One or more device tokens to deliver the notification to. One of the three targets: don’t combine it with externalUserIds or sendByTopic.

string[]

Your own user IDs, the same values your apps pass to setUser after login. Lerix finds every device currently linked to each ID, across all the platforms in this project, and delivers to all of them. Up to 1000 IDs per request, each 1 to 255 characters. One of the three targets: don’t combine it with deviceTokens or sendByTopic.An ID with no linked device isn’t an error (the user may not have installed the app yet). It comes back in unknownUserIds in the response. When the notification is scheduled with sentAt, devices are looked up again at send time, so a device that signs in after you schedule still receives it.

boolean

default:"false"

Set to true to deliver to every device subscribed to topic. One of the three targets: don’t combine it with deviceTokens or externalUserIds. Devices subscribe to a topic from your app using the SDK. A topic is created automatically the first time a device subscribes to it, or you can create one manually from the Topics tab in the dashboard.

string

The topic key to broadcast to. Required when sendByTopic is true, ignored otherwise.

string

Name of a custom notification sound. The file itself must already be bundled inside your app project — Lerix only passes the filename through to APNs/FCM, it doesn’t host or upload sound files. Leave empty to use the device’s default notification sound.iOS: the sound file’s name with its extension (e.g. sound.mp3; .caf/.wav also supported).Android: the resource name without an extension, matching a file under res/raw/ (e.g. sound for a file at res/raw/sound.mp3).

Supported formats: .wav, .mp3, .ogg.
Keep the filename lowercase — some tooling/devices ignore uppercase letters in resource names.
Keep the file small and under ~30 seconds; large files may not play on some devices.
If the named file isn’t found, the notification falls back to the device’s default sound rather than failing.
A given sound is locked in the first time it’s used on a device — Android fixes a notification channel’s sound at creation and never lets it change afterward, so switching to a different sound value later creates a new channel rather than updating the old one.

Web: not supported — the Web Notifications API has no cross-browser way to set a custom sound, so this parameter is ignored for web recipients.

string

URL of an image to show as a rich image in the notification. Lerix downloads it — this is a normal https:// URL, not a file you need to bundle in your app (unlike sound).Android: works automatically, rendered as a BigPictureStyle notification.iOS: requires the app to have a Notification Service Extension configured (a one-time setup step — see the Flutter push notifications guide). Without it, imageUrl is silently ignored on iOS; the notification still sends and displays normally, just without the image. Sending this field automatically sets APNs’ mutable-content flag, which is what triggers the extension to run.Web: works automatically, no extra setup — the service worker renders it as the notification’s icon/image directly.

object

Arbitrary custom data to attach to the notification. Any JSON object; omit for no metadata. Delivered to the device alongside title/body and readable from the SDK as payload.metadata in setOnNotificationReceived/setOnNotificationTapped.

string

Defaults to the project in the URL (/v1/:project-id/...); only needed for older integrations.

string

Deprecated alternative to the lerix-key header, still accepted.

string

default:"API"

Where the notification was sent from.

string

An ISO 8601 timestamp to schedule delivery for later instead of sending immediately. Omit it (or pass a time in the past) to send right away. A scheduled notification can be edited or canceled before it goes out — see Update a notification and Cancel a scheduled notification.

Never expose your private key in client-side code or public repositories. Send API requests from a trusted backend only.

Response

201 Created

{
  "success": true,
  "message": "Notification sent successfully",
  "notificationId": "b6b1a2b0-9c3f-4b3e-9c3f-4b3e9c3f4b3e"
}

Save notificationId. It’s what you pass to the other notification endpoints (update, unsend, cancel, and delivery status). When you send to externalUserIds, the response also says who was reached:

201 Created

{
  "success": true,
  "message": "Notification sent successfully",
  "notificationId": "b6b1a2b0-9c3f-4b3e-9c3f-4b3e9c3f4b3e",
  "matchedUsers": 1,
  "matchedDevices": 3,
  "unknownUserIds": ["user_456"]
}

number

How many of the requested IDs have at least one linked device.

number

How many devices the notification was sent to, across every platform.

string[]

Requested IDs with no linked device. Nothing was sent for them.

A device on a platform whose push keys aren’t configured yet doesn’t block the others: it gets a failed delivery with the PLATFORM_NOT_CONFIGURED code, visible in Get delivery status.

Errors

HTTP status	`error`	Meaning
400	`NOTIFICATION_TARGET_INVALID`	The request combined `externalUserIds` with `deviceTokens` or `sendByTopic`

Every other failure follows the shape and codes documented in Error & success codes.

Getting started

Frameworks

Modules

Developers

Push Notifications

Parameters

Response

Errors

​Parameters

​Response

​Errors

Parameters

Response

Errors