Public API v1

Base URL: https://api.callonalarm.io

The CallOnAlarm Public API allows developers to trigger phone alerts programmatically from any device or application (IoT sensors, home automation systems, custom scripts, etc.).

---

Quick Start

Trigger an alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "eventCode": "BA"
  }'

---

Authentication

All API requests to /v1/* endpoints require authentication via an API Key.

Obtaining an API Key

Generate your API Key from the CallOnAlarm dashboard under Settings → API Keys.

Using the API Key

Include your API Key in the Authorization header using the Bearer scheme:

Authorization: Bearer coa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example

Test connection (curl)

curl https://api.callonalarm.io/v1/connection/test \
  -H "Authorization: Bearer coa_live_76977174759233a326e682867bcf536f769d17cd"

Response (200 OK):

{
  "success": true,
  "message": "Connection successful",
  "apiKey": {
    "isInternal": false,
    "clientId": "c4c8d755-a538-49b1-b1d9-d2e5433529fc",
    "type": "external"
  },
  "timestamp": "2026-01-30T12:22:39.372Z"
}

---

Endpoints

---

Test Connection

Verify your API Key is valid.

GET /v1/connection/test

Authentication: Required

Response (200 OK):

{
  "success": true,
  "message": "Connection successful",
  "apiKey": {
    "clientId": "c4c8d755-a538-49b1-b1d9-d2e5433529fc",
  },
  "timestamp": "2026-01-30T12:22:39.372Z"
}

---

Trigger Alert

Trigger an alert for a connection.

POST /v1/alert/trigger

Authentication: Required

Request Body:

Field	Type	Required	Description
accountNumber	string	Yes	Your connection's account number
eventCode	string	Yes	SIA or Custom event code (see Event Codes section below or Custom Codes Mapping)
message	string	No	Custom log/voice message (overrides default)
zone	string	No	Zone identifier (e.g., "3", "Front Door")

Example - Basic Alert:

Basic alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "73687044",
    "eventCode": "BA"
  }'

Example - Alert with Custom Message:

Custom message alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "73687044",
    "eventCode": "BA",
    "zone": "3",
    "message": "Intrusion detected in the garage"
  }'

Response (201 Created):

{
  "success": true,
  "alertId": "01b83b2b-79bb-492e-8405-9178562f750f",
  "requiresCalls": true,
  "contactsToCall": 2,
  "language": "en",
  "delaySeconds": 30,
  "status": "call_delayed",
  "technicalEmailSent": false
}

Response Fields:

Field	Description
alertId	Unique identifier for tracking the alert
requiresCalls	Whether phone calls will be made
contactsToCall	Number of contacts that will be called
language	Language for the voice message (see note below)
delaySeconds	Delay before calls start (if delay rule configured)
status	Alert status (see Status Values below)
technicalEmailSent	Whether a technical notification was sent

Important: The language field reflects the language configured in your account settings (set during registration). The voice message will be spoken in this language. Supported languages: en (English), fr (French), es (Spanish), it (Italian), de (German). To change your language preference, update it in Dashboard → Settings → Account.

Status Values:

Status	Description
call_immediate	Calls starting immediately
call_delayed	Calls will start after delay period
ignored	Event filtered by rules (no action)
technical_only	Only technical email sent (no calls)
logged_inactive	Event logged but connection is inactive

---

Get Alert Status

Retrieve the current status of an alert.

GET /v1/alert/:id/status

Authentication: Required

Example:

Get alert status (curl)

curl https://api.callonalarm.io/v1/alert/01b83b2b-79bb-492e-8405-9178562f750f/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK) - Acknowledged Alert:

{
  "id": "bada7819-eb12-41d9-a363-0b8f662c80a1",
  "status": "acknowledged",
  "eventType": "BA",
  "acknowledged": true,
  "acknowledgedAt": "2026-01-30T12:41:35.942Z",
  "acknowledgedBy": "Sarah",
  "acknowledgedByPhone": "[phone]",
  "receivedAt": "2026-01-30T12:40:46.637Z",
  "cancelledWhen": null,
  "totalCallsMade": 1,
  "creditsConsumed": 2
}

Response (200 OK) - Cancelled Alert:

{
  "id": "01b83b2b-79bb-492e-8405-9178562f750f",
  "status": "cancelled_by_disarm",
  "eventType": "BA",
  "acknowledged": false,
  "acknowledgedAt": null,
  "acknowledgedBy": null,
  "acknowledgedByPhone": null,
  "receivedAt": "2026-01-30T12:37:53.653Z",
  "cancelledWhen": "before_first_call",
  "totalCallsMade": 0,
  "creditsConsumed": 0
}

---

Acknowledge Alert

Manually acknowledge an alert via API.

POST /v1/alert/:id/acknowledge

Authentication: Required

Request Body:

Field	Type	Required	Description
phoneNumber	string	Yes	Phone number acknowledging the alert

Example:

Acknowledge alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/01b83b2b-79bb-492e-8405-9178562f750f/acknowledge \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "[phone]"
  }'

Response (200 OK):

{
  "success": true,
  "message": "Alert acknowledged successfully"
}

---

Rate Limiting

API requests are rate limited to protect the service.

Limit	Value
Requests per hour	100
Window	1 hour (sliding)

Rate limit information is included in response headers:

RateLimit-Limit: 100
RateLimit-Remaining: 89
RateLimit-Reset: 2956
RateLimit-Policy: 100;w=3600

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 100 requests per hour.",
  "retryAfter": "1 hour"
}

---

Error Codes

HTTP Code	Error	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing, invalid, or expired API Key
404	Not Found	Resource not found (connection, alert)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

{
  "error": "Error Type",
  "message": "Human-readable description"
}

Common Errors

Missing API Key:

{
  "error": "Unauthorized",
  "message": "API Key required",
  "hint": "Provide API Key in Authorization header: \"Bearer YOUR_API_KEY\""
}

Invalid API Key:

{
  "error": "Unauthorized",
  "message": "Invalid API Key"
}

Missing Required Fields:

{
  "error": "Bad Request",
  "message": "accountNumber and eventCode are required"
}

Connection Not Found:

{
  "error": "Not Found",
  "message": "Connection not found for this account number"
}

Alert Not Found:

{
  "error": "Not Found",
  "message": "Alert not found"
}

Alert Already Acknowledged:

{
  "error": "Bad Request",
  "message": "Alert already acknowledged",
  "acknowledgedAt": "2026-01-30T12:41:35.942Z"
}

---

Use Case: Custom IT Monitoring Alert

This example shows how a developer can trigger a custom alert for IT infrastructure monitoring, such as a server going down.

Scenario: You want to be notified by phone when your server in rack B34E goes offline.

1

Choose an appropriate event code

For IT/equipment failures, use one of these codes or create custom ones:

Code	Description	Recommended for
IA	Equipment Fail Condition	Server down, hardware failure
YP	Power Supply Trouble	UPS/power issues
NT	Network Failure	Network connectivity loss
YC	Communications Fail	Communication system failure

2

Configure notification rules (Dashboard)

Before triggering alerts, configure how you want to be notified:

• Go to Dashboard → Delay Rules

• Select the event code you'll use (e.g., IA)

• Choose your notification preference:

  • ☑️ Call — Immediate phone call

  • ☑️ Delayed Call — Phone call after a delay (allows auto-recovery)

  • ☑️ Technical — Email notification only

Note: To receive technical emails, configure the email address in Dashboard → Connections → [Your Connection] → Advanced Settings → Technical Email.

3

Trigger the alert

Trigger IT alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "eventCode": "IA",
    "zone": "B34E",
    "message": "Server down in rack B34E - immediate attention required"
  }'

4

Cancel if auto-recovery (optional)

If your monitoring detects the server is back online, send the restore code to cancel pending calls:

Send restore (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "eventCode": "IR",
    "zone": "B34E",
    "message": "Server restored in rack B34E"
  }'

Example Response:

{
  "success": true,
  "alertId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "requiresCalls": true,
  "contactsToCall": 2,
  "language": "en",
  "delaySeconds": 60,
  "status": "call_delayed",
  "technicalEmailSent": true
}

• A technical email was sent immediately (technicalEmailSent: true)

• Phone calls will start in 60 seconds (delaySeconds: 60)

• If the server recovers and you send a restore code (IR) within 60 seconds, calls are cancelled

---

Use Case: Crypto Wallet Price Alert

This example shows how a developer can receive an immediate phone call when their crypto portfolio reaches a critical threshold.

Scenario: You want to be called immediately when:

• Your wallet drops below $10,000 (stop-loss alert)

• Your wallet exceeds $50,000 (take-profit alert)

1

Choose an event code

For custom financial alerts, use:

Code	Description	Recommended for
UA	Untyped Zone Alarm	Generic custom alerts
QA	Emergency Alarm	Critical financial alerts

2

Configure for immediate calls (Dashboard)

Since crypto markets move fast, configure immediate calls with no delay:

• Go to Dashboard → Delay Rules

• Select the event code UA (or QA)

• Configure:

  • ☑️ Call — Immediate phone call (no delay)

  • ☐ Delayed Call — Leave unchecked for instant notification

3

Create your monitoring script

Example script that checks wallet value and triggers alerts:

crypto-monitor.sh

#!/bin/bash
# crypto-monitor.sh - Check wallet value and trigger alert

WALLET_VALUE=$(curl -s "https://api.your-crypto-tracker.com/wallet/value")
LOW_THRESHOLD=10000
HIGH_THRESHOLD=50000

API_KEY="YOUR_API_KEY"
ACCOUNT="YOUR_ACCOUNT_NUMBER"

# Check low threshold (stop-loss)
if (( $(echo "$WALLET_VALUE < $LOW_THRESHOLD" | bc -l) )); then
  curl -X POST https://api.callonalarm.io/v1/alert/trigger \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"accountNumber\": \"$ACCOUNT\",
      \"eventCode\": \"UA\",
      \"zone\": \"STOP-LOSS\",
      \"message\": \"Alert! Your crypto wallet has dropped below $LOW_THRESHOLD dollars. Current value: $WALLET_VALUE dollars. Take action now.\"
    }"
fi

# Check high threshold (take-profit)
if (( $(echo "$WALLET_VALUE > $HIGH_THRESHOLD" | bc -l) )); then
  curl -X POST https://api.callonalarm.io/v1/alert/trigger \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"accountNumber\": \"$ACCOUNT\",
      \"eventCode\": \"UA\",
      \"zone\": \"TAKE-PROFIT\",
      \"message\": \"Congratulations! Your crypto wallet has exceeded $HIGH_THRESHOLD dollars. Current value: $WALLET_VALUE dollars. Consider taking profits.\"
    }"
fi

4

Trigger alerts via API (examples)

Stop-Loss Alert (wallet dropped to $9,500):

Stop-loss alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "eventCode": "UA",
    "zone": "STOP-LOSS",
    "message": "Alert! Your crypto wallet has dropped below 10000 dollars. Current value: 9500 dollars. Take action now."
  }'

Take-Profit Alert (wallet reached $52,000):

Take-profit alert (curl)

curl -X POST https://api.callonalarm.io/v1/alert/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "eventCode": "UA",
    "zone": "TAKE-PROFIT",
    "message": "Congratulations! Your crypto wallet has exceeded 50000 dollars. Current value: 52000 dollars. Consider taking profits."
  }'

Example Response:

{
  "success": true,
  "alertId": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "requiresCalls": true,
  "contactsToCall": 2,
  "language": "en",
  "delaySeconds": null,
  "status": "call_immediate",
  "technicalEmailSent": false
}

Tips for crypto monitoring:

1. Use the zone field to differentiate alert types (STOP-LOSS, TAKE-PROFIT, LIQUIDATION, etc.)

2. Include the current value in the message so you know the exact amount when called

3. Add rate limiting in your script to avoid multiple calls for the same threshold

4. Consider time-based rules — you might want delayed calls during sleeping hours

---

Event Codes Reference

The eventCode field uses standard SIA (Security Industry Association) codes (DC-05-1999.09).

(Sections below list event codes by category.)

Critical Alarms

Fire Alarms

Code	Description
FA	Fire Alarm
FB	Fire Bypass
FC	Fire Cancel
FH	Fire Alarm Restore
FI	Fire Test Begin
FJ	Fire Trouble Restore
FK	Fire Test End
FM	Fire Alarm Cross Point
FR	Fire Restoral
FS	Fire Supervisory
FT	Fire Trouble
FU	Fire Unbypass
FX	Fire Test
FY	Missing Fire Trouble
FZ	Missing Fire Supervisory

Panic Alarms

Code	Description
PA	Panic Alarm
PB	Panic Bypass
PH	Panic Alarm Restore
PJ	Panic Trouble Restore
PR	Panic Restoral
PS	Panic Supervisory
PT	Panic Trouble
PU	Panic Unbypass

Holdup Alarms

Code	Description
HA	Holdup Alarm
HB	Holdup Bypass
HH	Holdup Alarm Restore
HJ	Holdup Trouble Restore
HR	Holdup Restoral
HS	Holdup Supervisory
HT	Holdup Trouble
HU	Holdup Unbypass

Emergency Alarms

Code	Description
QA	Emergency Alarm
QB	Emergency Bypass
QH	Emergency Alarm Restore
QJ	Emergency Trouble Restore
QR	Emergency Restoral
QS	Emergency Supervisory
QT	Emergency Trouble
QU	Emergency Unbypass

Medical Alarms

Code	Description
MA	Medical Alarm
MB	Medical Bypass
MH	Medical Alarm Restore
MJ	Medical Trouble Restore
MR	Medical Restoral
MS	Medical Supervisory
MT	Medical Trouble
MU	Medical Unbypass

Burglary/Intrusion Alarms

Code	Description
BA	Burglary Alarm
BB	Burglary Bypass
BC	Burglary Cancel
BD	Swinger Trouble
BE	Swinger Trouble Restore
BH	Burglary Alarm Restore
BJ	Burglary Trouble Restore
BM	Burglary Alarm Cross Point
BR	Burglary Restoral
BS	Burglary Supervisory
BT	Burglary Trouble
BU	Burglary Unbypass
BV	Burglary Verified
BX	Burglary Test
BZ	Missing Supervision

Environmental Alarms

Gas Alarms

Code	Description
GA	Gas Alarm
GB	Gas Bypass
GH	Gas Alarm Restore
GJ	Gas Trouble Restore
GR	Gas Restoral
GS	Gas Supervisory
GT	Gas Trouble
GU	Gas Unbypass
GX	Gas Test

Heat Alarms

Code	Description
KA	Heat Alarm
KB	Heat Bypass
KH	Heat Alarm Restore
KJ	Heat Trouble Restore
KR	Heat Restoral
KS	Heat Supervisory
KT	Heat Trouble
KU	Heat Unbypass

Water Alarms

Code	Description
WA	Water Alarm
WB	Water Bypass
WH	Water Alarm Restore
WJ	Water Trouble Restore
WR	Water Restoral
WS	Water Supervisory
WT	Water Trouble
WU	Water Unbypass

Freeze Alarms

Code	Description
ZA	Freeze Alarm
ZB	Freeze Bypass
ZH	Freeze Alarm Restore
ZJ	Freeze Trouble Restore
ZR	Freeze Restoral
ZS	Freeze Supervisory
ZT	Freeze Trouble
ZU	Freeze Unbypass

Sprinkler Alarms

Code	Description
SA	Sprinkler Alarm
SB	Sprinkler Bypass
SH	Sprinkler Alarm Restore
SJ	Sprinkler Trouble Restore
SR	Sprinkler Restoral
SS	Sprinkler Supervisory
ST	Sprinkler Trouble
SU	Sprinkler Unbypass

Security Events

Tamper Events

Code	Description
TA	Tamper Alarm
TB	Tamper Bypass
TC	All Points Tested
TE	Test End
TH	Tamper Alarm Restore
TJ	Tamper Trouble Restore
TP	Walk Test Point
TR	Tamper Restoral
TS	Test Start
TT	Tamper Trouble
TU	Tamper Unbypass
TX	Test Report

Untyped Zone Events

Code	Description
UA	Untyped Zone Alarm
UB	Untyped Zone Bypass
UH	Untyped Alarm Restore
UJ	Untyped Trouble Restore
UR	Untyped Zone Restore
US	Untyped Zone Supervisory
UT	Untyped Zone Trouble
UU	Untyped Zone Unbypass
UX	Undefined Alarm
UY	Untyped Missing Trouble
UZ	Untyped Missing Alarm

Access Control & Arm/Disarm

Opening/Closing (Arm/Disarm)

Code	Description
OP	Opening Report (Disarmed)
CL	Closing Report (Armed)
OA	Automatic Opening
CA	Automatic Closing
CD	Closing Delinquent
CE	Closing Extend
CF	Forced Closing
CG	Close Area
CI	Fail to Close
CJ	Late Close
CK	Early Close
CM	Missing Alarm - Recent Close
CP	Automatic Closing
CR	Recent Closing
CS	Close Key Switch
CT	Late to Open
CW	Was Force Armed
CZ	Point Closing
OC	Cancel Report
OG	Open Area
OH	Early to Open from Alarm
OI	Fail to Open
OJ	Late Open
OK	Early Open
OL	Late to Open from Alarm
OR	Disarm from Alarm
OS	Open Key Switch
OT	Late to Close
OZ	Point Opening

Door & Access Control

Code	Description
DA	Card Assigned
DB	Card Deleted
DC	Access Closed
DD	Access Denied
DE	Request to Enter
DF	Door Forced
DG	Access Granted
DH	Door Left Open - Restoral
DJ	Door Forced - Trouble
DK	Access Lockout
DL	Door Left Open - Alarm
DM	Door Left Open - Trouble
DN	Door Left Open
DO	Access Open
DP	Access Denied - Bad Time
DQ	Access Denied - Unarmed
DR	Door Restoral
DS	Door Station
DT	Access Trouble
DU	Dealer ID
DV	Access Denied - Unauthorized Entry
DW	Access Denied - Interlock
DX	Request to Exit
DY	Door Locked
DZ	Access Closed State

Perimeter & Area

Code	Description
NF	Forced Perimeter Arm
NL	Perimeter Armed

System Status & Power

Power Supply

Code	Description
AN	Analog Restoral
AR	AC Restoral
AS	Analog Service
AT	AC Trouble

Local Programming & Phone Line

Code	Description
LB	Local Programming Begin
LD	Local Programming Denied
LE	Listen In Ended
LF	Listen In Begin
LR	Phone Line Restoral
LS	Local Programming Success
LT	Phone Line Trouble
LU	Local Programming Fail
LX	Local Programming Ended

System Status

Code	Description
YA	Bell Fault
YB	Busy Seconds
YC	Communications Fail
YD	Receiver Linecard Trouble
YE	Receiver Linecard Restore
YF	Parameter Checksum Fail
YG	Parameter Changed
YH	Bell Restored
YI	Overcurrent Trouble
YJ	Overcurrent Restore
YK	Communication Restoral
YM	System Battery Missing
YN	Invalid Report
YO	Unknown Message
YP	Power Supply Trouble
YQ	Power Supply Restore
YR	System Battery Restoral
YS	Communications Trouble
YT	System Battery Trouble
YW	Watchdog Reset
YX	Service Required
YY	Status Report
YZ	Service Completed

Communications & Network

Network Status

Code	Description
NA	No Activity
NC	Network Condition
NR	Network Restoral
NS	Activity Resumed
NT	Network Failure

RF & Wireless

Code	Description
XA	Extra Account Report
XE	Extra Point
XF	Extra RF Point
XH	RF Interference Restore
XI	Sensor Reset
XJ	RF Receiver Tamper Restore
XL	Low RF Signal
XM	Missing Alarm - Extra Point
XQ	RF Interference
XR	Transmitter Battery Restoral
XS	RF Receiver Tamper
XT	Transmitter Battery Trouble
XW	Forced Point
XX	Fail to Test

User & Configuration

User Codes & Access

Code	Description
JA	User Code Tamper
JD	Date Changed
JH	Holiday Changed
JK	Latchkey Alert
JL	Log Threshold
JO	Log Overflow
JP	User On Premises
JR	Schedule Executed
JS	Schedule Changed
JT	Time Changed
JV	User Code Changed
JX	User Code Deleted
JY	User Code Added
JZ	User Level Set

Testing & Diagnostics

Test Reports

Code	Description
RP	Automatic Test
RR	Restore Power
RS	Remote Programming Success
RT	Data Lost
RU	Remote Programming Fail
RX	Manual Test
RY	Test Off Normal

Equipment Status

Code	Description
EA	Exit Alarm
EE	Exit Error
ER	Expansion Restoral
ET	Expansion Trouble
EX	External Device State
EZ	Missing Alarm - External Error
IA	Equipment Fail Condition
IR	Equipment Fail Restore

Remote Programming & Control

Code	Description
RA	Remote Programming Call Fail
RB	Remote Programming Begin
RC	Relay Close
RD	Remote Programming Denied
RN	Remote Reset
RO	Relay Open

Printer Status

Code	Description
VI	Printer Paper In
VO	Printer Paper Out
VR	Printer Restore
VT	Printer Trouble
VX	Printer Test
VY	Printer Online
VZ	Printer Offline

---

Changelog

v1.0.0 (2026-01-30)

• Initial release

• Endpoints: /v1/alert/trigger, /v1/alert/:id/status, /v1/alert/:id/acknowledge, /v1/connection/test

• Authentication via API Key

• Rate limiting (100 requests/hour)