/
Using the Emergency API

Using the Emergency API

Owned by Mark Fernie
Last updated: Apr 16, 2025 by Blake Irving
4 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. Please refer to the manufacturer’s instructions of your system for more information on if this is available.

By default, you can send an HTTPS POST request with a JSON payload. You can also check the flag to use HTTPS GET requests. Existing organisations with active API integrations have GET and PUT requests allowed.

Getting the API key

You can create your API key by going to Organisation > Integration page in Edit mode and clicking on Create button. If you cannot find this page, please reach out to Vivi support.

image-20250414-034659.png
image-20250414-034751.png
image-20250416-012934.png

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 on the Emergency Types page.

The Location ID is the name of a location, as shown in Vivi Central. Locations can be viewed and edited on the Locations page.

Trigger an Emergency

Your emergency management system needs to send a request to https://api.vivi.io/api/public/v1/emergencies/trigger endpoint with the following information

key: <api_key> (Required): Organization API key.
type: <emergency_type_id> (Required): ID of emergency type to trigger.
location: <location_id> (Optional): ID of the location to trigger the emergency at. Trigger organization-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.

POST Request (Preferred)

  • Endpoint URL:
    https://api.vivi.io/api/public/v1/emergencies/trigger

  • Headers:
    The Content-Type header is set to application/json because the request body is in JSON format.

  • Body (JSON):

{ "key": "api_key", "type": "emergency_type_id" "location": "location_id", }

For testing in a terminal, the following bash script can be used:

curl -X POST https://api.vivi.io/api/public/v1/emergencies/trigger \ -H "Content-Type: application/json" \ -d '{ "key": "api_key", "type": "emergency_type_id", "location": "location_id" // Omit or remove this line for an organization-wide emergency }'

GET Request

For security reasons, we recommend using POST requests with a JSON payload.

For GET requests, all parameters must be included directly in the URL as query parameters rather than in a request body. This means that the api_key, emergency_type_id, and (if provided) the location_id are appended to the URL in a key-value format.

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

Cancelling an Emergency

Your emergency management system needs to send a request to https://api.vivi.io/api/public/v1/emergencies/cancel endpoint with the following information

key: <api_key> (Required): Organization API key.
type: <emergency_type_id> (Required): ID of emergency type to trigger.
location: <location_id> (Optional): ID of the location to trigger the emergency at. Trigger organization-wide emergency if not provided.

Note: Passing all as the emergency_type_id, without a location_id will cancel all active emergencies within your organisation, regardless of emergency type. location_id can still be used in conjunction with all.

POST Request (Preferred)

  • Endpoint URL:
    https://api.vivi.io/api/public/v1/emergencies/cancel

  • Headers:
    The Content-Type header is set to application/json because the request body is in JSON format.

  • Body (JSON):

{ "key": "api_key", "type": "emergency_type_id" "location": "location_id", }

For testing in a terminal, the following bash script can be used:

curl -X POST https://api.vivi.io/api/public/v1/emergencies/cancel \ -H "Content-Type: application/json" \ -d '{ "key": "api_key", "type": "emergency_type_id", "location": "location_id" // Omit or remove this line for an organization-wide emergency }'

GET Request

For security reasons, we recommend using POST requests with a JSON payload.

For GET requests, all parameters must be included directly in the URL as query parameters rather than in a request body. This means that the api_key, emergency_type_id, and (if provided) the location_id are appended to the URL in a key-value format.

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 send a request to https://api.vivi.io/api/public/v1/emergencies/status endpoint with the following information

This is only available via a GET request, not PUT

key: <api_key>: Organization API key – Required
location: <location_id>: ID of location to check - Required

POST Request (Preferred)

  • Endpoint URL:
    https://api.vivi.io/api/public/v1/emergencies/status

  • Headers:
    The Content-Type header is set to application/json because the request body is in JSON format.

  • Body (JSON):

{ "key": "api_key", "location": "location_id", }

For testing in a terminal, the following bash script can be used:

curl -X POST https://api.vivi.io/api/public/v1/emergencies/status \ -H "Content-Type: application/json" \ -d '{ "key": "api_key", "location": "location_id" }'

Example responses:

{ "emergency_types": ["0c17f5c8-77e2-4a79-a03e-b4610fc610fc"] }
{ "emergency_types": [] }

GET Request

For security reasons, we recommend using POST requests with a JSON payload.

For GET requests, all parameters must be included directly in the URL as query parameters rather than in a request body. This means that the api_key, and location_id are appended to the URL in a key-value format.

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: Emergencies

Troubleshooting

When testing the emergency API GET requests 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=api_key&type=emergency_type_id&location=location_id"

 

Related content