Contacts API

Manage contacts for each site including creation, updates, deletion, and validation.

Endpoints Overview

Create a Contact

Add a new contact to a site.

Endpoint

POST /ext/v1/sites/{site_id}/contacts

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-0123",
  "type": "primary",
  "role": "owner",
  "notification_preferences": {
    "email": true,
    "sms": true,
    "push": false
  }
}

Request Example

curl -X POST "https://api.chektdev.com/ext/v1/sites/site_123abc/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0123",
    "type": "primary"
  }'

Response (201 Created)

{
  "data": {
    "contact_id": "contact_789ghi",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0123",
    "type": "primary",
    "role": "owner",
    "notification_preferences": {
      "email": true,
      "sms": true,
      "push": false
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Get All Contacts

Retrieve all contacts for a site.

Endpoint

GET /ext/v1/sites/{site_id}/contacts

Request Example

curl -X GET "https://api.chektdev.com/ext/v1/sites/site_123abc/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "data": {
    "contacts": [
      {
        "contact_id": "contact_789ghi",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-0123",
        "type": "primary",
        "role": "owner"
      },
      {
        "contact_id": "contact_abc123",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com",
        "phone": "+1-555-0456",
        "type": "emergency",
        "role": "manager"
      }
    ],
    "total_count": 2
  }
}

Get a Contact

Retrieve details of a specific contact.

Endpoint

GET /ext/v1/sites/{site_id}/contacts/{contact_id}

Response (200 OK)

{
  "data": {
    "contact_id": "contact_789ghi",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0123",
    "type": "primary",
    "role": "owner",
    "notification_preferences": {
      "email": true,
      "sms": true,
      "push": false
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Update a Contact

Update an existing contact's information.

Endpoint

PUT /ext/v1/sites/{site_id}/contacts/{contact_id}

Request Body

{
  "phone": "+1-555-9999",
  "notification_preferences": {
    "email": true,
    "sms": true,
    "push": true
  }
}

Response (200 OK)

{
  "data": {
    "contact_id": "contact_789ghi",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-9999",
    "type": "primary",
    "notification_preferences": {
      "email": true,
      "sms": true,
      "push": true
    },
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Delete a Contact

Remove a contact from a site.

Endpoint

DELETE /ext/v1/sites/{site_id}/contacts/{contact_id}

Request Example

curl -X DELETE "https://api.chektdev.com/ext/v1/sites/site_123abc/contacts/contact_789ghi" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (204 No Content)

No response body. HTTP status 204 indicates successful deletion.

Send Validation

Send a validation message to verify contact information.

Endpoint

POST /ext/v1/sites/{site_id}/contacts/{contact_id}/validation

Request Body

{
  "method": "sms",
  "message": "Please verify your phone number for CHeKT alerts."
}

Response (200 OK)

{
  "data": {
    "validation_id": "val_xyz789",
    "status": "sent",
    "method": "sms",
    "sent_at": "2025-01-15T10:30:00Z"
  }
}

Contact Types

Contact Roles

Alternative Endpoints

Using Reference ID

POST /ref/v1/sites/{account_reference_id}/contacts
GET /ref/v1/sites/{account_reference_id}/contacts
DELETE /ref/v1/sites/{account_reference_id}/contacts/{external_contact_id}

Next Steps

• Arming API - Control site security
• Verifications API - Send alarm verifications
• Sites API - Manage sites