Verifications API

Send alarm verification messages to site contacts to confirm or cancel alarm events.

Endpoints Overview

Send Event Verification

Send an alarm verification message for a specific event to site contacts.

Endpoint

POST /ext/v1/events/{event_id}/verifications

Request Body

{
  "contacts": ["contact_123", "contact_456"],
  "method": "sms",
  "message": "Alarm triggered at your property. Reply YES to confirm or NO to cancel.",
  "timeout_seconds": 300
}

Request Fields

Request Example

curl -X POST "https://api.chektdev.com/ext/v1/events/event_789/verifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": ["contact_123"],
    "method": "sms",
    "timeout_seconds": 180
  }'

Response (200 OK)

{
  "data": {
    "verification_id": "ver_abc123",
    "event_id": "event_789",
    "status": "sent",
    "method": "sms",
    "sent_to": [
      {
        "contact_id": "contact_123",
        "name": "John Doe",
        "phone": "+1-555-0123",
        "status": "delivered"
      }
    ],
    "timeout_at": "2025-01-15T10:35:00Z",
    "sent_at": "2025-01-15T10:30:00Z"
  }
}

Send General Verification

Send a verification message not tied to a specific event.

Endpoint

POST /ext/v1/verifications

Request Body

{
  "site_id": "site_123abc",
  "contacts": ["contact_123"],
  "method": "sms",
  "subject": "Security System Alert",
  "message": "Please verify your contact information for emergency notifications.",
  "require_response": false
}

Request Example

curl -X POST "https://api.chektdev.com/ext/v1/verifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_123abc",
    "contacts": ["contact_123"],
    "method": "email",
    "subject": "Contact Verification",
    "message": "Please confirm your email address."
  }'

Response (200 OK)

{
  "data": {
    "verification_id": "ver_def456",
    "site_id": "site_123abc",
    "status": "sent",
    "method": "email",
    "sent_to": [
      {
        "contact_id": "contact_123",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "status": "delivered"
      }
    ],
    "sent_at": "2025-01-15T10:30:00Z"
  }
}

Verification Methods

Verification Status

Response Handling

Contact Responses

When contacts respond to verifications:

SMS Responses:

• YES or CONFIRM - Confirms the alarm
• NO or CANCEL - Cancels the alarm
• HELP - Request assistance

Email Responses:

• Click confirmation link in email
• Reply with YES/NO

Push Notifications:

• Tap confirm or cancel buttons in notification

Webhook Notifications

Subscribe to verification events:

{
  "event_type": "verification.responded",
  "data": {
    "verification_id": "ver_abc123",
    "event_id": "event_789",
    "contact_id": "contact_123",
    "response": "confirmed",
    "responded_at": "2025-01-15T10:32:00Z"
  }
}

Best Practices

Contact Selection

• Primary Contacts First: Send to primary contacts before secondary
• Multiple Methods: Use multiple contact methods for critical alerts
• Time-Based: Consider time of day when selecting contacts

Message Content

• Clear Instructions: Include clear YES/NO response instructions
• Urgency: Indicate alarm severity and urgency
• Site Information: Include site name/address for context
• Timeout Notice: Mention response timeout if applicable

Timeout Configuration

• High Priority: 180 seconds (3 minutes)
• Medium Priority: 300 seconds (5 minutes)
• Low Priority: 600 seconds (10 minutes)

Use Cases

Alarm Verification

When an alarm triggers, send verification to contacts:

{
  "contacts": ["contact_primary", "contact_emergency"],
  "method": "sms",
  "message": "ALARM: Motion detected at Main Office. Reply YES to confirm or NO for false alarm.",
  "timeout_seconds": 180
}

Contact Information Verification

Periodically verify contact information is current:

{
  "contacts": ["all"],
  "method": "email",
  "subject": "Annual Contact Verification",
  "message": "Please confirm your contact information is up to date."
}

Test Notifications

Test emergency contact system:

{
  "contacts": ["contact_123"],
  "method": "sms",
  "message": "This is a TEST of the emergency notification system. No response required."
}

Error Responses

Invalid Contact

{
  "error": {
    "code": "INVALID_CONTACT",
    "message": "One or more contact IDs are invalid",
    "details": {
      "invalid_contacts": ["contact_999"]
    }
  }
}

Delivery Failed

{
  "error": {
    "code": "DELIVERY_FAILED",
    "message": "Failed to deliver verification message",
    "details": {
      "reason": "Invalid phone number",
      "contact_id": "contact_123"
    }
  }
}

Next Steps

• Contacts API - Manage site contacts
• Webhook Events - Verification event notifications
• Arming API - Monitor alarm events