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/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: 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

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)

priority_label
string

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

priority_colour
string

Color code for the priority level (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

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^[A-Za-z0-9_-]+$

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

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. 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 ("").

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

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

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

required
Array of objects

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

Whether webhooks are enabled for this conversation

webhook_id
string

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
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": [
    ],
  • "alert": {
    },
  • "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
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

Title/subject of the conversation

description
string

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": "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": {
    }
}

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": {
    }
}