Alertive
API docs by Redocly

Alertive API (2.5.0)

Download OpenAPI specification:

Unlock seamless communication and automation with the Alertive API, a powerful tool designed to integrate directly with Alertive's highly configurable system. This documentation provides a comprehensive guide to leveraging the API's key functions facilitating creating conversations, checking their state, sending notifications, dynamically escalating participation and much more. By exposing a carefully selected subset of configuration keys and rigorously testing for reliability, the Alertive API enables you to automate alert and message creation ensuring efficient and dependable communication for your organisation. The overarching term for a communication, whether it's a chat, alert or task is a “conversation”.

Base URL

Depending on the type of system you’re integrating with will depend on which Alertive API base URL you’ll use. Below is a list of the currently available base URLs and the purpose of each.

Testing: https://testing.alertiveapi.com/ - Used to integrate with internal Alertive environments and will include untested API features. Only used by the Alertive team.

Staging: https://staging.alertiveapi.com/ - Used to integrate with UAT systems and will include changes not yet deployed to production.

Production: https://prod.alertiveapi.com/ - Used to integrate with production systems and will only include fully tested and stable API features.

Authentication

Getting a token to make authenticated requests to the Alertive API

To fully utilise the Alertive API you’ll need to make a HTTP request to the appropriate token endpoint to retrieve an access token. The obtained token can then be used in subsequent API requests.

Token Endpoint: [API BASE URL]/oauth2/token

Prerequisites

  • Client ID: Your unique identifier for the Alertive API
  • Client Secret: The confidential secret associated with your Client ID. This should be kept secure and never exposed in client-side code.
  • Authorization Grant Type: For this method, we will be using the client_credentials grant type.

Step-by-Step Guide

1. Construct the Request Body

The request body must be application/x-www-form-urlencoded and contain the following parameters:

grant_type=client_credentials

2. Create the Basic Authorization Header

Encode your Client ID and Client Secret using Base64 in the format client_id:client_secret.

Example:

  • Concatenated: abcdefg12345:hijklmnop67890
  • Base64: YWJjZGVmZzEyMzQ1OmhpamtsbW5vcDY3ODkw
  • Header: Basic YWJjZGVmZzEyMzQ1OmhpamtsbW5vcDY3ODkw

3. Make the POST Request

Example using curl:

curl -X POST \
  https://[API BASE URL]/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic YWJjZGVmZzEyMzQ1OmhpamtsbW5vcDY3ODkw' \
  -d 'grant_type=client_credentials'

4. Process the Response

Successful response:

{
  "access_token": "YWJjZGVmZzEyMzQ1OmhpamtsbW5vcDY3ODkw",
  "expires_in": 3600,
  "token_type": "Bearer"
}

5. Using the Access Token

Example using curl:

curl -X GET \
  https://prod.alertiveapi.com/conversations \
  -H 'Authorization: Bearer [YOUR_ACCESS_TOKEN]'

Create Conversations

The “Create a New Conversation” endpoint allows you to initiate a new conversation and serves as the entry point for creating alerts, tasks, and named conversations. Depending on the parameters provided in the request payload, this endpoint can be used to generate alert messages to notify users of events, assign actionable tasks, or start named conversations for ongoing discussions grouped under a specific title.

Authorizations:
OAuth2
header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema:
required
name
string <= 100 characters

Name of the conversation, shown as a heading in the notification preview. Distinct from title.

conversation_type
required
string
Enum: "alert" "named" "task"

Type of conversation to create. Also determines the default values applied when optional fields are omitted.

tab
string [ 1 .. 25 ] characters .*\S.*

Specifies which tab the conversation appears under. If omitted, tab is derived from conversation_type:

  • alert → alert
  • task → task
  • named → chat Provide this field to override that default. The values all and unread are not accepted. Must contain at least one non-whitespace character (whitespace-only strings are invalid).
title
required
string <= 100 characters

The conversation title/subject displayed to participants.

description
required
string <= 1000 characters

Description of the conversation

type
string <= 100 characters

Sub-type of the conversation (e.g., "Bloods", "Cannular", "Patient Relocation", "Catheter")

priority_value
integer [ 1 .. 99999 ]

Priority value for the conversation (must be a positive integer between 1 and 99999), with 1 being the highest priority.

priority_label
string <= 25 characters

Label for the priority level (required if priority_value is provided)

priority_colour
string^#[0-9A-Fa-f]{6}$

Color code for the priority level in #RRGGBB format (required if priority_value is provided)

due_date
string^\d{4}-\d{2}-\d{2}( \d{2}:\d{2})?$

Due date for the task in Europe/London local time. Format: "YYYY-MM-DD HH:MM" or "YYYY-MM-DD"

colour
string^#[0-9A-Fa-f]{6}$

Color code for the conversation in #RRGGBB format

ios_icon
string <= 100 characters

Apple SF Symbol name for the conversation icon on iOS. Common examples: checkmark.square.fill, text.bubble, text.document, waveform.path.ecg, bell, bed.double.fill, heart.fill. If omitted for task conversations, defaults to checkmark.square.fill.

android_icon
string <= 100 characters

Material icon for Android and Web, referenced as material_NAME_normal where NAME is the chosen icon. Common examples: material_check_box_normal, material_chat_normal, material_assignment_normal, material_monitor_heart_normal, material_notifications_normal, material_bed_normal, material_favorite_normal. If omitted for task conversations, defaults to material_domain_verification_normal.

sound_file_id
string <= 50 characters ^[A-Za-z0-9_-]+$

Identifier for the notification sound

is_critical
boolean

When true, the alert uses the device's critical alert behaviour and can override volume and Do Not Disturb settings. Defaults if omitted: alert and task → true. Not applicable to named conversations.

chat_available
boolean

Controls whether free-text chat is available. When false, participants see the alert and response options only. Defaults if omitted: alert → false; named and task → true.

expiry_ttl
integer [ 1 .. 7884000 ]
Default: 3600

Time-to-live in seconds for conversation expiry. If omitted, defaults to 3600.

activity_ttl
integer [ 1 .. 7884000 ]
Default: 86400

Time-to-live in seconds for conversation activity. If omitted, defaults to 86400.

object or Array of objects
object

Defines the flow of response options that will be shown. The structure maps from the current state to the available next states using response option value fields (not name or label). Object keys and array entries must match the value of options in response_options. If no response_flow is provided, all response options will be shown initially. The response_flow must have an initial state with empty string key (""), see request samples for example usage. When response_flow is provided, alert.allow_additional_responses is required.

participant_can_leave
boolean

Whether participants can leave the conversation. Defaults if omitted: alert → false; named and task → true.

owner_can_close_early
boolean

When true, the owner can close the conversation manually before it expires. Defaults if omitted: alert → false; named and task → true.

owner_can_add_additional_contacts
boolean

Whether the owner can add further participants after the conversation is created. Defaults if omitted: alert → false; named and task → true.

can_send_attachments_within_conversation
boolean

Whether participants can send attachments within the conversation. Defaults if omitted: alert → false; named and task → true.

Array of objects <= 10 items

Image or audio attachments to include on the conversation. Supply file bytes either way — via a multipart/form-data request (preferred; see that content type below), or inline as base64 in this application/json field. The API uploads each file to Alertive's attachment storage on your behalf and attaches the resulting URL when the conversation is created.

Accepted MIME types: images image/jpeg, image/jpg, image/png; audio audio/x-m4a, audio/mp4, audio/mpeg. This API enforces a maximum of 4 MB per attachment (decoded size for application/json/base64 requests, file size for multipart/form-data), and a combined maximum across all attachments in a single request of approximately 4.5 MB — the whole request body (all attachments plus every other field, encoded as base64 for transport regardless of content type) must fit within this API's underlying Lambda payload limit. Alertive's own upstream storage may enforce a different per-file limit as well — contact Alertive support to confirm the current server-side value for your system before relying on a specific number there.

show_responses_to_participants
boolean

Whether participants other than the owner can view the responses tab and see other participants' responses. Defaults to false unless set to true. For alert conversations, defaults to true if omitted.

object

Additional custom attributes for the conversation. Supports up to 5 extra attributes (extra_attr_1 through extra_attr_5). An attribute is of type 'text' and can be marked as 'mandatory', 'optional', or 'notAvailable'.

Array of objects <= 10 items

Optional integration actions that can be triggered from the conversation.

Integration actions require server-side configuration by the Alertive support team. You can only use integration actions that have been pre-configured on your system. Contact Alertive support to set up new integration actions or to see what actions are available.

object

Alert-specific configuration for alert and task conversations

required
Array of objects [ 1 .. 100 ] items

The recipients of the conversation

object

Optional SIP data

object

Optional patient information related to the conversation

object or string

Optional external system data to attach to the conversation. This data is stored as a tag and can be retrieved later via the GET endpoint. Maximum size is 1KB (including tag name). Can be provided as either a JSON object or a string.

webhook_enabled
boolean

Enables webhooks for this conversation. If omitted, webhooks are not enabled.

webhook_id
string <= 50 characters

Identifier for the webhook configuration

object or Array of strings

Events configuration for webhooks. Can be provided as either a JSON object or an array.

object or Array of strings

Webhook endpoints configuration. Can be provided as either a JSON object or an array.

Responses

Request samples

Content type
Example
{
  • "name": "Emergency Alert",
  • "conversation_type": "alert",
  • "title": "Patient Cardiac Arrest",
  • "description": "Patient in Room 204 experiencing cardiac arrest",
  • "is_critical": true,
  • "chat_available": false,
  • "recipients": [
    ],
  • "alert": {
    },
  • "attachments": [
    ],
  • "patient_data": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Conversation created successfully.",
  • "success": true,
  • "data": {
    }
}

Read Conversations

The “Read Conversation” endpoint allows you to retrieve a specific conversation by its ID, but it only returns the conversation’s metadata. This includes high-level details such as the conversation type, status, and timestamps, without exposing the full message history or content.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

The ID of the conversation

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Responses

Response samples

Content type
application/json
Example
{
  • "message": "Conversation retrieved successfully.",
  • "success": true,
  • "data": {
    }
}

Update Conversations

The "Update Conversation" endpoint allows you to update specific fields of an existing conversation, but only if it was originally created via the API. You can update the title, description, and participants. When updating participants, the provided list replaces the existing participants (any participants not in the new list will be removed, and any new participants will be added). Only include the fields you want to update in the request body.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

The ID of the conversation

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema: application/json
required
title
string <= 100 characters

The conversation title/subject displayed to participants

description
string <= 1000 characters

Description of the conversation

Array of objects

The recipients of the conversation. When provided, this list replaces all existing participants. Any participants not in this list will be removed, and any new participants will be added.

Responses

Request samples

Content type
application/json
Example
{
  • "title": "Updated Conversation Title"
}

Response samples

Content type
application/json
{
  • "message": "Conversation updated successfully",
  • "success": true,
  • "data": {
    }
}

Delete Conversations

The “Delete Conversation” endpoint allows you to remove an existing conversation from the system, but only if it was originally created via the API. This restriction ensures that system-generated or manually created conversations outside of the API remain protected from unintended deletion.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

ID of the conversation to delete

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Responses

Response samples

Content type
application/json
{
  • "message": "Conversation has been deleted.",
  • "success": true,
  • "data": {
    }
}

Create Messages

The “Create Messages” endpoint allows you to post a new message to an existing conversation, enabling continued communication within the same thread. This is useful for updating participants, responding to previous messages, or adding context to an ongoing alert, task, or named conversation.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

ID of the conversation to send message to

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema:
required
title
string

Title of the message

message_type
string

Free-form category of the message, echoed back on the created message. Common values seen in the examples below: notification, alert, integration, task, info.

integration_message
boolean
Default: false

Whether this is an integration message with action buttons

object

A single document attachment to include on the message. Supply the file bytes either way — via a multipart/form-data request (preferred; see that content type below), or inline as base64 in this application/json field. The API uploads the file to Alertive's attachment storage on your behalf and attaches the resulting URL when the message is sent. Only supported on plain messages — cannot be combined with integration_message: true.

Accepted MIME types: application/pdf, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), plain text, RTF, and Apple Pages/Numbers/Keynote. Legacy Office formats (.doc, .xls, .ppt) are not supported. This API enforces a maximum of 4 MB (decoded size for application/json/base64 requests, file size for multipart/form-data).

required
object

Responses

Request samples

Content type
Example
{
  • "title": "System Notification",
  • "message_type": "notification",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "message": "",
  • "success": true,
  • "data": {
    }
}

Add Participants

The "Add Participants" endpoint allows you to add one or more participants to an existing conversation. The conversation must have been created via the API. If any participant already exists in the conversation, the operation will fail with a 409 Conflict error.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

ID of the conversation to add participants to

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema: application/json
required
required
Array of objects

Array of participants to add to the conversation

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Participants added successfully",
  • "success": true,
  • "data": {
    }
}

Remove Participants

The "Remove Participants" endpoint allows you to remove one or more participants from an existing conversation. The conversation must have been created via the API. If any participant does not exist in the conversation, the operation will fail with a 404 Not Found error.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

ID of the conversation to remove participants from

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema: application/json
required
required
Array of objects

Array of participants to remove from the conversation. Only type and identifier/aid are required.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Participants removed successfully",
  • "success": true,
  • "data": {
    }
}

Modify Participants

The "Modify Participants" endpoint allows you to change the affiliation (role) of one or more participants in an existing conversation. The conversation must have been created via the API. If any participant does not exist in the conversation, the operation will fail with a 404 Not Found error. If a participant already has the target affiliation, the operation will fail with a 409 Conflict error.

Authorizations:
OAuth2
path Parameters
conversationId
required
string

ID of the conversation to modify participants in

header Parameters
x-org-id
required
string

The organisation ID of the Alertive system you want to interface with

Request Body schema: application/json
required
required
Array of objects

Array of participants to modify in the conversation. The affiliation field specifies the new affiliation.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Participants modified successfully",
  • "success": true,
  • "data": {
    }
}