Guides

Standard Alarms

ℹ️Geographic Coverage

The Noonlight Dispatch API is only supported in the US (all 50 states)

1. Set up your developer account

First, you need to sign in to our developer portal to retrieve your sandbox server token. This server token will be used to interact with the Dispatch API from your backend services.

⚠️

Your server token is considered sensitive and it is your responsibility to protect it. It should not be in client-side source code or configs.

2. Create your first sandbox alarm

“Creating an alarm” with the Dispatch API will kick off the designated dispatching process for your specific use case. In its most basic form, emergency services will be dispatched to the location provided.

 
In order to create your first alarm, you will need to make sure you have:

  • Associated individual’s name
  • Verified phone number
  • Location (accept geo-coordinates or address)
  • PIN (optional)
  • Type of emergency services (optional; defaults to police)

If you have additional information about the individual (height, weight, DOB, etc.) you can add that information with our update person endpoint.

⚠️

Locations

For static alarms associated with an address (home or businesses), address is required

ℹ️

PIN

We generally encourage partners to require a PIN for end user cancelation of alarms. That said, this is not a requirement. Should you choose to leverage a PIN to verify the cancelation of an alarm, you would need to pass that information in when creating the alarm.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'

const alarm = await request({
  method: 'POST',
  url: 'https://api-sandbox.noonlight.com/dispatch/v1/alarms',
  auth: { bearer: token },
  body: {
    location: {
      address: {
        line1: "123 Some Street",
        city: "St. Louis",
        state: "MO",
        zip: "63101"
      }
    },
    name: "John Smith",
    phone: "15554440003",
    pin: "1234"
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
     "location":{
        "address":{
           "line1":"123 Some Street",
           "city":"St. Louis",
           "state":"MO",
           "zip":"63101"
        }
     },
     "name":"John Smith",
     "phone":"15554440003",
     "pin":"1234"
  }'

3. Updating the alarm

Once the alarm is created, you have the ability to pass in additional information which can be leveraged to enhance the efficacy of the resolution process. With more information, we have the ability to verify the alarm, contact other household members to cancel/verify the alarm, etc.

Examples of the types of information that can be added to an alarm are below:

  • Update the location (required in situations where location is dynamic)
  • Add additional people to the alarm
  • Add event specific data:
    • Type and name of the device associated with alarm origination
    • Type, name, time of subsequent and likely related events

Details related to each of the items above can be found below.

3.1 Updating the alarm location (not required for static alarms)

ℹ️

If you are creating an alarm for a home or business, you should not need to implement this.

If your use case requires dispatching on a non-static emergency location, you can send location updates to the Dispatch API.

If you are sending location updates, we recommend:

  • No more frequent than every 10m of displacement or every 10 seconds
  • Location accuracy of <= 75m
  • Stop sending location updates after the alarm is canceled
import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/locations`,
  auth: { bearer: token },
  body: {
    coordinates: {
      lat: 32.3418,
      lng: -86.1409,
      accuracy: 5
    }
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/locations \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
     "coordinates":{
        "lat":32.3418,
        "lng":-86.1409,
        "accuracy":5
     }
  }'

3.2 Adding additional people to an alarm (optional)

If you would like to notify or allow people other than the primary user to cancel the alarm, for example if you’re creating a home alarm and want to allow household members to cancel, then you can do so using the create people endpoint. We will handle reaching out to the additional people as appropriate for your use-case.

In order to add additional people, you will need to have:

  • Associated individual’s name
  • Verified phone number
  • PIN (optional)

ℹ️

Currently there is no limit on how many people you can add to an alarm, but you can only call this endpoint once per alarm.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/people`,
  auth: { bearer: token },
  body: [
    {
      name: "Sue Smith",
      phone: "14445550003"
    },
    {
      name: "Sam Smith",
      phone: "15554440002"
    }
  ],
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/people \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[
    {
      "name":"Sue Smith",
      "phone":"14445550003"
    },
    {
      "name":"Sam Smith",
      "phone":"15554440002"
    }
  ]'

3.3 Adding the triggering event to an alarm (optional)

Adding “triggering event” data to an alarm allows Noonlight to provide additional context to users and first responders to aid in the emergency resolution process. “Triggering event” data is data related to the detection of the potential emergency (eg. front door sensor opened).

Event TypeDescription
alarm.device.activated_alarmWhen triggered automatically by a sensor
alarm.person.activated_alarmWhen triggered manually by a person on a sensor event within your application
import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/events`,
  auth: { bearer: token },
  body: [
    {
      meta: {
        attribute: "smoke",
        value: "detected",
        device_model: "some_model",
        device_name: "Kitchen Smoke Detector",
        device_manufacturer: "some_manufacturer"
      },
      event_type: "alarm.device.activated_alarm",
      event_time: "2020-04-02T08:11:36Z"
    }
  ],
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/events \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[
    {
      "meta":{
        "attribute":"smoke",
        "value":"detected",
        "device_model":"some_model",
        "device_name":"Kitchen Smoke Detector",
        "device_manufacturer":"some_manufacturer"
      },
      "event_type":"alarm.device.activated_alarm",
      "event_time":"2020-04-02T08:11:36Z"
    }
  ]'

3.4 Adding events to an alarm (optional)

Similar to “event triggering” data, there is often additional information that is valuable for effectively addressing an emergency. Examples include: video clips, motion sensor detecting motion in the kitchen shortly after a contact sensor breaking initiated the alarm, etc.

We surface this information in the dispatching dashboard which we expose to both our dispatchers and first responders.

Event TypeDescription
alarm.device.value_changedEvents that happened after the alarm was created
import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/events`,
  auth: { bearer: token },
  body: [
    {
      meta: {
        attribute: "contact",
        value: "open",
        device_model: "some_model",
        device_name: "Front Door Contact Sensor",
        device_manufacturer: "some_manufacturer"
      },
      event_type: "alarm.device.value_changed",
      event_time: "2020-04-02T08:12:36Z"
    }
  ],
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/events \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[
    {
      "meta":{
        "attribute":"contact",
        "value":"open",
        "device_model":"some_model",
        "device_name":"Front Door Contact Sensor",
        "device_manufacturer":"some_manufacturer"
      },
      "event_type":"alarm.device.value_changed",
      "event_time":"2020-04-02T08:12:36Z"
    }
  ]'

4. Digesting status updates via webhooks (optional)

After an alarm is created, Noonlight sends webhooks for actions taken by Noonlight dispatchers throughout the handling of an alarm - you can view those events and descriptions below. They are typically leveraged to modify UX or for reporting purposes.

Event TypeDescription
alarm.status.canceledThe alarm being canceled by the user through the Noonlight dispatcher via text/call.
alarm.closedThe alarm being closed by the Noonlight dispatcher.
alarm.psap_contactedAn outbound call to the PSAP. This event can happen multiple times.

ℹ️

Noonlight includes a signature in each webhook’s X-Noonlight-Signature header. This allows you to verify that the webhooks were sent by Noonlight, not a third party. To verify signatures, you can compare the X-Noonlight-Signature header with the Base64 encoded HMAC hash of the webhook body - if they match, then the webhook came from Noonlight. You can see an example of how to do this in Node.js below.

import http from 'http'
import express from 'express'
import bodyParser from 'body-parser'
import { createHmac } from 'crypto'

const app = express()

app.server = http.createServer(app)

app.use(bodyParser.json())

app.post('/webhook', (req, res) => {
  
  // See your secret here: https://developer.noonlight.com/app/dashboard
  const webhookSecret = 'somesecret'
  
  const signature = createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('base64')
  
  if (signature === req.get('X-Noonlight-Signature')) {
    return res.sendStatus(200)
  }
  
  res.sendStatus(401)
})

app.server.listen(process.env.PORT, () => {
  console.log(`Started on port ${app.server.address().port}`)
})

export default app

5. Canceling alarms (optional)

Typically this is user initiated, enabled by you exposing the ability for a user to request to cancel; but can also be done without user involvement in situations where your platform is confident the alarm is not associated with an emergency.

User’s always have the ability to cancel via text/call with Noonlight dispatchers.

If the user cancels the alarm after emergency services have already been dispatched to the PSAP, our request to cancel could be ignored and a wellness check on the user might still be conducted. This is at the discretion of the PSAP, but we will always notify the PSAP that the user has canceled.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/status`,
  auth: { bearer: token },
  body: {
    status: "CANCELED",
    pin: "1234"
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/status \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
     "status":"CANCELED",
     "pin":"1234"
  }'

6. Creating a monitoring certificate for your user (optional)

ℹ️

Only relevant for Pro-Monitoring and Video Monitoring within context of home security systems

Most professionally monitored home security systems qualify consumers for home insurance discounts. To apply for the discount, consumers need to provide their home insurance provider with a monitoring certificate provisioned by their monitoring provider (Noonlight).

In order to create a monitoring certificate for your user, you will need to make sure you have:

  • Location (address only)
import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'

const alarm = await request({
  method: 'POST',
  url: 'https://api-sandbox.noonlight.com/dispatch/v1/certificates',
  auth: { bearer: token },
  body: {
    address: {
      line1: "123 Some Street",
      city: "St. Louis",
      state: "MO",
      zip: "63101"
    }
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/certificates \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "address":{
      "line1":"123 Some Street",
      "city":"St. Louis",
      "state":"MO",
      "zip":"63101"
    }
  }'

Updated 3 months ago