Skip to main content

Monitor Premises

Monitor Premises

In this guide, we will create a premises monitorable to allow us to monitor events for a physical location.

Overview​

Monitorables are people, places, or things that you want to monitor for events and alarms. Premises monitorables are used to track and monitor physical locations, such as homes, businesses, or commercial buildings.

Getting Started​

Before creating a premises monitorable, you need an application with the monitorable:write scope. If you haven't created an application yet, see the Create Application API Reference to get started.

Once you have your application credentials, use the Set Access Token button in the navbar to configure your access token for making API requests.

Create a Premises Monitorable​

To create a premises monitorable, send a POST request to the /monitorables endpoint with the premises information:

Request body

Type of monitorable to create

Identifier to assign to this monitorable. When omitted, an identifier is generated. Must be unique; a value already in use is rejected with 409.

External identifier to represent this monitorable. Alternatively, send the optional HTTP header External-Id when externalId is omitted; a string in the body takes precedence over the header.

Personal identification code for the monitorable. Cannot be reused across contacts and the monitorable.

Type of premises being monitored

Address

Primary street address

Secondary address information (apartment, suite, etc.)

City name

ISO 3166-2 subdivision code (e.g. "US-NY", "CA-ON", "MX-JAL")

County name

Postal or ZIP code

ISO 3166-1 alpha-2 country code

Municipality identifier

Contacts for the premises

Contact 1

Contact ID. When provided on update, updates the existing contact. Omit to create a new contact.

First name of the contact

Last name of the contact

Phone number in E.164 format

Email address of the contact. Required when contactType is PRIMARY. Optional for EMERGENCY. An empty string is rejected.

Preferred communication mode for this contact

Role of this contact. PRIMARY is the main contact. EMERGENCY is an additional contact. Exactly one contact on a monitorable must be PRIMARY. Omitted values are stored as EMERGENCY.

BCP-47 language tag for preferred language

Personal identification code. Cannot be reused across contacts and the monitorable.

Call escalation order for this contact. Must be unique across all contacts on the monitorable. When omitted on create, defaults to the contact position in the request array. When omitted on update for a new contact, the next available order value is assigned (highest existing order + 1).

Terms

IP address used for terms acceptance. When omitted, the server resolves the client IP from forwarded request headers.

Date and time when terms were accepted

Customer support ID from a prior service availability check. When omitted, a new ID is allocated.

Subscription type selected for this premises. Must be one of the options from the SUBSCRIPTION requirement.

cURL command

cURLPOST
curl -X POST "/v1/monitorables" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "city": "Austin",
    "state": "US-TX",
    "county": "Travis",
    "postalCode": "00001",
    "country": "US"
  },
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "VIDEO",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US"
    }
  ],
  "type": "PREMISES",
  "externalId": "ext-premises-12345",
  "premisesType": "RESIDENTIAL",
  "terms": {
    "ipAddress": "192.168.0.1",
    "acceptedAt": "2026-10-02T18:11:59.881Z"
  }
}'

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

Upon successful creation, you'll receive a response containing the premises monitorable details:

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-premises-12345",
  "customerSupportId": "A265000001",
  "type": "PREMISES",
  "verificationStatus": "PENDING_REQUIREMENTS",
  "systemStatus": "INACTIVE",
  "picEnabled": false,
  "subscription": "MONTHLY",
  "keys": [],
  "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"
    },
    {
      "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": [],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}
Ensure you provide enough contacts to meet the jurisdiction's requirements. The monitoring account will not be created until the required number of contacts is provided. See Number of Contacts Requirement for details.

Customer Support ID​

Premises monitorables are associated with a customerSupportId (ex. A265000001).

To reserve an ID before create, send a POST request to /monitorables/customer-support-id:

cURL command

cURLPOST
curl -X POST "/v1/monitorables/customer-support-id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Set your access token in the navbar to auto-fill the Authorization header

Response:

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

The response id is the customer support ID string. Pass it as customerSupportId when creating the premises monitorable. The reservation lasts 15 minutes; the platform claims the reserved ID for the new monitorable. If you omit the field on create, a new ID is allocated automatically and returned on the create response. Passing an expired or already-claimed ID returns a 400 error. If the partner has no available customer support pool, the reserve endpoint returns a 400 error.

Person and vehicle monitorables do not use customerSupportId.

Subscription​

When the partner has active subscription offerings, creating a premises monitorable generates a SUBSCRIPTION pre-activation requirement. The allowed types appear in the requirement options array (for example MONTHLY, ANNUAL).

You may pass subscription on create:

  • If the value is one of the allowed options, the requirement is created as COMPLETE and subscription is set on the monitorable.
  • If omitted, the requirement is created as INCOMPLETE and must be fulfilled before activation via update.
  • If you pass subscription when the partner has no active subscriptions, the API returns 400 with Subscription is not available for this partner.

If the partner has no active subscriptions, no SUBSCRIPTION requirement is created.

See Subscriptions for the full model.

Contact Ordering​

Contacts serve as the call escalation list used by monitoring agents and emergency services when an alarm occurs at the premises. Use the optional order field on each contact to control the sequence in which contacts are attempted — order: 1 is tried first, then order: 2, and so on.

When order is omitted on create, the platform assigns based on the contact's position in the request array. When adding a new contact on update without order, the next available value is assigned. Each contact must have a unique order — duplicates are rejected with a 400 error. Exactly one contact must be PRIMARY, and that contact needs an email. See Contact type.

{
  "type": "PREMISES",
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551110001",
      "emailAddress": "john.doe@example.com",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "order": 1
    },
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "phoneNumber": "+15551110002",
      "emailAddress": "jane.doe@example.com",
      "contactType": "EMERGENCY",
      "preferredLanguage": "en-US",
      "order": 2
    }
  ]
}

See Contact Ordering in the Monitorables concept guide for a full explanation.

Activate the Monitorable​

After creating the monitorable, you need to activate it before events can be created. The monitorable must have a status of PENDING_REQUIREMENTS or VERIFIED and meet all pre-activation requirements, including required contacts and — when present — a completed SUBSCRIPTION requirement.

Send a POST request to the /monitorables/:monitorableId/activate endpoint:

Path parameters

cURL command

cURLPOST
curl -X POST "/v1/monitorables/:monitorableId/activate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Set your access token in the navbar to auto-fill the Authorization header

Conclusion​

You've successfully created and activated a premises monitorable in the Hyperion platform. The premises monitorable can now be used to track events for the physical location.

Next Steps​

Now that you have a monitorable, you can start creating events for it. See the Create Events guide to learn how to send events for your monitorable.

Learn More​

  • Monitorables - Understanding monitorable types and fields
  • Subscriptions - Subscription offerings and the SUBSCRIPTION requirement
  • Events - Creating events for monitorables

API Reference​