API docs by Redocly

Silver Shield Integration API (Part HTTP) (v5.0.0)

Download OpenAPI specification:

Silver Shield Developer Support: support@pontosense.com License: Apache 2.0

This specification defines the HTTP APIs provided by Silver Shield for third-party system integration.

Authentication

To access these APIs, partners must obtain a valid API access key through the Silver Shield Developer Portal. All API requests require authentication via HMAC-SHA256 signature in the Authorization header.

Terminology

Throughout this document:

  • "Sensor" refers to the Silver Shield monitoring device.
  • "Tenant" refers to the account of an organization or customer in the Silver Shield system.
  • "Client" refers to the third-party Integrator's system.

Firmware Management

APIs for managing sensor firmware, including version queries and upgrade operations

Query available firmware versions

Retrieves a list of available firmware versions for supported sensor models. Use this endpoint to determine if newer firmware versions are available for upgrade.

Response Structure: The response is organized by sensor model, listing all available firmware versions including release notes and compatibility information.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sensor Management

APIs for sensor lifecycle management, including registration, configuration, monitoring, and maintenance

Provision sensor MQTT certificates

Provisions security certificates required for the sensor to establish secure connections with the MQTT broker.

Use Case

This endpoint should be called during the initial sensor onboarding process. The Integrator's system retrieves the certificates and transmits them securely to the sensor via the App, enabling authenticated and encrypted MQTT communication.

Important Notes

  • Certificates are unique to each sensor and cannot be reused
  • The response includes MQTT broker connection details (host, port, etc.)
  • Use the App SDK provided to ensure proper security measures when transmitting certificates to the sensor
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
version
required
string (Version) ^(\d+)\.(\d+)\.(\d+)$

Version number following semantic versioning format (X.Y.Z).

model
required
integer <int32> (Model)
Enum: 2 4

Sensor hardware model identification

Supported Models:

  • 2: P2 model (serial number format: ATR_GN_P2-######-#####)
  • 4: P4 model (serial number format: ATR_GN_P4-######-#####)

Model information is embedded in the sensor serial number and determines firmware compatibility and feature support.

timeZone
required
string <time-zone>

Time zone of the sensor.

name
string [ 1 .. 64 ] characters

Name of the sensor.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "version": "1.2.0",
  • "model": 2,
  • "timeZone": "string",
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "thingName": "string",
  • "certPem": "string",
  • "publicKey": "string",
  • "privateKey": "string",
  • "host": "http://example.com",
  • "orgId": 4001,
  • "sensorId": 6001
}

List sensors with filtering and pagination

Retrieves a paginated list of sensors with advanced filtering capabilities for comprehensive device inventory management.

Filtering Capabilities

Supports multi-parameter filtering for precise sensor discovery:

  • sn: Filter by exact sensor serial number for specific device lookup
  • model: Filter by sensor model type to narrow down device categories
  • version: Filter by firmware version to identify sensors running specific software releases
  • state: Filter by connection status
    • 10: Online - Sensor actively connected and operational
    • 20: Offline - Sensor disconnected or unreachable
  • radarState: Filter by radar working condition
    • 0: Normal - Radar functioning correctly
    • 21: Abnormal - Radar error detected
    • 22: Mount angle skewed - Installation angle out of optimal range
  • upgradeState: Filter by firmware upgrade status
    • 0: Up-to-date - Running latest firmware
    • 10: New firmware available - Update pending
    • 20: Upgrading - Currently performing firmware update
    • 30: Upgrade failed - Previous upgrade attempt unsuccessful
  • metaKey/metaValue: Filter by custom metadata key-value pairs for integrator-specific categorization

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

sn
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: sn=ATR_GN_P4-250120-09527

Sensor serial number for filtering (partial match supported)

model
integer <int32> (Model)
Enum: 2 4
Example: model=2

Sensor model

version
string (Version) ^(\d+)\.(\d+)\.(\d+)$
Example: version=1.2.0

Firmware version

state
integer <int32> (SensorState)
Enum: 10 20

Sensor connection status

radarState
integer <int32> (RadarWorkState)
Enum: 0 21 22

Radar work status

upgradeState
integer <int32> (UpgradeState)
Enum: 0 10 20 30

Upgrade status

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Retrieve sensor details

Retrieves comprehensive information about a specific sensor, including:

  • Current configuration parameters
  • Default settings for comparison
  • Installation angle metrics (roll, pitch)
  • Connection and working status
  • Firmware version information

This endpoint is typically used for diagnostic purposes or to display sensor status in management interfaces.

Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "sn": "ATR_GN_P4-250120-09527",
  • "version": "1.2.0",
  • "model": 2,
  • "configs": {
    },
  • "defaults": {
    },
  • "angle": {
    }
}

Update sensor metadata

Updates modifiable attributes of an existing sensor.

Updateable Fields

  • name: Display name for the sensor (1-64 characters)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Rename sensors for better identification
  • Attach custom metadata for tracking or categorization
  • Update sensor information after deployment changes
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

Name of the sensor.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remove sensor from system

Permanently removes a sensor from the tenant's system.

Important Considerations

  • This operation is irreversible
  • All sensor data, configurations, and associations will be removed
  • The sensor will no longer be able to communicate with the platform
  • Consider archiving or suspending instead of deleting if data retention is required

Prerequisites

  • Sensor must exist in the tenant's system
  • Proper authentication credentials are required
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Configure sensor scan area and mounting parameters

Configures monitoring space (scan area) for optimal sensor performance.

Configuration Parameters

All measurements are relative to the sensor's facing direction:

  • left: Left scan distance (150-600 cm)
  • right: Right scan distance (150-600 cm)
  • height: Sensor mounting height (200-220 cm from floor)

Use Cases

  • Initial sensor installation and calibration
  • Adjusting detection range after physical relocation
  • Optimizing coverage for room layout changes

Best Practices

  • Ensure measurements are accurate for reliable detection
  • Consider furniture and obstacles when setting scan distances
  • Follow manufacturer-recommended mounting height guidelines

Image Example

Example Diagram

Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
left
required
integer [ 150 .. 600 ]

Left-side detection distance in centimeters (horizontal)

right
required
integer [ 150 .. 600 ]

Right-side detection distance in centimeters (horizontal)

height
required
integer [ 200 .. 220 ]

Sensor mounting height from floor in centimeters (vertical)

Responses

Request samples

Content type
application/json
{
  • "left": 150,
  • "right": 150,
  • "height": 200
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Configure sensor detection zones

Defines spatial zones within the sensor's scan area to enable location-specific activity monitoring and event generation.

Zone Types

  • 10: Bed zone
  • 20: Door zone
  • 30: Sofa/Couch zone
  • 40: Toilet zone
  • 50: Medication station zone

Configuration Requirements

  • coordinates: Zone boundary defined by top-left and bottom-right corner points (in cm)
  • height: Zone height (0-500 cm)
  • angle: Zone orientation to the nearest 90 degree angle (0, 90, 180, 270, 360 degrees, clockwise from top)

Benefits

  • Enables zone-specific activity logging
  • Generates targeted events (e.g., bed_in, door_in)
  • Supports location-aware analytics and reporting
  • Improves fall detection accuracy with context
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
Array
id
required
integer <int64> (Id) >= 1

Unique identifier for an entity in the system.

This is a base type used by all entity identifiers (User, Home, Room, Tenant, Sensor, etc.). The value is automatically assigned by the server and must be greater than 0.

type
required
integer <int32>
Enum: 10 20 30 40 50

Zone type

  • 10: bed
  • 20: door
  • 30: sofa
  • 40: toilet
  • 50: medication station
required
Array of objects (Coordinate) = 2 items

Zone boundaries (rectangle) in centimeters, given as the top-left and bottom-right corner points.

height
integer <int32> [ 0 .. 500 ]

Zone height in centimeters (integer ≥ 0 and ≤ 500).

angle
integer <int32>
Enum: 0 90 180 270

Zone orientation in degrees (clockwise from top).

  • 0: Top-up (default)
  • 90: Right-up
  • 180: Bottom-up
  • 270: Left-up

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Retrieve configured sensor zones

Retrieves the complete list of configured zones for a specific sensor.

Response Details

Returns all zone configurations including:

  • id - System-generated unique identifier for the zone (integer > 0).
  • type - Zone category (10=Bed, 20=Door, 30=Sofa, 40=Medication Station, 50=Toilet).
  • coordinates - Rectangle boundaries in cm (top-left and bottom-right points).
  • height - Zone height in cm (0-500).
  • angle - Zone orientation in degrees (0-360, 0 = top-up, clockwise).

Use Cases

  • Display zone configuration in management interfaces
  • Verify zone setup after configuration changes
  • Export zone data for external processing
  • Diagnostic troubleshooting
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Configure fall detection delay threshold

Configures the fall detection delay threshold to balance sensitivity and false positive rates.

Threshold Values

  • 0 seconds: Immediate detection (fastest, highest false positive rate, usually for demo or testing)
  • 30 seconds: Balanced detection
  • 60 seconds: Standard detection
  • 90 seconds: Default detection (slowest, lowest false positive rate)

Threshold Impact

Lower Threshold:

  • Faster fall alerts
  • Increased risk of false positives
  • Suitable for environments requiring immediate notification

Higher Threshold:

  • Reduced false positives
  • Delayed alerts
  • Suitable for environments prioritizing accuracy over speed

Recommendations

  • Start with 30-60 seconds for optimal balance
  • Adjust based on user behavior and environment
  • Monitor and tune based on actual alert patterns
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
threshold
required
integer
Enum: 0 30 60 90

Fall detection confirmation delay in seconds

Threshold Options:

  • 0 seconds: Immediate detection (fastest, highest false positive rate)
  • 30 seconds: Balanced detection
  • 60 seconds: Standard detection
  • 90 seconds: Conservative detection (slowest, lowest false positive rate)

Responses

Request samples

Content type
application/json
{
  • "threshold": 0
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Enable real-time location reporting

Activates continuous real-time location data transmission to the configured MQTT channel.

Behavior

  • Sensor begins transmitting target location data immediately
  • Location updates include detected target positions and movement
  • Automatic timeout after 60 seconds to prevent excessive network traffic
  • Repeated calls within the timeout period do not extend the duration

Use Cases

  • Live monitoring dashboards
  • Real-time occupancy tracking
  • Immediate location visualization
  • Debugging sensor placement and coverage

Important Notes

  • Use /sensors/{sn}/actions/location/stop to terminate reporting before timeout
  • Requires active MQTT subscription to receive location data (MQTT over Websockets provided by default)
  • Location data is published to sensor-specific MQTT topics
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Disable real-time location reporting

Immediately terminates active real-time location data transmission.

Behavior

  • Stops location reporting to MQTT channel instantly
  • No-op if sensor is not currently reporting
  • Sensor resumes normal event-based operation
  • Does not affect other sensor functionality

Use Cases

  • Manual termination of location monitoring sessions
  • Reducing network bandwidth usage
  • Transitioning to event-based monitoring
  • Emergency stop of location tracking

Important Notes

  • Event detection continues normally after stopping
  • To restart reporting, call the /start endpoint again
  • MQTT subscription cleanup is client responsibility
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remote sensor reboot

Initiates a remote power cycle of the specified sensor.

Use Cases

  • Applying configuration changes that require reboot
  • Recovering from software errors or unresponsive states
  • Clearing temporary sensor issues without physical access
  • Post-firmware upgrade finalization

Behavior

  • Sensor gracefully shuts down and powers back on (about 10s in total)

Important Notes

  • Sensor will be temporarily offline during reboot process
  • No data collection during offline period
  • Consider scheduling during low-activity periods
  • Verify sensor returns to online status after operation
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Initiate firmware upgrade

Triggers an over-the-air (OTA) firmware upgrade for the specified sensor.

Request Parameters

  • firmwareId: Unique identifier of the target firmware version
  • otaType: Upgrade mode
    • 0: Manual upgrade (initiated by user)
    • 1: Automatic upgrade (system-initiated)

Upgrade Process

  1. Sensor receives upgrade command
  2. Sensor downloads firmware from server
  3. Sensor validates firmware integrity
  4. Sensor installs new firmware
  5. Sensor reboots to complete installation
  6. Sensor reconnects with new firmware version

Important Considerations

  • Sensor will be offline during upgrade (~2-5 minutes depending on the network to download firmware)
  • Do not power off sensor during upgrade process
  • Monitor upgrade status via sensor state endpoint
  • Verify successful upgrade via status check
  • Failed upgrades will automatically roll back to previous version
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
firmwareId
required
integer <int64> (Id) >= 1

Unique identifier for an entity in the system.

This is a base type used by all entity identifiers (User, Home, Room, Tenant, Sensor, etc.). The value is automatically assigned by the server and must be greater than 0.

otaType
integer <int32> (OtaType)
Enum: 0 1

(optional): Upgrade type.

  • 0: Manual upgrade
  • 1: Automatic upgrade

Responses

Request samples

Content type
application/json
{
  • "firmwareId": 1,
  • "otaType": 0
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Assign sensor to room

Associates a sensor with a specific room within a home, enabling room-level organization and analytics. Currently, only one room can be assigned per sensor.

Use Cases

  • Organize sensors by physical location
  • Enable room-specific activity monitoring
  • Support room-level reporting and analytics
  • Facilitate room-based sensor management

Behavior

  • Sensor becomes part of the specified room
  • Room-level events include sensor data
  • Sensor can be reassigned to different rooms
  • Previous room assignment is overwritten

Important Notes

  • Room must exist in the same tenant and home
  • Sensor can only be assigned to one room at a time
  • Room context enhances event filtering and reporting
  • Consider room naming conventions for consistency
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Request Body schema: application/json
roomId
required
integer <int64> (RoomId) >= 1

Unique identifier for a room in the system.

This ID is automatically generated when a room is created and remains constant throughout the room's lifecycle. A room represents a physical space within a home where a sensor is deployed (e.g., bedroom, living room, bathroom). Used for referencing the room in API operations.

Responses

Request samples

Content type
application/json
{
  • "roomId": 3001
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Complete the onboarding process

Marks the completion of the physical sensor installation (mounting and calibration) process.

Use Case

This endpoint should be called after:

  • Physical installation is complete
  • Sensor is properly mounted at correct height
  • Initial calibration and angle adjustment is finalized
  • Scan area and zone configurations are set

Behavior

  • Confirms sensor is ready for active monitoring
  • Updates sensor state to normal operation
  • Enables full event generation and reporting
  • May trigger post-installation diagnostics

Prerequisites

  • Sensor must be in installation/setup state
  • Physical mounting and calibration must be complete
  • Required configurations (scan area, zones) should be set

Important Notes

  • Call this endpoint only after successful physical installation
  • Do not call during ongoing calibration processes
  • Verify sensor placement and orientation before completion
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

sn
required
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: ATR_GN_P4-250120-09527

Unique sensor serial number as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

User Management

APIs for user account management, including creation, updates, and binding/unbinding operations

Query user accounts

Retrieves a paginated list of user accounts with comprehensive filtering capabilities.

Filtering Options

  • name: Filter by user name (partial match, case-insensitive)
  • email: Filter by email address (partial match, case-insensitive)
  • id: Filter by exact user ID
  • homeId: Filter users associated with specific home
  • labelId: Filter users bound to specific label
  • metaKey/metaValue: Filter by custom metadata key-value pairs

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Response

Returns user details including:

  • User ID, name, and email
  • Creation timestamp
  • Associated homes and labels
  • Custom metadata
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

name
string

Filter by name (partial match, case-insensitive)

email
string

Filter by email address (partial match, case-insensitive)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

homeId
integer <int64> (HomeId) >= 1
Example: homeId=1

Home unique identifier for filtering

labelId
integer <int64> (LabelId) >= 1
Example: labelId=1

Label unique identifier for filtering

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Create user account

Creates a new user account within the tenant.

Required Fields

  • name: Display name (1-64 characters)
  • email: Valid email address for user identification and notifications

Optional Fields

  • metadata: Custom key-value pairs for integrator-specific data

Response

Returns the newly created user's ID for reference in subsequent operations.

Use Cases

  • Register new residents or monitored individuals
  • Add caregivers or family members
  • Create user accounts for system administrators
  • Establish user profiles for analytics and reporting

Important Notes

  • Email addresses must be unique within the tenant
  • User account is created in unbound state (no homes/labels)
  • Use binding endpoints to associate user with homes and labels
  • User metadata persists across all associated resources
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The username of the new user.

email
required
string <email>

A real mailbox that accepts mail for user login.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "userId": 1
}

Update user account

Modifies existing user account information.

Updateable Fields

  • name: Display name (1-64 characters)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Update user information after life changes
  • Correct typos or errors in user data
  • Add or modify metadata for categorization
  • Maintain accurate user records

Important Notes

  • Email address cannot be modified through this endpoint
  • Existing home and label associations are preserved
  • Empty metadata fields are not cleared automatically
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The username of the new user.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Delete user account

Permanently removes a user account from the tenant.

Impact

  • User account is permanently deleted
  • All user associations (homes, labels) are removed
  • User-specific data and history may be affected
  • User ID becomes invalid for all operations

Use Cases

  • Remove users who no longer require monitoring
  • Clean up duplicate or test accounts
  • Respond to account closure requests
  • Maintain data privacy and compliance

Important Considerations

  • This operation is irreversible
  • Consider archiving or deactivating instead of deleting
  • Review associated data before deletion
  • Ensure compliance with data retention policies
  • Remove home and label associations before deletion (optional)
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Associate homes with user

Establishes associations between a user and multiple homes. After association, the user will receive events and data from the specified homes.

Request Body

  • homes: Array of home IDs to associate with the user

Behavior

  • User gains access to specified homes
  • User receives events and data from associated homes
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Assign residents to monitored homes
  • Grant caregivers access to multiple residences
  • Establish user-home relationships for multi-unit facilities
  • Manage user permissions across locations

Important Notes

  • Homes must exist within the same tenant
  • User can be associated with multiple homes simultaneously
  • Use DELETE endpoint to remove associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Request Body schema: application/json
homes
required
Array of integers <int64> (HomeId) [ items <int64 > >= 1 ]

List of home IDs to bind to the user.

Responses

Request samples

Content type
application/json
{
  • "homes": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remove home associations from user

Removes associations between a user and specified homes.

Request Body

  • homes: Array of home IDs to disassociate from the user

Behavior

  • User loses access to specified homes
  • User stops receiving events from disassociated homes
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Remove access when user moves or leaves residence
  • Revoke caregiver permissions
  • Update user-home relationships
  • Maintain access control and privacy

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other home associations for the user are preserved
  • Historical data retention depends on system configuration
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Request Body schema: application/json
homes
required
Array of integers <int64> (HomeId) [ items <int64 > >= 1 ]

List of home IDs to unbind from the user.

Responses

Request samples

Content type
application/json
{
  • "homes": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Associate labels with user

Establishes associations between a user and multiple labels. After association, the user will be able to manage the homes belonging to those labels.

Request Body

  • labels: Array of label IDs to associate with the user

Behavior

  • User becomes associated with specified labels
  • User inherits label attributes and categorization
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Categorize users for management and reporting
  • Apply group-based policies or settings
  • Enable label-based filtering and analytics
  • Organize users by care level or service type

Important Notes

  • Labels must exist within the same tenant
  • User can be associated with multiple labels
  • Labels enable enhanced reporting and filtering
  • Use DELETE endpoint to remove associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Request Body schema: application/json
labels
required
Array of integers <int64> (LabelId) [ items <int64 > >= 1 ]

List of label IDs to bind to the user.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remove label associations from user

Removes associations between a user and specified labels. After disassociation, the user will no longer be linked to the homes under those labels.

Request Body

  • labels: Array of label IDs to disassociate from the user

Behavior

  • User loses association with specified labels
  • Label-based categorization is removed for user
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Update user categorization and groupings
  • Remove obsolete or outdated label assignments
  • Reorganize label structure
  • Maintain accurate user classification

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other label associations for the user are preserved
  • Does not delete the label itself
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

userId
required
integer <int64> (Id) >= 1
Example: 1

Unique user identifier as a path parameter

Request Body schema: application/json
labels
required
Array of integers <int64> (LabelId) [ items <int64 > >= 1 ]

List of label IDs to unbind from the user.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Home Management

APIs for home entity management, including creation, modification, and user-label associations

Query home list

Retrieves a paginated list of homes with comprehensive filtering capabilities.

Filtering Options

  • name: Filter by home name (partial match, case-insensitive)
  • id: Filter by exact home ID
  • userId: Filter homes associated with specific user
  • labelId: Filter homes bound to specific label
  • metaKey/metaValue: Filter by custom metadata key-value pairs

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Response

Returns home details including:

  • Home ID and name
  • Creation timestamp
  • Associated users and labels
  • Custom metadata
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

name
string

Filter by name (partial match, case-insensitive)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

userId
integer <int64> (Id) >= 1
Example: userId=1

User unique identifier for filtering

labelId
integer <int64> (LabelId) >= 1
Example: labelId=1

Label unique identifier for filtering

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Create home entity

Creates a new home entity for the tenant.

Required Fields

  • name: Display name (1-64 characters)

Optional Fields

  • metadata: Custom key-value pairs for integrator-specific data

Response

Returns the newly created home's ID for reference in subsequent operations.

Use Cases

  • Register new residences or care facilities
  • Create monitoring spaces for new clients
  • Establish home entities for multi-unit buildings
  • Set up monitoring for new installations

Important Notes

  • Home names must be unique within the tenant (recommended)
  • New homes are created with no associated users or labels
  • Use binding endpoints to associate users and labels
  • Home metadata persists across all associated resources
  • Homes serve as parent entities for rooms and sensors
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the new home.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "homeId": 2001
}

Update home information

Modifies existing home entity details.

Updateable Fields

  • name: Display name (1-64 characters)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Update home information after relocation
  • Correct typos or errors in home data
  • Add or modify metadata for categorization
  • Maintain accurate home records

Important Notes

  • Home ID remains unchanged after updates
  • Existing rooms, sensors, and associations are preserved
  • Empty metadata fields are not cleared automatically
  • Changes take effect immediately
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the home.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Delete home

Permanently removes a home from the tenant.

Impact

  • Home entity is permanently deleted
  • All associated rooms are removed
  • All sensors in associated rooms are unassigned
  • User and label associations are removed
  • Historical data retention depends on system configuration

Use Cases

  • Remove homes that are no longer monitored
  • Clean up test or temporary homes
  • Respond to facility closure or relocation
  • Maintain accurate system organization

Important Considerations

  • This operation is irreversible
  • Consider archiving instead of deleting if data retention is needed
  • Review all rooms and sensors before deletion
  • Ensure compliance with data retention policies
  • Consider impact on associated users and labels
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Associate users with home

Establishes associations between a home and multiple users. After association, the specified users will receive events and data from the home. It is equal to /tenants/{tenantId}/users/{userId}/homes endpoint in terms of functionality.

Request Body

  • users: Array of user IDs to associate with the home

Behavior

  • Specified users gain access to the home
  • Users receive events and data from the home
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Add residents to monitored homes
  • Assign caregivers to specific residences
  • Grant access to multiple users for shared spaces
  • Manage user permissions within home context

Important Notes

  • Users must exist within the same tenant
  • Home can have multiple associated users
  • Users can be associated with multiple homes
  • Use DELETE endpoint to remove associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
users
required
Array of integers <int64> (UserId) [ items <int64 > >= 1 ]

List of user IDs to bind to the home.

Responses

Request samples

Content type
application/json
{
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remove user associations from home

Removes associations between a home and specified users.

Request Body

  • users: Array of user IDs to disassociate from the home

Behavior

  • Specified users lose access to the home
  • Users stop receiving events from the home
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Remove access when residents move or leave
  • Revoke caregiver permissions for specific homes
  • Update user-home relationships after changes
  • Maintain access control and privacy

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other user associations for the home are preserved
  • Historical data retention depends on system configuration
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
users
required
Array of integers <int64> (UserId) [ items <int64 > >= 1 ]

List of user IDs to unbind from the home.

Responses

Request samples

Content type
application/json
{
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Associate labels with home

Establishes associations between a home and multiple labels, grouping homes with labels.

Request Body

  • labels: Array of label IDs to associate with the home

Behavior

  • Home becomes associated with specified labels
  • Home inherits label attributes and categorization
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Categorize homes for management and reporting
  • Apply group-based policies or settings
  • Enable label-based filtering and analytics
  • Organize homes by care level, service type, or region

Important Notes

  • Labels must exist within the same tenant
  • Home can be associated with multiple labels
  • Labels enable enhanced reporting and filtering
  • Use DELETE endpoint to remove associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
labels
required
Array of integers <int64> (LabelId) [ items <int64 > >= 1 ]

List of label IDs to bind to the home.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Remove label associations from home

Removes associations between a home and specified labels.

Request Body

  • labels: Array of label IDs to disassociate from the home

Behavior

  • Home loses association with specified labels
  • Label-based categorization is removed for home
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Update home categorization and groupings
  • Remove obsolete or outdated label assignments
  • Reorganize label structure
  • Maintain accurate home classification

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other label associations for the home are preserved
  • Does not delete the label itself
  • Does not affect users associated with the labels
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
labels
required
Array of integers <int64> (LabelId) [ items <int64 > >= 1 ]

List of label IDs to unbind from the home.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Room Management

APIs for room configuration and activity reporting within homes

Query rooms within home

Retrieves a paginated list of rooms belonging to a specific home with filtering capabilities.

Filtering Options

  • id: Filter by exact room ID
  • name: Filter by room name (partial match, case-insensitive)
  • metaKey/metaValue: Filter by custom metadata key-value pairs

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Response

Returns room details including:

  • Room ID, name, and type
  • Creation timestamp
  • Associated sensors
  • Custom metadata
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

name
string

Filter by name (partial match, case-insensitive)

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Create room entity

Creates a new room within a specific home.

Required Fields

  • name: Display name (1-64 characters)
  • type: Room type
    • 0: Other
    • 1: Bedroom
    • 2: Living room
    • 3: Bathroom
    • 4: Kitchen
    • 5: Office
    • 6: Hallway

Optional Fields

  • metadata: Custom key-value pairs for integrator-specific data

Response

Returns the newly created room's ID for reference in subsequent operations.

Use Cases

  • Define monitored spaces within a home
  • Organize sensors by physical location
  • Enable room-specific reporting and analytics
  • Support room-based activity monitoring

Important Notes

  • Room must belong to an existing home
  • Room names should be unique within the home (recommended)
  • New rooms are created with no associated sensors
  • Use sensor binding to assign sensors to rooms
  • Room type enables enhanced analytics and reporting
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

homeId
required
integer <int64> (HomeId) >= 1
Example: 1

Unique home identifier as a path parameter

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the new room.

type
required
any <int32> (RoomType)
Enum: 0 1 2 3 4 5 6

Room functional classification

Room Types:

  • 0: Other - Custom or undefined room type
  • 1: Bedroom - Sleeping quarters
  • 2: Living room - Common living area
  • 3: Bathroom - Sanitary facilities
  • 4: Kitchen - Food preparation area
  • 5: Office - Workspace area
  • 6: Hallway - Connecting corridor
object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": 0,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "roomId": 3001
}

Update room information

Modifies existing room entity details.

Updateable Fields

  • name: Display name (1-64 characters)
  • type: Room type (see endpoint documentation for values)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Update room information after remodeling
  • Correct typos or errors in room data
  • Modify room type for better categorization
  • Maintain accurate room records

Important Notes

  • Room ID remains unchanged after updates
  • Existing sensors and associations are preserved
  • Empty metadata fields are not cleared automatically
  • Changes to room type affect analytics and reporting
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

roomId
required
integer <int64> (RoomId) >= 1
Example: 1

The unique identifier of the room

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the room.

type
any <int32> (RoomType)
Enum: 0 1 2 3 4 5 6

Room functional classification

Room Types:

  • 0: Other - Custom or undefined room type
  • 1: Bedroom - Sleeping quarters
  • 2: Living room - Common living area
  • 3: Bathroom - Sanitary facilities
  • 4: Kitchen - Food preparation area
  • 5: Office - Workspace area
  • 6: Hallway - Connecting corridor
object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": 0,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Delete room entity

Permanently removes a room from the home's structure.

Impact

  • Room entity is permanently deleted
  • All sensors associated with the room are unassigned
  • Room-specific data and history may be affected
  • Room ID becomes invalid for all operations

Use Cases

  • Remove rooms that are no longer monitored
  • Clean up test or temporary rooms
  • Reorganize home structure after changes
  • Maintain accurate system organization

Important Considerations

  • This operation is irreversible
  • Sensors in the room become unassigned (not deleted)
  • Historical data retention depends on system configuration
  • Consider impact on analytics and reporting
  • Consider deleting sensors first if they are no longer needed
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

roomId
required
integer <int64> (RoomId) >= 1
Example: 1

The unique identifier of the room

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Query weekly activity reports

Retrieves comprehensive weekly activity reports for monitored users in a specific room.

Query Parameters

  • startTime: Report period start (ISO 8601 date-time format)
  • endTime: Report period end (ISO 8601 date-time format)
  • Time window maximum: 7 days

Report Structure

The response includes:

  • Report metadata (room, period, timezone, state)
  • summary: Data analysis sections with insights
  • tips: Actionable recommendations categorized by topic

Report Sections

Reports may contain multiple analysis sections covering:

  • Activity patterns and trends
  • Sleep quality assessments
  • Fall risk evaluation
  • Behavioral changes
  • Care recommendations

Use Cases

  • Monitor user health and behavior trends
  • Generate reports for caregivers and family members
  • Identify potential health issues early
  • Track intervention effectiveness
  • Support care planning and decision-making

Important Notes

  • Report generation may take several seconds
  • Reports are generated based on available data
  • Incomplete weeks may have limited analysis
  • Report state indicates success or failure
  • Failed reports should be re-requested after correction
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

roomId
required
integer <int64> (RoomId) >= 1
Example: 1

The unique identifier of the room

query Parameters
startTime
required
string <date-time> (Time)
Example: startTime=2024-01-01T12:00:00Z

Event window start time (ISO 8601 date-time format). Maximum time window with endTime is 7 days.

endTime
required
string <date-time> (Time)
Example: endTime=2024-01-01T12:00:00Z

Event window end time (ISO 8601 date-time format). Maximum time window with startTime is 7 days.

Responses

Response samples

Content type
application/json
{
  • "roomId": 3001,
  • "roomType": 0,
  • "scale": 1,
  • "startDate": "2025-07-08",
  • "contentStartDate": "2025-07-07",
  • "contentEndDate": "2025-07-13",
  • "timezone": "America/New_York",
  • "state": 1,
  • "summary": {
    },
  • "tips": [
    ]
}

Label Management

APIs for managing labels and their associations with homes and users

Query labels

Retrieves a paginated list of labels with comprehensive filtering capabilities.

Filtering Options

  • id: Filter by exact label ID
  • name: Filter by label name (partial match, case-insensitive)
  • userId: Filter labels associated with specific user
  • homeId: Filter labels bound to specific home
  • metaKey/metaValue: Filter by custom metadata key-value pairs

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Response

Returns label details including:

  • Label ID and name
  • Description
  • Creation timestamp
  • Associated homes and users
  • Custom metadata

Use Cases

  • Review existing label structure
  • Find labels for association operations
  • Analyze label distribution across users and homes
  • Audit label usage and associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

name
string

Filter by name (partial match, case-insensitive)

userId
integer <int64> (Id) >= 1
Example: userId=1

User unique identifier for filtering

homeId
integer <int64> (HomeId) >= 1
Example: homeId=1

Home unique identifier for filtering

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Create label

Creates a new label for categorizing homes and users.

Required Fields

  • name: Display name (1-64 characters)

Optional Fields

  • description: Detailed description (0-500 characters)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Create categories for organizing homes and users
  • Define service tiers or care levels
  • Establish regional or facility groupings
  • Support label-based filtering and reporting

Best Practices

  • Use descriptive, meaningful names
  • Consider label reusability across homes and users
  • Document label purpose in description
  • Plan label structure before creation

Important Notes

  • New labels are created with no associations
  • Use binding endpoints to associate labels with homes and users
  • Label names should be unique (recommended)
  • Labels enable enhanced filtering and analytics
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the new label.

description
string [ 0 .. 500 ]

The description of the label.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Update label

Modifies existing label details.

Updateable Fields

  • name: Display name (1-64 characters)
  • description: Detailed description (0-500 characters)
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Update label information after organizational changes
  • Correct typos or errors in label data
  • Clarify label purpose with descriptions
  • Maintain accurate label records

Important Notes

  • Label ID remains unchanged after updates
  • Existing home and user associations are preserved
  • Changes affect all associated homes and users
  • Empty metadata fields are not cleared automatically
  • Consider impact on existing associations when renaming
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Request Body schema: application/json
name
required
string [ 1 .. 64 ] characters

The name of the label.

description
string

The description of the label.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Delete label

Permanently removes a label for the tenant.

Impact

  • Label entity is permanently deleted
  • All home-label associations are removed
  • All user-label associations are removed
  • Label-based categorization is removed from associated entities
  • Historical data may retain label references

Use Cases

  • Remove obsolete or unused labels
  • Clean up test or temporary labels
  • Reorganize label structure
  • Maintain accurate system organization

Important Considerations

  • This operation is irreversible
  • Consider impact on associated homes and users
  • Associated homes and users are not deleted
  • Historical data analysis may be affected
  • Consider reorganizing instead of deleting if label is in use
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Associate homes with label

Establishes associations between a label and multiple homes.

Request Body

  • homes: Array of home IDs to associate with the label

Behavior

  • Specified homes become associated with the label
  • Homes inherit label attributes and categorization
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Categorize homes for management and reporting
  • Apply group-based policies or settings
  • Enable label-based filtering and analytics
  • Organize homes by service type, region, or care level

Important Notes

  • Homes must exist within the same tenant
  • Label can be associated with multiple homes
  • Homes can be associated with multiple labels
  • Use DELETE endpoint to remove associations
  • All users associated with homes gain indirect label access
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Request Body schema: application/json
homes
required
Array of integers <int64> (HomeId) [ items <int64 > >= 1 ]

List of home IDs to bind to the label.

Responses

Request samples

Content type
application/json
{
  • "homes": [
    ]
}

Response samples

Content type
application/json
{
  • "tenantId": 1
}

Remove home associations from label

Removes associations between a label and specified homes.

Request Body

  • homes: Array of home IDs to disassociate from the label

Behavior

  • Specified homes lose association with the label
  • Label-based categorization is removed for homes
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Update home categorization and groupings
  • Remove obsolete or outdated label assignments
  • Reorganize label structure
  • Maintain accurate home classification

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other home associations for the label are preserved
  • Does not delete the label itself
  • Does not affect users directly associated with homes
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Request Body schema: application/json
homes
required
Array of integers <int64> (HomeId) [ items <int64 > >= 1 ]

List of home IDs to unbind from the label.

Responses

Request samples

Content type
application/json
{
  • "homes": [
    ]
}

Response samples

Content type
application/json
{
  • "tenantId": 1
}

Associate users with label

Establishes direct associations between a label and multiple users.

Request Body

  • users: Array of user IDs to associate with the label

Behavior

  • Specified users become associated with the label
  • Users inherit label attributes and categorization
  • Associations are additive (previous associations preserved)
  • Duplicate associations are ignored

Use Cases

  • Categorize users for management and reporting
  • Apply group-based policies or settings
  • Enable label-based filtering and analytics
  • Organize users by care level, service type, or role

Important Notes

  • Users must exist within the same tenant
  • Label can be associated with multiple users
  • Users can be associated with multiple labels
  • Direct user-label associations differ from indirect associations via homes
  • Use DELETE endpoint to remove associations
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Request Body schema: application/json
users
required
Array of integers <int64> (UserId) [ items <int64 > >= 1 ]

List of user IDs to bind to the label.

Responses

Request samples

Content type
application/json
{
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "tenantId": 1
}

Remove user associations from label

Removes direct associations between a label and specified users.

Request Body

  • users: Array of user IDs to disassociate from the label

Behavior

  • Specified users lose direct association with the label
  • Label-based categorization is removed for users
  • Other associations remain intact
  • Non-existent associations are ignored

Use Cases

  • Update user categorization and groupings
  • Remove obsolete or outdated label assignments
  • Reorganize label structure
  • Maintain accurate user classification

Important Notes

  • This operation is reversible (re-associate using POST endpoint)
  • Other user associations for the label are preserved
  • Does not delete the label itself
  • Does not affect users associated with homes that have this label
  • This affects direct user-label associations, not indirect associations via homes
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

labelId
required
integer <int64> (LabelId) >= 1
Example: 1

Unique label identifier as a path parameter

Request Body schema: application/json
users
required
Array of integers <int64> (UserId) [ items <int64 > >= 1 ]

List of user IDs to unbind from the label.

Responses

Request samples

Content type
application/json
{
  • "users": [
    ]
}

Response samples

Content type
application/json
{
  • "tenantId": 1
}

Tenant Management

APIs for tenant organization management and configuration

Query tenant list

Retrieves a paginated list of tenants with filtering capabilities.

Filtering Options

  • name: Filter by tenant name (partial match, case-insensitive)
  • id: Filter by exact tenant ID
  • email: Filter by tenant email (partial match, case-insensitive)
  • metaKey/metaValue: Filter by custom metadata key-value pairs

Pagination

Requires pageNo and pageSize parameters. Maximum 100 records per page.

Response

Returns tenant details including:

  • Tenant ID and name
  • Contact email
  • Creation timestamp
  • Custom metadata

Access Control

  • Access is restricted based on user permissions
  • Multi-tenant users may see limited information
  • Consult authentication documentation for access details
Authorizations:
ApiKeyAuth
query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

name
string

Filter by name (partial match, case-insensitive)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

email
string

Filter by email address (partial match, case-insensitive)

metaKey
string

Metadata key for filtering (must be used together with metaValue)

metaValue
string

Metadata value for filtering (must be used together with metaKey)

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Create tenant organization

Creates a new tenant organization in the system.

Required Fields

  • name: Organization name
  • email: Contact email address

Optional Fields

  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Onboard new customer organizations
  • Create isolated data spaces for different clients
  • Establish separate organizational units
  • Support multi-tenant deployments

Important Notes

  • Tenant creation is typically restricted to administrators
  • Each tenant provides isolated data and resource management
  • Tenant credentials and access keys are generated after creation
  • Tenant names should be unique across the system (recommended)
  • Metadata persists across all tenant resources
Authorizations:
ApiKeyAuth
Request Body schema: application/json
name
required
string (Name) [ 1 .. 64 ] characters

Human-readable name of an entity.

This field represents the display name for users, homes, rooms, labels, tenants, etc. The name should be descriptive and meaningful for end users. Must be between 1 and 64 characters in length.

email
required
string <email> (Email)

Email address for user or tenant communication.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Update tenant information

Modifies existing tenant organization details.

Updateable Fields

  • name: Organization name
  • metadata: Custom key-value pairs for integrator-specific data

Use Cases

  • Update organization information after rebranding
  • Correct typos or errors in tenant data
  • Add or modify metadata for categorization
  • Maintain accurate tenant records

Important Notes

  • Tenant ID remains unchanged after updates
  • Email address cannot be modified through this endpoint
  • Existing homes, users, and resources are preserved
  • Changes affect all resources within the tenant
  • Empty metadata fields are not cleared automatically
  • Consider impact on integrations when updating tenant information
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

Request Body schema: application/json
name
required
string (Name) [ 1 .. 64 ] characters

Human-readable name of an entity.

This field represents the display name for users, homes, rooms, labels, tenants, etc. The name should be descriptive and meaningful for end users. Must be between 1 and 64 characters in length.

object (Metadata)

Metadata represented as key-value pairs for extensibility.

This field allows clients to attach custom data to entities (users, homes, rooms, etc.) for their own purposes. Key-value pairs are flexible and can store any string values. Reserved for future extensibility and integrations.

Use cases include:

  • Storing custom identifiers from external systems
  • Attaching tags for filtering or categorization
  • Storing integration-specific configuration or flags

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Delete tenant organization

Permanently removes a tenant organization and all associated resources.

Impact

  • Tenant organization is permanently deleted
  • All homes within the tenant are removed
  • All users within the tenant are removed
  • All sensors and configurations are deleted
  • All events, reports, and historical data are removed
  • Tenant access keys and credentials are revoked

Use Cases

  • Remove customer organizations that no longer require service
  • Clean up test or temporary tenants
  • Respond to organization closure requests
  • Maintain system hygiene and organization

Critical Considerations

  • This operation is PERMANENT AND IRREVERSIBLE
  • All data is completely erased with no recovery option
  • Consider exporting data before deletion if required by policy
  • Requires elevated privileges or administrative approval
  • Ensure compliance with data retention and deletion policies
  • Confirm with stakeholders before proceeding
  • WARNING: This operation cannot be undone
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

Responses

Response samples

Content type
application/json
{
  • "code": 100101,
  • "message": "Not authenticated."
}

Event Management

APIs for querying sensor events and activity reports

Query sensor events

Retrieves historical events generated by sensors with comprehensive filtering and pagination. Events can be queried for a maximum of 7 days after trigger and are cleared on a rolling basis.

Required Parameters

  • pageNo, pageSize: Pagination (max 100 records/page)
  • startTime: Event window start (ISO 8601 date-time format)
  • endTime: Event window end (ISO 8601 date-time format)
  • Maximum event history: Last 7 days

Filtering Options

  • id: Filter by exact event ID
  • sn: Filter by sensor serial number
  • type: Filter by event type (see below)

Event Types

Type Description
online Sensor came online
offline Sensor went offline
occupied Room occupancy detected
vacant Room became vacant
bed_in User entered bed
bed_out User exited bed
couch_in User sat on couch/sofa
couch_out User left couch/sofa
door_in User entered through door
door_out User exited through door
mount_angle_skewed Sensor mounting angle abnormal
sensor_recovered Sensor issue resolved
sensor_malfunctioning Sensor malfunction detected
upgrade_started Firmware upgrade initiated
upgrade_succeeded Firmware upgrade completed successfully
upgrade_failed Firmware upgrade failed
fall_detected Fall event detected
fall_recovered User recovered from fall

Use Cases

  • Review historical activity and incidents
  • Analyze patterns and trends
  • Audit sensor operations and status changes
  • Investigate specific events or incidents
  • Generate event-based reports

Important Notes

  • Events are time-ordered (newest first)
  • Events are retained according to system policy
  • Large result sets may require multiple paginated requests
  • Use specific filters to optimize query performance
Authorizations:
ApiKeyAuth
path Parameters
tenantId
required
integer <int64> (TenantId) >= 1
Example: 1

The unique identifier of the tenant

query Parameters
pageNo
required
integer >= 1
Example: pageNo=1

Page number for pagination (starts from 1)

pageSize
required
integer [ 1 .. 100 ]

Number of items per page (maximum 100)

id
integer <int64> (Id) >= 1
Example: id=1

Unique identifier

sn
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$
Example: sn=ATR_GN_P4-250120-09527

Sensor serial number for filtering (partial match supported)

type
string (EventType)
Enum: "online" "offline" "occupied" "vacant" "bed_in" "bed_out" "couch_in" "couch_out" "door_in" "door_out" "fall_detected" "fall_recovered" "mount_angle_skewed" "sensor_recovered" "sensor_malfunctioning" "upgrade_started" "upgrade_succeeded" "upgrade_failed"

Filter by event type code

Available event types:

  • online: Sensor came online
  • offline: Sensor went offline
  • occupied: Room occupancy detected
  • vacant: Room became vacant
  • bed_in: User entered bed
  • bed_out: User exited bed
  • couch_in: User sat on couch/sofa
  • couch_out: User left couch/sofa
  • door_in: User entered through door
  • door_out: User exited through door
  • mount_angle_skewed: Sensor mounting angle abnormal
  • sensor_recovered: Sensor issue resolved
  • sensor_malfunctioning: Sensor malfunction detected
  • upgrade_started: Firmware upgrade initiated
  • upgrade_succeeded: Firmware upgrade completed successfully
  • upgrade_failed: Firmware upgrade failed
  • fall_detected: Fall event detected
  • fall_recovered: User recovered from fall
startTime
required
string <date-time> (Time)
Example: startTime=2024-01-01T12:00:00Z

Event window start time (ISO 8601 date-time format). Maximum time window with endTime is 7 days.

endTime
required
string <date-time> (Time)
Example: endTime=2024-01-01T12:00:00Z

Event window end time (ISO 8601 date-time format). Maximum time window with startTime is 7 days.

Responses

Response samples

Content type
application/json
{
  • "countId": "string",
  • "current": 1,
  • "maxLimit": 0,
  • "optimizeCountSql": true,
  • "pages": 0,
  • "searchCount": true,
  • "size": 100,
  • "total": 0,
  • "records": [
    ]
}

Iot Management

Iot related operations

Get iot token, which is used for device iot authentication.

Get iot token, which is used for iot device authentication.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
sn
string (Sn) ^ATR_GN_P[24]-[0-9]{6}-[0-9]{5}$

Sensor serial number (SN).

Responses

Request samples

Content type
application/json
{
  • "sn": "ATR_GN_P4-250120-09527"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImlhdCI6MTY0MjE5NjQzNywiZXhwIjoxNjQyMjAwMzM3fQ.y5ZY5ZY5ZY5ZY5ZY5ZY5ZY5ZY5ZY5ZY5Z",
  • "expireTime": "2023-01-15T08:13:57Z",
  • "host": "dev-iot.pontosense.net",
  • "data": {
    }
}