Skip to main content

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

External identifier to represent this monitorable. Alternatively, send the optional query parameter externalId; a query value takes precedence over the body.

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.

External identifier to represent this contact. Optional partner-supplied id.

First name of the contact

Last name of the contact

Phone number in E.164 format

Optional secondary phone number in E.164 format. Omit or send null when the contact has no second number.

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-29T16:45:54.883Z"
  }
}'

💡 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",
  "personalIdentificationCodeEnabled": 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.

Conclusion​

You've successfully created a vehicle monitorable in the Hyperion platform.

Next Steps​

Activate service before events can be created. See the Activate Service guide. Then see Create Events to send events for your monitorable.

Learn More​

  • Monitorables - Understanding monitorable types and fields
  • Events - Creating events for monitorables

API Reference​