Skip to main content

Monitor Persons

Monitor Persons

In this guide, we will create a person monitorable to allow us to monitor events for an individual.

Overview​

Monitorables are people, places, or things that you want to monitor for events and alarms. Person monitorables are used to track and monitor individuals, such as employees, a homeowner, or a resident.

Getting Started​

Before creating a person 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 Person Monitorable​

To create a person monitorable, send a POST request to the /monitorables endpoint with the person's 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.

Person

First name of the person

Last name of the person

Email address of the person

Phone number in E.164 format

BCP-47 language tag for preferred language

Default communication mode for this person

Contacts for the person

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).

Relationship of the contact to the person

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

cURL command

cURLPOST
curl -X POST "/v1/monitorables" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "person": {
    "firstName": "Jane",
    "lastName": "Smith",
    "emailAddress": "jane.smith@example.com",
    "phoneNumber": "+15551234567",
    "preferredLanguage": "en-US",
    "communicationMode": "VIDEO"
  },
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.smith@example.com",
      "communicationMode": "SMS",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "relationship": "SPOUSE"
    }
  ],
  "type": "PERSON",
  "externalId": "ext-person-abc123",
  "terms": {
    "ipAddress": "192.168.0.1",
    "acceptedAt": "2026-10-02T18:11:59.827Z"
  }
}'

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

Response​

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

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-person-abc123",
  "type": "PERSON",
  "verificationStatus": "VERIFIED",
  "systemStatus": "INACTIVE",
  "picEnabled": false,
  "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"
    }
  ],
  "documents": [],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z"
}

Contact Ordering​

Contacts serve as the call escalation list used by monitoring agents and emergency services when an alarm occurs. 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": "PERSON",
  "contacts": [
    {
      "firstName": "Bob",
      "lastName": "Smith",
      "phoneNumber": "+15551110001",
      "emailAddress": "bob.smith@example.com",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US",
      "relationship": "SPOUSE",
      "order": 1
    },
    {
      "firstName": "Carol",
      "lastName": "Smith",
      "phoneNumber": "+15551110002",
      "emailAddress": "carol.smith@example.com",
      "contactType": "EMERGENCY",
      "preferredLanguage": "en-US",
      "relationship": "MOTHER",
      "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 activation requirements such as required contacts.

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 person monitorable in the Hyperion platform. The person monitorable can now be used to track events for the individual.

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
  • Events - Creating events for monitorables

API Reference​