Alarm Verifications API

Overview

The Alarm Verifications API allows you to respond to alarm verification requests from the CHeKT system. When an alarm is triggered, the system may request verification from site contacts before dispatching emergency services.

Verification Actions

Two actions are available for alarm verification:

Endpoints

Update Alarm Verification

Submit a verification response for an alarm.

Endpoint: PATCH /partner/v1/dealers/{dealerId}/sites/{siteId}/alarm-verifications/{verificationId}

Authentication: OAuth 2.0 Client Credentials Grant

Request

Path Parameters:

• dealerId (string, required): The dealer ID from CHeKT
• siteId (string, required): The site ID from CHeKT
• verificationId (number, required): The verification ID from CHeKT alarm notification

Headers:

• Authorization: Bearer {access_token}
• x-partner-trace-id (optional): UUID for request tracking

Body:

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "contact_id": 67890,
  "action": "dispatch",
  "responded_at": "2023-10-01T12:00:00Z"
}

Parameters:

• verification_id (string, required): UUID assigned by CHeKT when alarm verification was created
• contact_id (number, required): CHeKT ID of the contact who responded
• action (string, required): Verification action (dispatch or disregard)
• responded_at (string, required): ISO 8601 timestamp when the action was taken

Response (200 OK)

{
  "id": 1,
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "contact_id": 67890,
  "action": "dispatch",
  "responded_at": "2023-10-01T12:00:00Z"
}

Response Fields:

• id (number): Unique identifier for the alarm verification response
• verification_id (string): UUID of the verification request
• contact_id (number): CHeKT contact ID who responded
• action (string): Verification action taken
• responded_at (string): Timestamp of the response (ISO 8601 format)

Verification Process

How alarm verification works:

1. Alarm Triggered: A device at the site triggers an alarm
2. Verification Created: CHeKT creates a verification request with a unique verification_id
3. Contact Notified: Site contacts receive notification via your system or CHeKT
4. Contact Responds: Contact chooses to dispatch or disregard
5. Response Submitted: Your system calls this API with the contact's decision
6. Action Taken: CHeKT processes the response and takes appropriate action

Error Responses

Code Examples

cURL

# Submit verification response
curl -X PATCH https://api.chekt.com/partner/v1/dealers/12345/sites/1/alarm-verifications/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000" \
  -d '{
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": 67890,
    "action": "dispatch",
    "responded_at": "2023-10-01T12:00:00Z"
  }'

JavaScript

// Submit verification response
const response = await fetch(
  "https://api.chekt.com/partner/v1/dealers/12345/sites/1/alarm-verifications/1",
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${accessToken}`,
      "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
    },
    body: JSON.stringify({
      verification_id: "550e8400-e29b-41d4-a716-446655440000",
      contact_id: 67890,
      action: "dispatch",
      responded_at: new Date().toISOString()
    })
  }
);

const result = await response.json();
console.log("Verification response recorded:", result);

Python

import requests
from datetime import datetime

# Submit verification response
response = requests.patch(
    "https://api.chekt.com/partner/v1/dealers/12345/sites/1/alarm-verifications/1",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
    },
    json={
        "verification_id": "550e8400-e29b-41d4-a716-446655440000",
        "contact_id": 67890,
        "action": "dispatch",
        "responded_at": datetime.utcnow().isoformat() + "Z"
    }
)

result = response.json()
print("Verification response recorded:", result)

Best Practices

• Respond to verification requests within 2 minutes
• Validate contact_id before submission
• Use accurate responded_at timestamps
• Log all verification responses for audit trails
• Implement timeout handling for unresponsive contacts
• Test both dispatch and disregard workflows

Response Time Guidelines

Integration Notes

Receiving Verification Requests

Verification requests are sent to your system via:

• Webhooks: Real-time push notifications (recommended)
• Polling: Periodic checking of verification status

Testing

Test your verification workflow with:

1. Create a test site with test contacts
2. Trigger a test alarm
3. Submit verification responses
4. Verify proper handling in your system

Next Steps