Alertive
API docs by Redocly

Alertive API

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/json 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: application/json
required
name
string

Name of the conversation

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

Type of conversation to create

title
required
string

Title/subject of the conversation

description
required
string

Description of the conversation

type
string

Priority type for the conversation

priority_label
string

Label for the priority level

priority_colour
string

Color code for the priority level

colour
string

Color code for the conversation

ios_icon
string

Icon identifier for iOS devices

android_icon
string

Icon identifier for Android devices

sound_file_id
string

Identifier for the notification sound

is_critical
boolean

Whether the conversation is critical or not

chat_available
boolean

Whether chat functionality is available

expiry_ttl
integer
Default: 3600

Time-to-live in seconds for conversation expiry

activity_ttl
integer
Default: 86400

Time-to-live in seconds for conversation activity

Array of objects

Available response options for alerts

participant_can_leave
boolean

Whether participants can leave the conversation

owner_can_close_early
boolean

Whether the owner can close the conversation early

owner_can_add_additional_contacts
boolean

Whether the owner can add additional contacts

can_send_attachments_within_conversation
boolean

Whether attachments can be sent within the conversation

object

Alert-specific configuration

required
Array of objects

The recipients of the conversation

object

Optional patient information related to the conversation

Responses

Request samples

Content type
application/json
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": [
    ],
  • "patient_data": {
    }
}

Response samples

Content type
application/json
{
  • "message": "",
  • "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
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": "string",
  • "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
query Parameters
conversation_id
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": "string",
  • "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: application/json
required
title
string

Title of the message

integration_message
boolean
Default: false

Whether this is an integration message with action buttons

required
object

Responses

Request samples

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

Response samples

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