API docs by Redocly

The Notifier SaaS API (v1)

Download OpenAPI specification:

Programmatic API for managing groups and group alerts.

API version: This document applies to API version v1. Pass Notifier-API-Version: v1 to override the account default per request. Successful responses echo the resolved version in the same response header.

Authentication

  1. Exchange your API key for an access token at POST /auth/token.
  2. Include Authorization: Bearer <access_token> on all protected routes.
  3. When the access token expires (15 minutes), call POST /auth/refresh with your refresh token and the expired access token.
  4. Refresh tokens expire after 30 days.

Rate limits

Token endpoints are limited per IP and API key prefix. Authenticated routes are limited per account session.

Validation

Path parameters such as groupId and alertId must be valid UUIDs. Invalid values return HTTP 400 with error.code of validation_error before any database lookup.

Invalid query parameter values return HTTP 400 with error.code of invalid_query_parameter. Unknown query parameters (for example ?previous instead of ?timeframe=previous) also return HTTP 400. Invalid JSON request bodies and other request validation failures return HTTP 400 with error.code of validation_error.

Field limits

The API enforces maximum string lengths on group and alert fields. Values longer than the limit return HTTP 400 with error.code of validation_error.

Field Max length Where set
Group name 60 name on create/update group
Alert title 60 Derived from the group name when the alert is scheduled; not a separate request field
Alert message 80 message on create/update alert
Alert note 480 note on create/update alert (optional)
Alert link 2048 link on create/update alert (optional)

When an alert is delivered, the push notification title is the group name and the body is the alert message. Update the group name before scheduling if you need a different notification title.

General flow

The general flow is:

  1. Create a group
  2. Invite your user(s) to join the group
  3. Send an alert

Tips

  • Sending too many alerts will make your customers unhappy.
  • Save your account's plan limits to make sure you don't exceed the number of alerts you can send in a month.
  • Your usage can be monitored by visting your account's dashboard.
  • Individaul alerts can only be sent via API.

Auth

API key exchange and token refresh

Exchange API key for tokens

Returns a JWT for API calls and a refresh token.

WARNING: Your API key is a secret and should only be called from server-side/backend environments. NEVER expose, hardcode, or execute this request in client-side code (e.g., browsers, mobile apps), prompt outputs, or public logs.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
optional
apiKey
string

Optional body field; Bearer header is preferred.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Refresh access token

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Account

Account status and plan limits

Get account info

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "planName": "string",
  • "planLimits": {
    }
}

Groups

Group management

Create a group

Create a group by supplying the group's name. Make sure the group name is easily recognized by your users - for example, include your organization name in the group name.

You also have the option to limit when and how many users are allowed to join.

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
name
required
string [ 1 .. 60 ] characters

Group name. Maximum 60 characters.

memberLimit
integer or null >= 1
joinStartDate
string or null <date-time>
joinEndDate
string or null <date-time>
joinClosed
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "memberLimit": 1,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "status": "active",
  • "name": "string",
  • "memberLimit": 0,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "joinLink": "string"
}

Update a group

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
groupId
required
string <uuid>
name
string [ 1 .. 60 ] characters

Group name. Maximum 60 characters.

memberLimit
integer or null >= 1
joinStartDate
string or null <date-time>
joinEndDate
string or null <date-time>
joinClosed
boolean
status
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "name": "string",
  • "memberLimit": 1,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "status": "active",
  • "name": "string",
  • "memberLimit": 0,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "joinLink": "string"
}

List groups

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "all" "active" "inactive"

Filter groups by status. Omit or set to all to return all groups. Set to active or inactive to filter. An empty value returns HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get group statistics

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

query Parameters
timeframe
string
Default: "last12"
Enum: "last12" "current" "previous"

Time window for statistics. Defaults to last12 when omitted or empty. Invalid values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Alerts

Group alert scheduling and delivery

List group alerts

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

query Parameters
status
string
Enum: "all" "scheduled" "sent" "cancelled"

Filter alerts by status. Omit, leave empty, or set to all to return all alerts in the timeframe. Invalid values return HTTP 400.

timeframe
string
Default: "last12"
Enum: "last12" "current" "previous"

Time window for alerts. Defaults to last12 when omitted or empty. Invalid values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Schedule an alert

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
message
required
string [ 1 .. 80 ] characters

Alert message. Maximum 80 characters. Becomes the push notification body when delivered.

note
string or null <= 480 characters

Optional alert note. Maximum 480 characters.

link
string or null <= 2048 characters

Optional alert link. Maximum 2048 characters.

sendAt
required
string <date-time>
refId
string^[0-9a-fA-F]{64}$

Optional SHA-256 reference (64 lowercase hex characters after normalization). When set, the alert is delivered only to the active member bound to this reference in the group. Omitted means a broadcast to all active members. Null is not allowed.

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "note": "string",
  • "link": "string",
  • "sendAt": "2019-08-24T14:15:22Z",
  • "refId": "string"
}

Response samples

Content type
application/json
{
  • "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e"
}

Get alert details

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  • "status": "scheduled",
  • "is1to1Alert": true,
  • "refId": "string",
  • "alert": {
    }
}

Update a scheduled alert

Update an alert anytime before its scheduled delivery. Alerts cannot be updated once they have been sent.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
message
string [ 1 .. 80 ] characters

Alert message. Maximum 80 characters.

note
string or null <= 480 characters

Optional alert note. Maximum 480 characters.

link
string or null <= 2048 characters

Optional alert link. Maximum 2048 characters.

sendAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "note": "string",
  • "link": "string",
  • "sendAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Cancel a scheduled alert

Cancel an alert anytime before its scheduled delivery. Alerts cannot be canceled once they have been sent.

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}