API Reference

Contacts API

Manage site contacts and emergency contact information

Overview

The Contacts API allows you to manage contacts associated with customer sites. Contacts are individuals who can be reached in case of alarm events or emergency situations.

Contact Purpose

Contacts are used for alarm verification, emergency notifications, and site access coordination.

Endpoints

Create a Contact

Add a new contact to a specific site.

Endpoint: POST /partner/v1/dealers/{dealerId}/sites/{siteId}/contacts

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

Headers:

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

Body:

{
  "external_contact_id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "1234567890",
  "email": "john.doe@example.com"
}

Parameters:

  • external_contact_id (string, required): Unique identifier from your system
  • first_name (string, required): Contact's first name
  • last_name (string, required): Contact's last name
  • phone_number (string, optional): Contact's phone number
  • email (string, optional): Contact's email address

Response (201 Created)

{
  "contact_id": 1,
  "external_contact_id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "1234567890",
  "email": "john.doe@example.com",
  "created_at": "2021-07-01T00:00:00.000Z"
}

Response Fields:

  • contact_id (number): Unique identifier assigned by CHeKT
  • external_contact_id (string): Your system's identifier
  • first_name (string): Contact's first name
  • last_name (string): Contact's last name
  • phone_number (string): Contact's phone number
  • email (string): Contact's email address
  • created_at (string): Creation timestamp (ISO format)

List All Contacts

Retrieve all contacts for a specific site.

Endpoint: GET /partner/v1/dealers/{dealerId}/sites/{siteId}/contacts

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

Headers:

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

Response (200 OK)

[
  {
    "contact_id": 1,
    "external_contact_id": "1234",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "1234567890",
    "email": "john.doe@example.com",
    "created_at": "2021-07-01T00:00:00.000Z"
  }
]

Get a Specific Contact

Retrieve detailed information about a single contact.

Endpoint: GET /partner/v1/dealers/{dealerId}/sites/{siteId}/contacts/{contactId}

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
  • contactId (string, required): The contact ID from CHeKT

Headers:

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

Response (200 OK)

{
  "contact_id": 1,
  "external_contact_id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "1234567890",
  "email": "john.doe@example.com",
  "created_at": "2021-07-01T00:00:00.000Z"
}

Update a Contact

Update contact information such as name, phone, or email.

Endpoint: PUT /partner/v1/dealers/{dealerId}/sites/{siteId}/contacts/{contactId}

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
  • contactId (string, required): The contact ID from CHeKT

Headers:

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

Body:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "phone_number": "9876543210",
  "email": "jane.smith@example.com"
}

Parameters: (All optional)

  • first_name (string): Updated first name
  • last_name (string): Updated last name
  • phone_number (string): Updated phone number
  • email (string): Updated email address

Response (200 OK)

{
  "contact_id": 1,
  "external_contact_id": "1234",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone_number": "9876543210",
  "email": "jane.smith@example.com",
  "created_at": "2021-07-01T00:00:00.000Z"
}

Delete a Contact

Permanently remove a contact from a site.

Endpoint: DELETE /partner/v1/dealers/{dealerId}/sites/{siteId}/contacts/{contactId}

Authentication: OAuth 2.0 Client Credentials Grant

Deleting a contact will remove them from alarm verification and notification lists. Ensure alternative contacts are available.

Request

Path Parameters:

  • dealerId (string, required): The dealer ID from CHeKT
  • siteId (string, required): The site ID from CHeKT
  • contactId (string, required): The contact ID from CHeKT

Headers:

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

Response (204 No Content)

No response body. HTTP status 204 indicates successful deletion.

Error Responses

Status CodeDescriptionSolution
400Bad Request - Invalid input or parametersCheck your request payload format
401Unauthorized - Invalid or expired tokenRefresh your access token
403Forbidden - Access deniedVerify your permissions
404Not Found - Contact, site, or dealer does not existCheck the IDs

Code Examples

cURL

# Create a contact
curl -X POST https://api.chekt.com/partner/v1/dealers/12345/sites/1/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000" \
  -d '{
    "external_contact_id": "1234",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "1234567890",
    "email": "john.doe@example.com"
  }'

# Get all contacts
curl -X GET https://api.chekt.com/partner/v1/dealers/12345/sites/1/contacts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-partner-trace-id: 550e8400-e29b-41d4-a716-123456789000"

JavaScript

// Create a contact
const response = await fetch("https://api.chekt.com/partner/v1/dealers/12345/sites/1/contacts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
  },
  body: JSON.stringify({
    external_contact_id: "1234",
    first_name: "John",
    last_name: "Doe",
    phone_number: "1234567890",
    email: "john.doe@example.com"
  })
});

const contact = await response.json();
console.log("Created contact:", contact);

Python

import requests

# Create a contact
response = requests.post(
    "https://api.chekt.com/partner/v1/dealers/12345/sites/1/contacts",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "x-partner-trace-id": "550e8400-e29b-41d4-a716-123456789000"
    },
    json={
        "external_contact_id": "1234",
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "1234567890",
        "email": "john.doe@example.com"
    }
)

contact = response.json()
print("Created contact:", contact)

Best Practices

  • Validate phone numbers before submission
  • Ensure at least one contact per site for emergency response
  • Keep contact information up to date
  • Store contact_id for alarm verification workflows
  • Test contact reachability after creation

Next Steps

Next Steps