• Introduction
  • Dealer Integration
• Authentication
  • Prerequisites
  • Access Control
• REST API (v1)
  • Background
  • Result Options
  • Deprecation
  • Resource: admins
  • Resource: admins-users
  • Resource: admins-webhooks
  • Resource: billing-programs
  • Resource: dealers
  • Resource: dealers-addresses
  • Resource: dealers-phones
  • Resource: dealers-programs
  • Resource: dealers-accounts-transfers
  • Resource: dealers-branding
  • Resource: dealers-suspensionlog
  • Resource: dealers-contacts
  • Resource: dealers-features
  • Resource: dealers-rateplans
  • Resource: devices-aliases
  • Resource: devices
  • Resource: devices-cellular-events
  • Resource: devices-cellular-status
  • Resource: devices-charges
  • Resource: devices-chat-messages
  • Resource: devices-eventlog
  • Resource: devices-features-prices
  • Resource: devices-notifications
  • Resource: devices-programs
  • Resource: devices-relay-attempts
  • Resource: devices-users
  • Resource: events-notifications-cameras
  • Resource: events-notifications-chats
  • Resource: events-notifications-doorbells
  • Resource: events-notifications-locks
  • Resource: events-notifications-signals
  • Resource: events-notifications-zones
  • Resource: events-triggers
  • Resource: events-webhooks
  • Resource: features-bysubject
  • Resource: features-plans
  • Resource: features-plansvideo
  • Resource: features-prices
  • Resource: goldmine-leads
  • Resource: helix-cache-mfd
  • Resource: helix-ha-nodes
  • Resource: helix-users
  • Resource: oauth-accesstokens
  • Resource: oauth-clients
  • Resource: oauth-refreshtokens
  • Resource: rateplans
  • Resource: receivers-binds
  • Resource: receivers-connections
  • Resource: receivers-disabled
  • Resource: receivers-groups
  • Resource: receivers
  • Resource: revisions
  • Resource: self
  • Resource: stations
  • Resource: stations-contacts
  • Resource: timeseries-signal
  • Resource: users
  • Resource: users-addresses
  • Resource: users-phones
  • Resource: users-preferences
  • Resource: users-pushtokens
  • Resource: users-videoprofiles
• RPC API (v1)
  • Background
  • Request
  • Method: alarm.cancel
  • Method: alarm.confirm
  • Method: dealers.devices.stats.get
  • Method: dealers.restore
  • Method: dealers.suspend
  • Method: devices.assign
  • Method: devices.cellular.history.get
  • Method: devices.deactivate
  • Method: devices.features.select
  • Method: devices.initialize
  • Method: devices.mac.generate
  • Method: devices.programs.renew
  • Method: devices.rateplan.get
  • Method: devices.rateplan.set
  • Method: devices.reactivate
  • Method: devices.register
  • Method: devices.replace
  • Method: devices.resume
  • Method: devices.session.init
  • Method: devices.services.restart
  • Method: devices.services.stop
  • Method: devices.signal.add
  • Method: devices.signal.delivered
  • Method: devices.signal.update
  • Method: devices.suspend
  • Method: devices.transfer
  • Method: devices.unassign
  • Method: devices.unregister
  • Method: events.notifications.renew
  • Method: helix.mfd.put
  • Method: helix.mfd.get
  • Method: helix.mfd.invalidate
  • Method: helix.pin.valid
  • Method: helix.sensor.enroll
  • Method: helix.sensor.unenroll
  • Method: mesh.ipdbsd.update
  • Method: mesh.ipddfs.get
  • Method: mesh.ipddfs.put
  • Method: push.send
  • Method: task.mfd.alias.sync
  • Method: users.exists
  • Method: users.pinonly.create
  • Method: users.pushtokens.delete
  • Method: users.pushtokens.put
  • Method: users.transfer
  • Method: users.transfer.request
  • Method: users.transfer.cancel
  • Method: users.transfer.authorize
  • Method: users.transfer.deny
  • Method: users.transfer.reject
  • Method: users.transfer.accept
  • Method: users.validation.phone.request
  • Method: users.validation.phone.confirm
  • Method: users.validation.email.request
  • Method: users.plansvideo.price.get
  • Method: users.type.change
  • Method: users.preferences.list
  • Method: video.register
  • Method: video.unregister
• WS API (v1)
  • Background
  • General Spec
  • Channel: device.query
  • Channel: device.keypad
  • Channel: device.helix
  • Channel: device.notification
  • Channel: device.signal
  • Channel: device.status
  • Channel: event
  • Channel: internal.auth
  • Channel: mesh.message
  • Channel: rest.events
  • Channel: rest.tunnel
  • Channel: rpc.tunnel
  • Channel: work
• Public API (v1)
  • Method: users.password.reset
  • Method: users.password.reset.request
  • Endpoint: users-password-reset-verify
  • Endpoint: validate
  • Endpoint: contacts-verify
  • Endpoint: healthcheck-all
  • Endpoint: healthcheck-default
  • Endpoint: healthcheck-mariadb
  • Endpoint: healthcheck-mongodb
  • Endpoint: healthcheck-rabbitmq
  • Endpoint: healthcheck-mesh
• Event Triggers and Actions
  • Background
  • Components
  • Event: device.chat.new
  • Event: device.doorbell
  • Event: device.mfd
  • Event: device.scene
  • Event: device.signal.new
  • Event: device.signal.update
  • Event: device.video
  • Event: device.zwave
  • Action: publishWork
  • Action: pushDeprecated
  • Action: pushUser
  • Action: webHook
  • Context: date
  • Context: dealer
  • Context: device
  • Context: doorLock
  • Context: nodeName
  • Context: signal
  • Context: zoneConfiguration
  • Context: zoneStatus
• Billing Programs
  • Background
  • Overriding Default Params
  • Billing Program: sunset(f5c27478-1114-4a1e-b7be-08362b681958)
  • Billing Program: builder-2020(7abb379c-93c5-46a0-bcc2-5a302844f362)
  • Billing Program: builder-2021(7bc184fd-5e8a-4bda-8023-4a3b32898d5a)

Branch: HEAD Hash: eff70d86e358b6bdfa7b1e1a7f69846ccf155ec4

Introduction

Welcome to the Alula API. This service has a variety of features, for both internal and external use. The category of use case will largely correspond to the user types listed in the Access Control section.

Dealer Integration

The main use case for external systems integration is at the Dealer account level. If you are developing an integration for a dealer, this section will provide some introductory and reference notes to support your work.

Sandbox

Credentials

To start, you will need the following information to use the Sandbox environment:

• Alarmdealer URL
• API Address and Port
• Client ID
• Client Secret
• Alarmdealer Username
• Alarmdealer Password

With this information, you should be able to get started with Password Grant authentication to the API. You should also be able to log in to the Sandbox Alarmdealer URL with the supplied username and password.

Test Device

The next step is to set up a test device. This section assumes you will be using a Helix panel. You will need the following information about the panel:

• MAC - an identifier of the form XX:XX:XX:XX:XX:XX
• CRC - a 4-digit number found on the label along with the MAC.

You can register the device through the Sandbox Alarmdealer web portal, or using the devices.register RPC method. (If the device has been registered in another portal, you will need to remove it from your inventory there first.)

When you register this device with the Sandbox, we associate it with the Sanbox environment. Next you should power the panel and connect it to the internet. If it is connecting for the first time, it should automatically connect. If it has been online before, connected to a different server, then you will need to factory reset the panel, or send it a special command to cause it to connect to the new Sandbox environment.

Once connected, you should see the device status show ONLINE in the Sandbox Alarmdealer device list, or by querying the devices REST resource.

Authentication

Prerequisites

To write an application that consumes the Alula API, you will need a Client ID and a Client Secret. To use the Authorization Code Grant, described below, you must also have one or more Redirect URIs whitelisted in advance.

Resource Access

Any request for protected resources must include an Access Token. This must be included in an HTTP header as

Authorization: Bearer $ACCESS_TOKEN

An access token may be obtained in the following ways:

Password Grant

A user may log in with their Alula account username and password. This is done via a request to /oauth/token with the following fields URL-encoded in the query string (GET) or form-encoded in the request body (POST):

POST /oauth/token

grant_type=password
client_id=$CLIENT_ID
client_secret=$CLIENT_SECRET
username=$USERNAME
password=$PASSWORD

This request will return a JSON response like the following:

{
  "token_type": "bearer",
  "access_token": "$ACCESS_TOKEN",
  "expires_in": 3600,
  "refresh_token": "$REFRESH_TOKEN"
}

Authorization Code Grant

A login web interface is available via GET request to /login?client_id=$CLIENT_ID&response_type=code&redirect_uri=$REDIRECT_URI&state=. Note that redirect_uri must match a URI stored in the client record for the specified client_id. To request that a URI be added to this list, please contact Alula. response_type must be code. state is optional.

Upon visiting this login page, the user will be presented with the Alula logo; a summary of the request for authorization; form inputs for their username and password; and a submit button.

If the user correctly submits their username and password, the API will respond with a redirect header that sends the user to the requested redirect_uri, appending a query parameter code containing the authorization code. If state was included in the original GET request to /login, then it will be appended to the URI unmodified; this allows your application to include its own reference information about the request.

With this authorization code, your application can request an access token. This is done via a POST request to /oauth/token with the following fields form-encoded in the request body (POST):

POST /oauth/token

grant_type=authorization_code
client_id=$CLIENT_ID
client_secret=$CLIENT_SECRET
code=$AUTHORIZATION_CODE

Refresh Grant

A new access token may be obtained by supplying the refresh token. This is done via a request to /oauth/token with the following fields URL-encoded in the query string (GET) or form-encoded in the request body (POST):

POST /oauth/token

grant_type=refresh_token
client_id=$CLIENT_ID
client_secret=$CLIENT_SECRET
refresh_token=$REFRESH_TOKEN

Access Control

User Types

Some resources and methods are only accessible by certain user types.

OAuth Scopes

As well as being protected by user types, at the lowest level, all resources and methods require a suitable OAuth scope. Available OAuth scopes are specified per OAuth client, and then a subset of the available scopes may be associated with a specific OAuth access/refresh token.

OAuth scopes have yet to be implemented. Look for it soon in a future release.

REST API (v1)

Background

Our REST API is exposed using version 1.0 of the JSON API specification.

We highly recommend going over the spec.

Result Options

Filters

The filter query parameter is used to filter results, and is in the format of an associated array, where the top-level keys are field names ($or operator an exception). The values of top-level keys is either an exact-match term, or another associative array where the keys are comparison operators.

Available Comparison Operators

Example

Javascript object representation of filter param:

{
  "someField": "some value",
  "someNumericField": {
    "$gt": 6
  },
  "$or": {
    "anotherField": 5,
    "yetAnother": {
      "$lt": 3
    }
  },
  "againField": {
    "$or": {
      "$gt": 1,
      "$lt": 10
    }
  },
  "nullField": null
}

Actual URI:

GET /rest/v1/resource
?filter[someField]=some%20value
&filter[someNumericField][$gt]=6
&filter[$or][anotherField]=5
&filter[$or][yetAnother][$lt]=3
&filter[againField][$or][$gt]=1
&filter[againField][$or][$lt]=10
&filter[nullField]

RSQL Filtering

You may also use the where query parameter to filter results using a REST Query Language (RSQL) expression. This filter parameter was added since it is compatible with the OpenAPI Specification. It allows you to use a single query string to filter the results with a SQL-like syntax:

GET /rest/v1/devices?where=programId=in=(32, 35) and onlineStatus==false

The where and filter parameters are compatible and may be included in the same request. In addition to the standard RSQL operators you may also use a custom =like= operator to match string values against a pattern.

Sorting

We implement sorting as described by the JSON API spec.

Custom Options

We have extended the JSON API specification by adding a query parameter, customOptions.

Available options are as follows:

omitRelationships

Default value: false

If included, this option will suppress the list of related resources when fetching a resource or list of resources.

Example:

  GET /rest/v1/devices?customOptions[omitRelationships]=true&filter[mac]=01:02:03:04:05:06

Deprecation

Patchable Field Deprecation

If a patchable field has been marked deprecated for a given user type, that means you can continue passing in that field with a patch request (without error) as long as you are not mutating the value.

Resource: admins

Base URL

/rest/v1/admins

Available methods: GET, PATCH, POST, DELETE

Description

Create, view, configure, and delete admins. When you use this resource to delete an admin, the admin will be marked as hidden and will no longer be able to login to the system.

Relationships

Fields

Resource: admins-users

Base URL

/rest/v1/admins/users

Available methods: GET, PATCH, POST, DELETE

Description

Allows system administrators view all users including hidden users. Hidden users may either be renamed or have their hidden field unset to recover deleted accounts.

Relationships

Fields

Resource: admins-webhooks

Base URL

/rest/v1/admins/webhooks

Available methods: GET, PATCH, POST, DELETE

Description

Read and delete WebHook endpoints for administrators.

Relationships

No relationships available.

Fields

Resource: billing-programs

Base URL

/rest/v1/billing/programs

Available methods: GET

Description

List available billing programs.

Relationships

No relationships available.

Fields

Resource: dealers

Base URL

/rest/v1/dealers

Available methods: GET, PATCH, POST

Description

Create, update, and view dealers.

Relationships

Fields

Resource: dealers-addresses

Base URL

/rest/v1/dealers/addresses

Available methods: GET, PATCH

Description

Update and view dealers’ address contact information.

Relationships

No relationships available.

Fields

Resource: dealers-phones

Base URL

/rest/v1/dealers/phones

Available methods: GET, PATCH

Description

Update and view dealers’ phone contact information.

Relationships

No relationships available.

Fields

Resource: dealers-programs

Base URL

/rest/v1/dealers/programs

Available methods: GET, PATCH, POST, DELETE

Description

Create, configure, and delete dealer billing program bindings.

Relationships

Fields

Resource: dealers-accounts-transfers

Base URL

/rest/v1/dealers/accounts/transfers

Available methods: GET

Description

View dealer account transfers and their statuses

Relationships

No relationships available.

Fields

Resource: dealers-branding

Base URL

/rest/v1/dealers/branding

Available methods: GET, PATCH, POST

Description

Dealer branding information, for customizing the appearance of mobile applications.

Relationships

Fields

Resource: dealers-suspensionlog

Base URL

/rest/v1/dealers/suspensionlog

Available methods: GET, PATCH, POST

Description

View a log of dealer suspend and restore activities

Relationships

Fields

Resource: dealers-contacts

Base URL

/rest/v1/dealers/contacts

Available methods: GET, PATCH, POST, DELETE

Description

Dealer emergency contact info

Relationships

No relationships available.

Fields

Resource: dealers-features

Base URL

/rest/v1/dealers/features

Available methods: GET, PATCH, POST, DELETE

Description

Create, update, and view dealer default featuress.

Relationships

No relationships available.

Fields

Resource: dealers-rateplans

Base URL

/rest/v1/dealers/rateplans

Available methods: GET, PATCH, POST, DELETE

Description

Create, configure, and delete dealer rate plans.

Relationships

Fields

Resource: devices-aliases

Base URL

/rest/v1/devices/aliases

Available methods: GET, PATCH, POST, DELETE

Description

Manage device aliases

Relationships

No relationships available.

Fields

Resource: devices

Base URL

/rest/v1/devices

Available methods: GET, PATCH

Description

The devices resource is used to view or update basic device information and settings.

Relationships

Fields

Resource: devices-cellular-events

Base URL

/rest/v1/devices/cellular/events

Available methods: GET, PATCH, POST

Description

No description provided.

Relationships

No relationships available.

Fields

Resource: devices-cellular-status

Base URL

/rest/v1/devices/cellular/status

Available methods: GET

Relationships

Fields

Resource: devices-charges

Base URL

/rest/v1/devices/charges

Available methods: GET, PATCH, POST, DELETE

Description

Manage device billing charges

Relationships

No relationships available.

Fields

Resource: devices-chat-messages

Base URL

/rest/v1/devices/chat/messages

Available methods: GET, PATCH, POST

Description

Create and read device chat messages.

Relationships

No relationships available.

Fields

Resource: devices-eventlog

Base URL

/rest/v1/devices/eventlog

Available methods: GET

Description

The device eventlog contains a list of all alarm events emitted by a device. It
makes the most sense to view the root of this resource via relationship link
from the devices resource;
i.e. /rest/v1/devices/<device UUID>/eventlog

Relationships

Fields

Resource: devices-features-prices

Base URL

/rest/v1/devices/features/prices

Available methods: GET

Description

View device feature prices

Relationships

No relationships available.

Fields

Resource: devices-notifications

Base URL

/rest/v1/devices/notifications

Available methods: GET, PATCH, POST

Description

This resource is used to configure alarm event notification preferences for devices.

Relationships

Fields

Resource: devices-programs

Base URL

/rest/v1/devices/programs

Available methods: GET, PATCH, POST, DELETE

Description

Create, and delete device to dealer billing program bindings.

Relationships

Fields

Resource: devices-relay-attempts

Base URL

/rest/v1/devices/relay/attempts

Available methods: GET, PATCH, POST

Description

Create and update signal relay attempts.

Relationships

No relationships available.

Fields

Resource: devices-users

Base URL

/rest/v1/devices/users

Available methods: GET, POST, DELETE

Description

Create and destroy devices-users to limit which sub-users have virtual keypad
access to a device.

Relationships

Fields

Resource: events-notifications-cameras

Base URL

/rest/v1/events/notifications/cameras

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for cameras. The authenticated user must have permissions to access the camera device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-notifications-chats

Base URL

/rest/v1/events/notifications/chats

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for chats. The authenticated user must have permissions to access the device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-notifications-doorbells

Base URL

/rest/v1/events/notifications/doorbells

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for doorbells. The authenticated user must have permissions to access the doorbell device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-notifications-locks

Base URL

/rest/v1/events/notifications/locks

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for locks. The authenticated user must have permissions to access the Helix device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-notifications-signals

Base URL

/rest/v1/events/notifications/signals

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for signals. The authenticated user must have permissions to access the device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-notifications-zones

Base URL

/rest/v1/events/notifications/zones

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event trigger notifications for zones. The authenticated user must have permissions to access the Helix device and have a user type of System, Dealer, User, or Sub-User.

Relationships

No relationships available.

Fields

Resource: events-triggers

Base URL

/rest/v1/events/triggers

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete event triggers. The authenticated user must have permissions to access the provided event type and action type.

Relationships

No relationships available.

Fields

Resource: events-webhooks

Base URL

/rest/v1/events/webhooks

Available methods: GET, PATCH, POST, DELETE

Description

Create, read, update, and delete WebHook endpoints.

Relationships

No relationships available.

Fields

Resource: features-bysubject

Base URL

/rest/v1/features/bysubject

Available methods: GET, PATCH, POST

Description

Associates a billing plan with a subject.

Relationships

No relationships available.

Fields

Resource: features-plans

Base URL

/rest/v1/features/plans

Available methods: GET, PATCH, POST

Description

Manage feature plans.

Relationships

No relationships available.

Fields

Resource: features-plansvideo

Base URL

/rest/v1/features/plansvideo

Available methods: GET, PATCH, POST, DELETE

Description

Manage feature prices for video associated with a specific Great Plains account.

Relationships

No relationships available.

Fields

Resource: features-prices

Base URL

/rest/v1/features/prices

Available methods: GET, PATCH, POST, DELETE

Description

Manages feature prices which allow administrators to set prices for each feature plan, feature, and device type.

Relationships

No relationships available.

Fields

Resource: goldmine-leads

Base URL

/rest/v1/goldmine/leads

Available methods: GET

Description

View goldmine leads information.

Relationships

Fields

Resource: helix-cache-mfd

Base URL

/rest/v1/helix/cache/mfd

Available methods: GET, DELETE

Description

Retrieve and delete helix cached mfd data. If mfd is unknown, or a deserialization error occurs, then raw data bytes will be return in the data field, and name field will be null. If successful, data will hold the deserialized mfd object./n/r/n/rUsers below system level REQUIRE deviceId filter! Filter will be scanned for deviceIds and authorization will be checked. Top level deviceId field will be replaced with the checked authorized device list (deviceId: {$in: [ids]}). Regex and wildcard deviceIds not allowed

Relationships

No relationships available.

Fields

Resource: helix-ha-nodes

Base URL

/rest/v1/helix/ha/nodes

Available methods: GET, PATCH, POST, DELETE

Description

Create, retrieve, and update Helix home automation nodes.

Relationships

No relationships available.

Fields

Resource: helix-users

Base URL

/rest/v1/helix/users

Available methods: GET, PATCH

Description

View helix users associated with device.

Relationships

Fields

Resource: oauth-accesstokens

Base URL

/rest/v1/oauth/accesstokens

Available methods: GET, POST, DELETE

Description

View and delete OAuth access tokens that have been generated for current user.

Relationships

No relationships available.

Fields