API Reference · Developer Documentation

Beacon Notifications API

Audience: Backend engineers
Version: v2.3
Doc ID: API-BEACON-023
Status: Current

1.0Overview

The Beacon Notifications API sends transactional push, email, and SMS messages from your application. You define a template once, then trigger it with a single request. Beacon handles channel fallback, retries, and delivery tracking.

Base URL	Format	Rate limit
`https://api.beacon.example/v2`	JSON over HTTPS	600 requests/min per key

2.0Authentication

Authenticate every request with a bearer token in the Authorization header. Generate keys in the Beacon console under Settings > API Keys.

# All requests require this header
Authorization: Bearer sk_live_51Hxxxxxxxx

Warning Live keys begin with sk_live_ and send real messages. Use sk_test_ keys in development — test sends appear in the console but are never delivered.

3.0Send a notification

POST/notifications

Triggers a notification from an existing template. The request returns immediately with a notification ID; delivery happens asynchronously.

3.1Request body

Field	Type	Required	Description
`template_id`	string	Yes	Template to send, for example `tmpl_order_shipped`.
`recipient`	object	Yes	The user to notify. Provide `user_id` or an explicit `email`/`phone`.
`data`	object	No	Key–value pairs merged into the template, such as `order_number`.
`channels`	array	No	Delivery order. Defaults to `["push", "email"]`. Beacon falls back to the next channel if the first fails.

3.2Example request

# Notify a customer that their order shipped
curl -X POST https://api.beacon.example/v2/notifications \
  -H "Authorization: Bearer sk_live_51Hxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_order_shipped",
    "recipient": { "user_id": "usr_8842" },
    "data": { "order_number": "A-10293" }
  }'

3.3Example response

HTTP/1.1 202 Accepted
{
  "id": "ntf_01J8ZK2M",
  "status": "queued",
  "channels": ["push", "email"]
}

Note A 202 Accepted response means Beacon accepted the request — not that the message was delivered. Poll the status endpoint (section 4.0) or configure a webhook for delivery confirmation.

4.0Check delivery status

GET/notifications/{id}

Returns the current state of a notification and a per-channel delivery timeline.

Status	Meaning
`queued`	Accepted and waiting to send.
`delivered`	At least one channel confirmed delivery.
`failed`	All channels exhausted without delivery. See `failure_reason`.

5.0Error handling

Beacon uses conventional HTTP status codes. Error responses include a machine-readable code and a human-readable message.

HTTP	Code	How to resolve
401	`invalid_key`	The API key is missing, revoked, or malformed. Generate a new key in the console.
404	`template_not_found`	The `template_id` doesn't exist in this environment. Test and live templates are separate.
422	`missing_merge_field`	The template references a field not present in `data`. The message lists the missing field.
429	`rate_limited`	Slow down and retry after the interval in the `Retry-After` header.