What are Monitorables?

Monitorables are the core entities in the Hyperion platform that you want to monitor for events and alarms. A monitorable represents a person, place, or thing that can generate events requiring monitoring responses.

Each monitorable has a unique identifier (id) assigned by the platform and can also have an optional externalId that you provide to reference the entity in your own systems. This allows you to correlate monitorables with records in your database.

What types of monitorables are available?

The Hyperion platform supports three types of monitorables, each with their own specific fields:

Type	Description	Use Case
`PREMISES`	Physical locations such as homes, businesses, or buildings	Home security, commercial building monitoring
`PERSON`	Individual people to monitor	Personal safety, lone worker monitoring
`VEHICLE`	Vehicles to track and monitor	Vehicle management, stolen vehicle recovery

What data is stored?

Each monitorable type has common fields plus type-specific fields. Premises use premisesType, address, and contacts; persons use person and contacts; vehicles use vehicle and contacts. These fields are returned only by Get Monitorable With Data (GET /monitorables/:id/data), which requires the monitorable:data:read scope. Create, get, list, update, activate, and cancel responses never include them. Each contact can specify communicationMode (how to reach them: VOICE, VIDEO, SMS, or IN_APP_CHAT), contactType, preferredLanguage, order (call escalation priority), picEnabled (whether a personal identification code has been set for that contact), and for person monitorables, relationship (e.g., SPOUSE, PARTNER, MOTHER, FATHER).

Contact type

Set contactType to PRIMARY or EMERGENCY.

PRIMARY is the main contact for the monitorable. Exactly one contact must be PRIMARY. That contact must include emailAddress.
EMERGENCY is an additional contact. emailAddress is optional. If you omit contactType, Hyperion stores EMERGENCY.

order decides who is called first. It is separate from contactType.

These requests are rejected:

No contact is PRIMARY: A primary contact is required for every monitorable
More than one contact is PRIMARY: Only one primary contact is allowed for a monitorable
The PRIMARY contact has no email: Email address is required for a primary contact
An email is present but not a valid address, including "": Email address must be a valid email

An email, when you send one, can be at most 255 characters. Deleting the only PRIMARY contact is rejected with the same "primary contact is required" error. Deleting the last contact on a monitorable is still rejected, even when that contact is PRIMARY.

Common Fields

All monitorables share these base fields:

Field	Description
`id`	Unique identifier assigned by Hyperion
`partnerId`	ID of the partner organization that owns the monitorable
`externalId`	Your external identifier for the monitorable (optional)
`type`	The monitorable type (`PREMISES`, `PERSON`, or `VEHICLE`)
`verificationStatus`	Whether the monitorable has met all compliance requirements (`PENDING_REQUIREMENTS`, `VERIFIED`, `INVALID_ADDRESS`, `FAILED`)
`systemStatus`	Whether the monitorable is active and how events are handled (`INACTIVE`, `ACTIVE`, `FAMILIARIZATION`, `CUSTOMER_TEST`, `CANCELLED`)
`picEnabled`	Whether a personal identification code has been set on the monitorable
`requirements`	Compliance requirements for this monitorable (permits, familiarization, contacts, subscription)
`documents`	Documents generated by the platform for this monitorable (e.g., proof of coverage certificates)
`subscription`	Selected billing plan (`MONTHLY` or `ANNUAL`) when a `SUBSCRIPTION` requirement applies; see Subscriptions
`address` / `person` / `vehicle`, `contacts`	Returned only by `GET /monitorables/:id/data` (requires `monitorable:data:read`); omitted from all other responses and webhooks
`createdAt`	Timestamp when the monitorable was created
`updatedAt`	Timestamp when the monitorable was last updated
`cancelledAt`	Timestamp when the monitorable was cancelled (only present after cancellation)

Premises Fields

Premises monitorables require a premisesType that classifies the protected property. This field is required on create and optional on update.

Value	Description
`RESIDENTIAL`	Residential individual consumer properties or households
`COMMERCIAL_SMB`	Small and medium business commercial properties with total protected space strictly less than 10,000 square feet (`< 10k sq ft`)
`COMMERCIAL_LARGE`	Large commercial, mid-market, or enterprise properties with total protected space greater than or equal to 10,000 square feet (`>= 10k sq ft`)

Premises responses also include:

Field	Description
`customerSupportId`	ADT central station ID for the premises (three alphanumeric characters + seven digits). Optionally passed on create from a prior reservation.
`subscription`	Selected plan (`MONTHLY` or `ANNUAL`) when the partner offers subscriptions. See Subscriptions.

Example GET /monitorables/:id/data response:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-premises-12345",
  "customerSupportId": "A265000001",
  "type": "PREMISES",
  "premisesType": "RESIDENTIAL",
  "verificationStatus": "PENDING_REQUIREMENTS",
  "systemStatus": "INACTIVE",
  "subscription": "MONTHLY",
  "picEnabled": false,
  "requirements": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "type": "PERMIT",
      "status": "INCOMPLETE",
      "stage": "POST_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "eventTypes": ["BURGLARY"],
      "applicationUrl": "https://www.county.gov/permit",
      "fees": [
        {
          "type": "PERMIT_INITIAL",
          "frequency": "PT0S",
          "amount": 50.00,
          "currency": "USD"
        }
      ],
      "renewal": {
        "frequency": "P1Y",
        "responsibleParty": "CUSTOMER",
        "fee": { "amount": 50.00, "currency": "USD", "frequency": "P1Y" }
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "documents": [],
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "New York",
    "state": "US-NY",
    "county": "New York",
    "postalCode": "10001",
    "country": "US",
    "municipalityId": "36061"
  },
  "contacts": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440020",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "VOICE",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "picEnabled": false,
      "order": 1
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Person Fields

Example GET /monitorables/:id/data response:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-person-abc123",
  "type": "PERSON",
  "verificationStatus": "VERIFIED",
  "systemStatus": "INACTIVE",
  "picEnabled": false,
  "requirements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "type": "NUMBER_OF_CONTACTS",
      "status": "COMPLETE",
      "stage": "PRE_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "count": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "documents": [],
  "person": {
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "jane.smith@example.com",
    "phoneNumber": "+15550456789",
    "preferredLanguage": "en-US",
    "communicationMode": "VIDEO"
  },
  "contacts": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440021",
      "firstName": "Bob",
      "lastName": "Smith",
      "phoneNumber": "+15559876543",
      "emailAddress": "bob.smith@example.com",
      "communicationMode": "VOICE",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "relationship": "SPOUSE",
      "picEnabled": false,
      "order": 1
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Vehicle Fields

Example GET /monitorables/:id/data response:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-vehicle-xyz789",
  "type": "VEHICLE",
  "verificationStatus": "VERIFIED",
  "systemStatus": "INACTIVE",
  "picEnabled": false,
  "requirements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "type": "NUMBER_OF_CONTACTS",
      "status": "COMPLETE",
      "stage": "PRE_ACTIVATION",
      "responsibleParty": "CUSTOMER",
      "count": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "documents": [],
  "vehicle": {
    "make": "Toyota",
    "model": "Camry",
    "year": 2023,
    "vin": "1HGBH41JXMN109186"
  },
  "contacts": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440022",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "SMS",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "picEnabled": false,
      "order": 1
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Use Cases

Home Security Monitoring

Create a PREMISES monitorable for each home or business location. Include premisesType, address details, and contacts so monitoring agents can respond appropriately when events occur.

{
  "type": "PREMISES",
  "externalId": "customer-account-12345",
  "premisesType": "RESIDENTIAL",
  "address": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "state": "US-NY",
    "county": "New York",
    "postalCode": "10001",
    "country": "US"
  },
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "VOICE",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "order": 1
    }
  ]
}

Personal Safety

Create a PERSON monitorable for individuals who need safety monitoring, such as lone workers or elderly family members.

{
  "type": "PERSON",
  "externalId": "employee-jane-smith",
  "person": {
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "jane.smith@example.com",
    "phoneNumber": "+15559876543",
    "preferredLanguage": "en-US",
    "communicationMode": "VIDEO"
  },
  "contacts": [
    {
      "firstName": "Bob",
      "lastName": "Smith",
      "phoneNumber": "+15551112222",
      "emailAddress": "bob.smith@example.com",
      "communicationMode": "VOICE",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "relationship": "SPOUSE",
      "order": 1
    }
  ]
}

Vehicle Monitoring

Create a VEHICLE monitorable to track incidents and enable quick response.

{
  "type": "VEHICLE",
  "externalId": "truck-001",
  "vehicle": {
    "make": "Ford",
    "model": "F-150",
    "year": 2024,
    "vin": "1FTFW1E50NFA12345"
  },
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "SMS",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "order": 1
    }
  ]
}

Customer Support ID

Premises monitorables are associated with a customerSupportId (ex. A265000001) used as the ADT central station ID.

Partners with a configured customer support pool can reserve an ID before create by sending a POST request to /monitorables/customer-support-id (requires the monitorable:write scope). The response returns the reserved ID and when the reservation expires:

{
  "id": "A265000001",
  "expiresAt": "2024-01-15T10:45:00Z"
}

The response id is the customer support ID string. Pass it as customerSupportId when creating a premises monitorable. The reservation soft-locks the ID for 15 minutes; create claims it for the new monitorable. If you omit customerSupportId on create, the platform allocates a new ID automatically (when a pool is configured) and returns it on the create response.

If the partner has no available customer support pool, the reserve endpoint returns a 400 error. Passing an expired or already-claimed ID on create also returns a 400 error.

Person and vehicle monitorables do not use customerSupportId. See Monitor Premises for the create flow.

Contact Ordering

Contacts are used by monitoring agents and emergency services as the call escalation list when an alarm occurs. The order field on each contact controls the sequence in which contacts are attempted.

When you set order, contacts are returned sorted ascending by that value — so order: 1 is tried first, then order: 2, and so on. Each contact on a monitorable must have a unique order value. The API returns a 400 error if a duplicate or conflicting order is provided.

When order is omitted on create, the platform assigns based on the contact's position in the request array: the first contact receives order: 1, the second order: 2, and so on. When adding a new contact on update without an order, the next available value is assigned (highest existing order + 1). An existing contact referenced by id without an order keeps its current order.

You can provide a mix of explicit and omitted order values on create. Omitted contacts use their array index as the fallback.

Scenario	Behavior
All contacts have `order`	Returned sorted by `order` ascending
No contacts have `order` on create	Assigned sequentially by array position (1, 2, 3, …)
Some contacts have `order`, some do not on create	Omitted contacts use their array index; contacts are returned sorted by `order` ascending
New contact on update without `order`	Assigned the next available order (highest existing order + 1)
Existing contact on update without `order`	Keeps its current order
Duplicate `order` in the same request	Rejected with a `400` error
`order` conflicts with an existing contact not in the request	Rejected with a `400` error

Example — Explicit Ordering

{
  "contacts": [
    {
      "firstName": "Alice",
      "lastName": "Jones",
      "phoneNumber": "+15551110001",
      "emailAddress": "alice@example.com",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "order": 2
    },
    {
      "firstName": "Bob",
      "lastName": "Jones",
      "phoneNumber": "+15551110002",
      "emailAddress": "bob@example.com",
      "contactType": "EMERGENCY",
      "preferredLanguage": "en-US",
      "order": 1
    }
  ]
}

Even though Alice appears first in the array, she receives order: 2 and Bob receives order: 1, so Bob will be contacted first during a call escalation.

Documents

Documents are generated automatically by the Hyperion platform. They cannot be created or modified through the API.

Monitorables can have documents associated with them, such as proof of coverage certificates. The platform generates these documents automatically when certain conditions are met — for example, when a premises monitorable becomes verified.

Documents are included in the monitorable response under the documents array and can also be retrieved individually through dedicated endpoints.

Document Types

Type	Description
`PROOF_OF_COVERAGE`	Certificate confirming that the monitorable has active monitoring coverage

Media Types

Media Type	Description
`PDF`	PDF document format

Document Fields

Each document in the documents array contains the following fields:

Field	Description
`id`	Unique identifier for the document
`monitorableId`	ID of the monitorable the document belongs to
`mediaType`	Format of the document (`PDF`)
`type`	Type of document (`PROOF_OF_COVERAGE`)
`createdAt`	Timestamp when the document was created
`updatedAt`	Timestamp when the document was last updated

Example Response

When retrieving a monitorable, documents appear in the response:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "PREMISES",
  "verificationStatus": "VERIFIED",
  "systemStatus": "ACTIVE",
  "picEnabled": false,
  "requirements": [],
  "documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "monitorableId": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
      "mediaType": "PDF",
      "type": "PROOF_OF_COVERAGE",
      "createdAt": "2024-02-01T12:00:00Z",
      "updatedAt": "2024-02-01T12:00:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-02-01T12:00:00Z"
}

To download the actual document content, use the Download Document Content endpoint with the document id.

Guides

Monitor Premises - Step-by-step guide to create premises monitorables
Monitor Persons - Step-by-step guide to create person monitorables
Monitor Vehicles - Step-by-step guide to create vehicle monitorables
Check Service Availability - Discover subscriptions and compliance for a location

Concepts

Subscriptions - Partner subscription offerings and the SUBSCRIPTION requirement

API Reference

Create Monitorable - Create a new monitorable
Get Monitorable - Retrieve monitorable details
List Monitorables - List all monitorables
Update Monitorable - Update monitorable details
Generate Token - Create a monitorable access token
List Events - Get events for a monitorable
List Documents - Get documents for a monitorable
Get Document - Retrieve document details
Download Document Content - Download the document file

What types of monitorables are available?​

What data is stored?​

Contact type​

Common Fields​

Premises Fields​

Person Fields​

Vehicle Fields​

Use Cases​

Home Security Monitoring​

Personal Safety​

Vehicle Monitoring​

Customer Support ID​

Contact Ordering​

Example — Explicit Ordering​

Documents​

Document Types​

Media Types​

Document Fields​

Example Response​

Related Resources​

Guides​

Concepts​

API Reference​

What types of monitorables are available?

What data is stored?

Contact type

Common Fields

Premises Fields

Person Fields

Vehicle Fields

Use Cases

Home Security Monitoring

Personal Safety

Vehicle Monitoring

Customer Support ID

Contact Ordering

Example — Explicit Ordering

Documents

Document Types

Media Types

Document Fields

Example Response

Related Resources

Guides

Concepts

API Reference