Using the Emergency API

Owned by Mark Fernie
Last updated: Dec 11, 2024 by Blake Irving
2 min read

Vivi has an API key that can be used with your existing emergency management system to trigger and cancel an emergency within Vivi.

Please note: For the Vivi Emergency API to operate, your existing emergency management system needs to be able to output a web-based trigger (HTTPS GET or PUT methods). Please refer to the manufacturer’s instructions of your system for more information on if this is available.

Getting the API key

You can request your API key by raising a support request within Vivi Central: https://admin.vivi.io/support

In the triggers, you will need to insert your Emergency Type ID and have the option of including the Location ID. The Emergency Type ID is the name of the emergency as shown in Vivi Central. Emergency types can be viewed and edited at: https://admin.vivi.io/emergencies/emergency-types. The Location ID is the name of a location as shown in Vivi Central. Locations and can be viewed and edited at: https://admin.vivi.io/organisations/locations.

Trigger an Emergency

Your emergency management system needs to output the following URL to trigger an emergency:

https://api.vivi.io/api/public/v1/emergencies/trigger?key=<api_key>&type=<emergency_type_id>&location=<location_id>

<api_key>: Organisation API key – Required
<emergency_type_id>: ID of emergency type to trigger – Required
<location_id>: ID of location to trigger emergency at - Optional, trigger organisation wide emergency if not provided

The location ID provided in the URL must be for a top level Location. Triggering Emergencies at the sub-location level is not supported.

Cancelling an Emergency

Your emergency management system needs to output the following URL to cancel an emergency:

https://api.vivi.io/api/public/v1/emergencies/cancel?key=<api_key>&type=<emergency_type_id>&location=<location_id>

Checking Active Emergency Types

Your emergency management system needs to read from the following URL to check active emergency types:

https://api.vivi.io/api/public/v1/emergencies/status?key=<api_key>&location=<location_id>

Tracking Emergencies

The Emergencies page in Vivi Central can be used to view and cancel currently active emergencies and stores a full history of previously run emergencies. This page can be accessed at: https://admin.vivi.io/emergencies

Troubleshooting

When testing the emergency API from the command line or terminal, you may find that a valid Emergency API URL causes a 400 Bad Request error to be returned. This may be because your terminal is interpreting ? or & as special characters. In this case, it may be necessary to wrap the URL in quotes.

For example, if you’re using wget:

wget "https://api.vivi.io/api/public/v1/emergencies/trigger?key=my_key&type=9716eec6-112f-4940-b1b5-16f3d66ca2ea&location=6e7873b3-05e4-4ac6-8719-db049d53fbee"