Skip to main content

Monitor Vehicles

Monitor Vehicles

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

Overview​

Monitorables are people, places, or things that you want to monitor for events and alarms. Vehicle monitorables are used to track and monitor vehicles, enabling use cases such as fleet management and stolen vehicle recovery.

Getting Started​

Before creating a vehicle 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 Vehicle Monitorable​

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

Vehicle

Vehicle manufacturer

Vehicle model

Vehicle manufacturing year

Vehicle Identification Number

Contacts for the vehicle

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

cURL command

cURLPOST
curl -X POST "/v1/monitorables" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
  "contacts": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+15551234567",
      "emailAddress": "john.doe@example.com",
      "communicationMode": "VIDEO",
      "contactType": "PRIMARY",
      "preferredLanguage": "en-US"
    }
  ],
  "type": "VEHICLE",
  "externalId": "ext-vehicle-abc123",
  "vehicle": {
    "make": "Toyota",
    "model": "Camry",
    "year": 2023,
    "vin": "1HGBH41JXMN109186"
  },
  "terms": {
    "ipAddress": "192.168.0.1",
    "acceptedAt": "2026-10-02T18:11:59.937Z"
  }
}'

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

Response​

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

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ext-vehicle-abc123",
  "type": "VEHICLE",
  "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 a vehicle 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": "VEHICLE",
  "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 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 vehicle monitorable in the Hyperion platform. The vehicle monitorable can now be used to track events for the vehicle.

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​