Crisisworks has a mature web services API that provides REST and RPC access to key data and functionality. This document provides details for system integrators to develop clients to connect, extract data and control Crisisworks.

1 Introduction
2 Working with Authentication
- 2.1 Crisisworks account & Duty Status
- 2.2 Fetching an API token
  - 2.2.1 Inputs
  - 2.2.2 Results
  - 2.2.3 Example: calling the "register" command to fetch an API token
- 2.3 Using a token to access secure API commands
  - 2.3.1 Example: supplying the token in the Authorization header
3 Working with RPC APIs
4 Working with REST APIs
- 4.1 Collections
- 4.2 Fetching a single record
- 4.3 Fetching a collection of records
- 4.4 Searching and filtering records
- 4.5 Paginating records
- 4.6 Submitting new records
- 4.7 Updating existing records
- 4.8 DELETE
5 API Command Reference
- 5.1 Asset (REST)
  - 5.1.1 GET Parameters
- 5.2 Asset Type (REST)
- 5.3 Asset Lookup
  - 5.3.1 Single Query Mode
  - 5.3.2 Multiple Query Mode
  - 5.3.3 Options
  - 5.3.4 Example: Look up a single address
  - 5.3.5 Example: Look up multiple addresses
- 5.4 Create Event (RPC)
  - 5.4.1 Parameters
- 5.5 Duty (RPC)
  - 5.5.1 Parameters
- 5.6 Event (REST)
  - 5.6.1 Fetch Individual Event
  - 5.6.2 Search Events
  - 5.6.3 Update Event
- 5.7 File Attachment (RPC)
- 5.8 Register Item (REST)
  - 5.8.1 GET Parameters
  - 5.8.2 Output
  - 5.8.3 POST|PUT|PATCH
  - 5.8.4 Matching assets
- 5.9 Audit Log
  - 5.9.1 GET Parameters
- 5.10 Register Item Media (REST)
- 5.11 Ping (RPC)
- 5.12 Device Registration (RPC) — Authentication
- 5.13 Resource (REST)
  - 5.13.1 GET Parameters
- 5.14 User (REST)
  - 5.14.1 GET Parameters
- 5.15 Participant (RPC)
  - 5.15.1 GET Parameters
- 5.16 Import (POST)
  - 5.16.1 Scheduling an import
  - 5.16.2 Checking import progress
- 5.17 Report (POST)
  - 5.17.1 Running a report
  - 5.17.2 Checking a report status
  - 5.17.3 Fetching report data
6 Further Examples

Introduction

Crisisworks offers a unified web services endpoint for both REST (Representational State Transfer) and RPC (Remote Procedure Call) commands. Some commands are RESTful while others implement an RPC interface. All commands use HTTPS as the transport, and support the common HTTP/1.1 verbs such as GET, POST, PUT, PATCH and DELETE.

The general format for accessing the API is:

https://site.crisisworks.com/api/adapter/command?param=value&token=XXX

This comprises the following components:

site	Your Crisisworks site URL
adapter	Your selected data adapter; this transforms the data to the appropriate format
command	The command to run
param	Zero or more parameters and their corresponding values — see each command for details
token	Your authentication token, if required.

The API supports different adapters to read and write the data contained within the HTTPS transport. The default and recommended transport is JSON, which reads and writes the data in JavaScript Object Notation.

Adapter	Format	Description

Adapter	Format	Description
json	Javascript Object Notation	The default and recommended adapter, whcih reads and writes JSON data using native Crisisworks JSON structures.
csv	Comma Separated Values	This adapter reads and writes data in CSV format, providing ready compatibility to many legacy systems. Due to the nature of CSV as a flat file format, complex linked structures cannot be represented, so it is only recommended for simpler integrations.
geojson	GeoJSON	A read-only adapter that returns JSON data in the open GeoJSON format. This provides ready compatibility for many geospatial platforms such as web mapping systems including OpenLayers and Leaflet.
binary	Binary	A binary response is used by some APIs (for example, file) to return the raw source file
rss	RSS XML	A read-only adapter that returns the data in RSS format with the geospatial extension. This provides ready compatibility for RSS readers and news ticker systems.

Example: Calling the "ping" diagnostic command

$ curl https://demo.crisisworks.com/api/json/ping

"2016-10-24T05:34:46+00:00"

Working with Authentication

Most APIs require authentication, and in order to use any authenticated API, you must first acquire a valid API token.

To do this, first call the register API command, and supply the user credentials to retrieve a token. From then on, supplying that token to authenticated API commands will perform the command on behalf of that user.

Crisisworks account & Duty Status

The API uses a regular Crisisworks account. We recommend that this account is only used for the API, as such give it a name like API User.

Ensure this user has the levels of access required to access the data it needs to view or edit for the specific registers.

If this API user is going to edit data in registers, the API user MUST BE ON DUTY in the event in one or more positions to have access to read or write data in the registers.

If the API user is only updating assets or asset contacts, this data is not in a register, so they don't need to be on duty in any events.

Fetching an API token

The register command takes a username and password and returns a token for use in using authenticated API commands.

Inputs

The register API command takes the following parameters in a JSON payload within a POST method:

Parameter	Type	Mandatory	Description

Parameter	Type	Mandatory	Description
uuid	string	Yes	A unique code that represents the connected device. For devices this is the device's UUID code. For servers, this should be the server's URL.
platform	string	Yes	A freetext string representing the type of connection — e.g. iPad, iPhone, Windows
version	string	Yes	The version of the client software
name	string	Yes	The name of the device — e.g. "Steve's iPad Pro"
username	string	Yes	The user username
password	string	Yes	The user's password
expiry	string	No	An optional date YYYY-MM-DD for token expiry, used for setting up integration endpoints. This must be within the overall configured expiry policy limits set for your service.

Results

If the user is successfully authenticated, the command returns a JSON object with the following values:

Key	Type	Description

Key	Type	Description
token	string	An API token which can be used to perform actions on behalf of a nominated user
htmlHtml	string	An HTML snippet that can be displayed in client software containing help and support information for Crisisworks

If the user's credentials are invalid, the server responds with a 401 HTTP error.

Example: calling the "register" command to fetch an API token

Example

$ curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
        "uuid": "$YOUR_DEVICE_UUID",
        "platform": "$YOUR_CLIENT_PLATFORM",
        "version": "1",
        "name": "$YOUR_CLIENT_NAME",
        "username": "$YOUR_USERNAME",
        "password": "$YOUR_PASSWORD"
        }' \
     "https://$SITE_URL/api/json/register"


{
    "token": "8162e97a0fabf76b3bf0b1bfa50e90e8",
    "helpHtml": "Visit <a target=\"_blank\"  href=\"http:\/\/www.crisisworks.com\/support\" target=\"_blank\">Crisisworks Online Support<\/a> for help and support"
}

Using a token to access secure API commands

Once you have acquired a token, it must be supplied to any calls requiring authentication by using the Authorization header. Note that the header must be in the following format (take special note of spaces):

Example: supplying the token in the Authorization header

It is also possible to supply the token and uuid as part of the request parameters, however this is discouraged.

Working with RPC APIs

RPC APIs are simply a remote call to procedure on the server.

They use GET for read actions and POST for write actions, and accept payload formats based on the adaptor in use (e.g. "json").

Example: calling the "ping" command

Example

Working with REST APIs

REST provides a consistent URI for access and manipulation of a specific data record.

Under REST, a single URI represents a data record, and the HTTP verb controls the manipulation according to the following table:

Method	Description	Example

Method	Description	Example
Collection Commands
GET	Returns a collection of items based on a filter	GET /api/json/item?event=123
POST	Creates a new item	POST /api/json/item
Record Commands
GET	Returns a single item	GET /api/json/item/id/1
PUT	Updates a single item	PUT /api/json/item/id/1
PATCH	Updates a single item with the supplied fields only	PATCH /api/json/item/id/1
DELETE	Deletes a single item	DELETE /api/json/item/id/1

Collections

The Crisisworks REST API returns either returns a single object or a collection of objects, based on its invocation.

Collections contain the following JSON structure:

In the collection structure:

models contains an array of individual model structures,
count contains the number of returned objects, and
total contains the total set (this will be different if you call the API with a limit and/or offset parameter to paginate the set).

Fetching a single record

Use the GET method and supply an 'id' parameter to fetch a single record.

Each command returns records of a specific schema, and the example below is made up and not valid. Consult the command reference for details of the specific model.

Example

Note: The contents of the record structure depends on the type of content being retrieved.

Fetching a collection of records

Fetching a collection of RESTful objects is achieved by calling its base URL without an identifier. e.g.

Filters can be added, depending on the object. e.g.

Example

Searching and filtering records

You can use our CQL query language to search and filter your records.

See our user guide for details: Searching and filtering
A data dictionary exists for each register, and you will find the link in the UI under the search box.

For example, the following is listed for Date Updated in the data dictionary for Recovery Case:

Attribute Label/Type	Field	Description	Examples

Attribute Label/Type

Field

Description

Examples

Last Updated Date (Date)

dateUpdated

Search by date the item was last updated

dateUpdated:<now-30d is less than 30 days from now

dateUpdated:2024-12-31 is the date 2024-12-31

dateUpdated:<2024-12-31 is earlier than the date 2024-12-31

dateUpdated:>2024-01-01 AND dateUpdated:<2024-12-31 is in the year 2024

dateUpdated:<2024-12-31T12:31:00 is before the date and time 2024-12-31 at time 12:31:00 GMT

To use CQL via an API you'll need to consider a few things:

The API does not have implicit filters like the user interface, so you'll probably want to also add in general CQL terms such as is:active and event.id:XX to constrain to certain other criteria. You can test these in the UI.
We're on the cusp of changing from V4 to V5 of Crisisworks in September – December 2024, and some of the advanced notation of CQL is changing between V4 and V5. We'll have a CW5 dictionary shortly for comparison, and the good news is most will remain the same, other than advanced usage such as querying on related objects.

A full example in CQL for Crisisworks 4 might be this — the following returns active records in event 22 updated in the last 30 days:

To run CQL in the V4 API, you url encode it and use a parameter called elasticsearch. In V5 this has been renamed to cql.

Paginating records

You can paginate large result-sets by taking note of the count and total values returned in the payload, and supplying limit and offset parameters in the request.

For example, to fetch 100 at a time:

Will return

You can then fetch the second set:

And the final set

Submitting new records

New records can be submitted using POST.

JSON Input follows the same structure as that returned from the GET API.
The JSON response reflects the final values of the record after being saved.
Possible error codes include 40x and 50x status codes. All have a human-readable message, and use http codes so you can follow that spec to know whether it's a temporary or permanent error.

Example

Note: it is not normal to submit such a short request, but it makes for a good example.

Updating existing records

To update an existing record, use PUT or PATCH.

PUT and PATCH work similarly, where:

PUT expecting a full record, while
PATCH expects a change-set.

Tip: When using PUT, missing data will be treated as if the value is set to null, and this will overwrite existing values at the server.

Possible error codes include 40x and 50x codes, as usual.

Example

DELETE

Delete can be called if the object supports it.

Certain RESTful commands may not allow deletions, in which case a 400 Bad Request will be returned. For those that do implement it, a 200 code will be returned on success, and 40x and 50x codes will be returned on failure.

Example

API Command Reference

The following public API commands are available:

API Command	URL	Type	Methods	Authenticated	Description

API Command	URL	Type	Methods	Authenticated	Description
asset	/api/json/asset	REST	GET, POST, PUT, PATCH, DELETE	Yes	Create, retrieve and delete assets from the system
asset-type	/api/json/asset-type	RPC	GET	Yes	Read-only access to look up asset types
create-event	/api/json/create-event	RPC	POST	Yes	A simple method to create events, usually based on existing templates
event	/api/json/event	REST	GET	Yes	Retrieve events and update them
file	/api/binary/file	RPC	GET, POST	Yes	Upload and retrieve file attachments. Note, this command only uses the binary adapter, and returns JSON on failure.
item	/api/json/item	REST	GET, POST, PUT, PATCH, DELETE	Yes	Create, retrieve and delete register items, which are the core operational record in Crisisworks.
log	/api/json/log	REST	GET	Yes	Read-only access to audit logs
media	/api/json/media	REST	GET, POST, PUT, PATCH, DELETE	Yes	Create, retrieve and delete media attachments on register items
ping	/api/json/ping	RPC	GET	No	A diagnostics command for debugging and uptime analysis
register	/api/json/register	RPC	POST	No	Register a username/password against a device and retrieve an API token
resource	/api/json/resource	REST	GET, POST, PUT, PATCH, DELETE	Yes	Create, retrieve and delete resources
user	/api/json/user	REST	GET, POST, PUT, PATCH, DELETE	Yes	Create, retrieve and delete users.
user-position	/api/json/user-position	RPC	POST	Yes	Update the current latitude/longitude of a user
participant	/api/json/participant	REST	GET	Yes	Search for participants by event, type and/or query string
import	/api/json/import	RPC	POST	Yes	Schedule an import job, or check on the status of a scheduled job.

These commands are mostly authenticated, and are either RPC or REST APIs. See below the more details on each command.

Asset (REST)

The asset REST command returns and manipulates assets in Crisisworks.

GET Parameters

Parameter	Key(s)	Type	Available Operators	Details

Parameter	Key(s)	Type	Available Operators	Details
Limit	limit	Number	-	When paginating, how many records to return
Offset	offset	Number	-	When paginating, which record to start from
Token	token	String	-	The API token to authenticate
ID	id id_operator	Integer	equals (default) in	Returns a record of a specific ID (equals), or a collection of records within a comma-separated list of IDs (in).
Contains	fulltext fulltext_operator	String	Contains (default) NotContains	Returns records containing the supplied text, as analysed by the full-text search parser.
Sounds Like	soundex	String	-	Returns records where the title sounds like the supplied string Aliases: name
Active	active	Boolean	-	Returns only active (or inactive) records based on supplied value
Type	type type_operator	String	Equals (default) In NotIn IsNotBlank IsBlank	Returns records matching the given asset type. For a list of asset types, see the asset-type API command.
Code	code	String	-	Returns records matching the given asset code
Is Impacted	isImpacted	Boolean	-	Returns records that have an active register item record in Crisisworks
Near	latitude longitude range	Number	-	Returns assets near the provided geospatial location.

Example

Asset Type (REST)

This command fetches the available asset types.

This command is read-only and only supports the GET REST method.

Example

Asset Lookup

The Asset Lookup API provides search and lookup capability for Crisisworks API clients, using the same underlying algorithms used by the item import and asset matching systems.

There are two modes of operation:

Single query mode — look up a single asset
Multiple query mode — process multiple items in a batch

Single Query Mode

Parameter	Purpose

Parameter	Purpose
query	The string to look up as an asset
output	One of id or asset (default)
key=val	A range of options can be supplied to fine-tune the system. See below for details of the available option keys.

Multiple Query Mode

To process multiple queries at once, construct a JSON payload and pass it via POST.

The result of either call will be formatted in an object map of results, keyed based on the supplied code parameter, or as a 1-based record count if no code was supplied. The object will either be a full asset object (output=asset, or an asset ID output=id).

Options

These additional options are available

Parameter	Purpose

Parameter	Purpose
mode	One of the modes described here. The default is the soundex mode.
assetClass	Optionally limits results to only those matching this asset class.
useExternalLookups	Defaults to true, and engage the Google POI search as a last resort if other methods have failed.
maxRank	For soundex searches, the maximum rank (1 = exact, 2 = all word in order, 3 = all words in any order). Default is 2.
fallbackMode	An optional second fallback mode for if the primary fails
codeField	For mode=code, this is the field to match upon (e.g. propnum)
upgradeExternalLookupToInternalAsset	If the fallback POI system is invoked, you can optionally attempt to upgrade the result to a proper asset. To use this feature, you need to also specify thee assetClass. You may also want to set the geocoderOptions to rooftop-level resolution (seee below), otherwise you will get nearby but not exact properties if the search returns only a nearby road.
geocoderOptions	For useExternalLookups, this is a JSON options array to configure the plugin. The most useful option is restrict matches to houses only:

Example: Look up a single address

Result

Example: Look up multiple addresses

Result:

Create Event (RPC)

This command provides an easy way to create events, usually based on existing event templates

Example

Parameters

Key	Type	Required?	Default	Details

Key	Type	Required?	Default	Details
templateId	Number	No	ID of "Basic" template	The template event ID to base this new event on.
title	String	Yes	(None)	The title of the event
description	String	No	(None)	An optional description of the event
startDate	Date Time String	No	Current date/time	The time that the event is scheduled to begin
endDate	Date Time String	No	(None)	The time that the event is scheduled to end
status	Number	No	The default state for new events (Usually 1 → "Open"	The status that the event should be set to when created
severity	Number	No	1	1=Test only, 2=Low Severity, 3=Moderate Severity, 4=High Severity
goOnDuty	Number	No	1	Should the user creating the event automatically go on duty for all candidate positions in the event? 1 = Yes, 0 = No

Duty (RPC)

This command provides a way to go on or off duty in an event

Example

Parameters

Key	Type	Required?	Default	Details

Key	Type	Required?	Default	Details
participantId	Number	Yes	(None)	The ID of the participant to go on duty as
onDuty	Number	Yes	1	0 = go off duty, 1 = go on duty

Event (REST)

This command fetches available events, and allows updating.

Fetch Individual Event

Example

Search Events

Example

Parameters

Filter	Keys	Type	Operators	Details

Filter	Keys	Type	Operators	Details
limit	Limit	Number	-	When paginating, how many records to return
offset	Offset	Number	-	When paginating, which record to start from
token	Token	String	-	The API token to authenticate
ID	id id_operator	Number	equals (default) notEquals in	Set id_operator to the desired operator if changing from the default
Contains	fulltext fulltext_operator	String	Contains (default) NotContains	Set fulltext_operator to the desired operator if changing from the default
Status	status status_operator	String	Equals (default) In NotIn IsNotBlank IsBlank IsStatusActive IsStatusInactive	Set status_operator to the desired operator if changing from the default
Active	active	Boolean	None	Aliases: isActive
Title	title title_operator	String	Equals NotEquals Contains (default) NotContains BeginsWith IsBlank IsNotBlank	Set title_operator to the desired operator if changing from the default
Severity	severity severity_operator	Number	Equals (default) In NotIn IsNotBlank IsBlank	Set severity_operator to the desired operator if changing from the default
Registers	registers registers_operator	String	Equals (default) In NotIn IsNotBlank IsBlank	Set registers_operator to the desired operator if changing from the default
Started After	startDateAfter startDateAfter_operator	Date Time String	Equals DateFuzzy NotEquals IsBlank IsNotBlank DateBefore DateBeforeEquals DateAfter DateAfterEquals (default) DateBeforeRel DateAfterRel	Set startDateAfter_operator to the desired operator if changing from the default
Started Before	startDateBefore startDateBefore_operator	Date Time String	Equals DateFuzzy NotEquals IsBlank IsNotBlank DateBefore DateBeforeEquals DateAfter DateAfterEquals (default) DateBeforeRel DateAfterRel	Set startDateBefore_operator to the desired operator if changing from the default
Event Structure	descendants descendants_operator	String	NestedSetHasDescendants (default) NestedSetNoDescendants	Set descendants_operator to the desired operator if changing from the default
Tag	tag tag_operator	String	Tagged (default) NotTagged	Set tag_operator to the desired operator if changing from the default
Location	geo geo_operator geo_polygon geo_radius geo_centre	Geo	GeoWithinPolygon (default) GeoWithinRange GeoWithinBoundingBox	Set geo_operator to the desired operator if changing from the default
Template	isTemplate	Boolean	None
Global	isGlobal	Boolean	None
Counter ID	counter	Number	None	Aliases: counterId
User Participation	participation participation_operator	String	(default) active notActive ever can	Set participation_operator to the desired operator if changing from the default

Example: Fetch the most recent event

Update Event

Parameters

Key	Type	Required?	Details

Key	Type	Required?	Details
id	Number	Yes	ID of the event to update
title	String	No	Changed title
description	String	No	Changed description
startDate	Date Time String	No	Changed start date
endDate	Date Time String	No	Changed end date
status	Number	No	New status (generally, 1 = open, -1 = closed)
severity	Number	No	1=Test only, 2=Low Severity, 3=Moderate Severity, 4=High Severity

Example: Close an event and update its description

File Attachment (RPC)

Documentation is currently unavailable for this command

Register Item (REST)

A RESTful command to access and manage register items, which are the primary business object within the system.

GET Parameters

Filter	Keys	Type	Operators	Details

Filter	Keys	Type	Operators	Details
limit	Limit	Number	-	When paginating, how many records to return
offset	Offset	Number	-	When paginating, which record to start from
token	Token	String	-	The API token to authenticate
Contains	contains contains_operator	String	Contains (default) NotContains	Aliases: search; Set contains_operator to the desired operator if changing from the default
Record ID	itemId itemId_operator	String	equals (default) notEquals in	Aliases: id; Set itemId_operator to the desired operator if changing from the default
System ID	systemId systemId_operator	String	Equals (default) NotEquals Contains NotContains BeginsWith IsBlank IsNotBlank	Set systemId_operator to the desired operator if changing from the default
Type	type type_operator	String	Equals (default) In NotIn IsNotBlank IsBlank	Aliases: class; Set type_operator to the desired operator if changing from the default
User ID	userId userId_operator	String	equals (default) notEquals in CurrentUser NotCurrentUser	Aliases: user; Set userId_operator to the desired operator if changing from the default
Event	eventId eventId_operator	String	InEvent (default) InSubEvent InEventOrSubEventOrGlobal InActiveEvent ActiveParticipating Active Any	Aliases: event; Set eventId_operator to the desired operator if changing from the default
Since	since since_operator	String	Equals DateFuzzy NotEquals IsBlank IsNotBlank DateBefore DateBeforeEquals DateAfter (default) DateAfterEquals DateBeforeRel DateAfterRel	Set since_operator to the desired operator if changing from the default
Until	until until_operator	String	Equals DateFuzzy NotEquals IsBlank IsNotBlank DateBefore (default) DateBeforeEquals DateAfter DateAfterEquals DateBeforeRel DateAfterRel	Set until_operator to the desired operator if changing from the default
Is a template item	isTemplate	String	None
Counter ID	counter	String	None	Aliases: counterId
	eventImplicit eventImplicit_operator	String	InEvent (default) InSubEvent InEventOrSubEventOrGlobal InActiveEvent ActiveParticipating Active Any	Set eventImplicit_operator to the desired operator if changing from the default

Output

Example output of all active fpn items. Note, the first item has an attached asset and shows how the extra fields are returned.

The external identifier for the item assets depends on what code field is configured for the site. Prior to 2019 this was exposed via the asset_code field. From 2019, one of the sub-fields from asset_extra should be used as appropriate e.g asset_extra.propnum.

Example

POST|PUT|PATCH

Creating (POST) and updating (PUT or PATCH) items uses a similar structure to the GET response, but only sends one item.

For example:

Matching assets

When linking an asset to an item, you have three approaches:

set assetId to the Crisisworks internal ID for the asset,
set asset_friendly to a name, and have Crisisworks look up the asset using a its search algorithm, or
set asset_lookup to look up a foreign key for the asset, that will match one of the stored foreign keys in the asset's extra property. For example, you can look up by propnum or crefno, if those foreign keys are in your asset dataset. To determine which code to look up, you can specify asset_codefield.

Example: looking up a property by propnum.

Example: looking up a property by a name search:

Audit Log

This fetches a collection of audit logs, either for a given object (with itemId specified), a given event (with eventId specified) or across the system.

GET Parameters

Filter	Keys	Type	Operators	Details

Filter	Keys	Type	Operators	Details
limit	Limit	Number	-	When paginating, how many records to return
offset	Offset	Number	-	When paginating, which record to start from
token	Token	String	-	The API token to authenticate
ID	id id_operator	String	Equals (default) NotEquals Contains NotContains BeginsWith IsBlank IsNotBlank	Set id_operator to the desired operator if changing from the default
Event	eventId eventId_operator	String	InEvent (default) InSubEvent InEventOrSubEventOrGlobal InActiveEvent ActiveParticipating Active Any	Aliases: event; Set eventId_operator to the desired operator if changing from the default
Scope	scope	String	None
Item	itemId	String	None	Aliases: item
Organisation	organisationId	String	None	Aliases: organisation
Participant	participantId	String	None	Aliases: participant
Position	positionId	String	None	Aliases: position
Register	registerId	String	None	Aliases: register
User	userId userId_operator	String	equals (default) notEquals in CurrentUser NotCurrentUser	Set userId_operator to the desired operator if changing from the default
User Object	userObjectId	String	None
Assignment	assignmentId	String	None	Aliases: assignment
Event (Implicit)	eventImplicit eventImplicit_operator	String	InEvent (default) InSubEvent InEventOrSubEventOrGlobal InActiveEvent ActiveParticipating Active Any	Set eventImplicit_operator to the desired operator if changing from the default

Example

Register Item Media (REST)

Ping (RPC)

This command provides simple diagnostics, and is the "hello world" of API connectivity.

Example

Device Registration (RPC) — Authentication

This command authenticates a username/password, registers the device and returns an API token for that device.

This command is an RPC command that supports the POST method.

Example

Resource (REST)

This command provides a RESTful way to access and manage resources within the system.

GET Parameters

Filter	Keys	Type	Operators	Details

Filter	Keys	Type	Operators	Details
limit	Limit	Number	-	When paginating, how many records to return
offset	Offset	Number	-	When paginating, which record to start from
token	Token	String	-	The API token to authenticate
ID	id id_operator	String	equals (default) notEquals in	Set id_operator to the desired operator if changing from the default
Contains	fulltext fulltext_operator	String	Contains (default) NotContains	Set fulltext_operator to the desired operator if changing from the default
Type	type type_operator	String	Equals (default) In NotIn IsNotBlank IsBlank	Set type_operator to the desired operator if changing from the default
Status	status status_operator	String	Equals (default) In NotIn IsNotBlank IsBlank IsStatusActive IsStatusInactive	Set status_operator to the desired operator if changing from the default
Organisation	organisationId organisationId_operator	String	In (default) NotIn	Set organisationId_operator to the desired operator if changing from the default
Category	categoryId categoryId_operator	String	Equals (default) In NotIn IsNotBlank IsBlank	Set categoryId_operator to the desired operator if changing from the default
Tagged	tag tag_operator	String	Tagged (default) NotTagged	Set tag_operator to the desired operator if changing from the default

Example

User (REST)

Provides a RESTful way to access and manage users.

GET Parameters

Filter	Keys	Type	Operators	Details

Filter	Keys	Type	Operators	Details
limit	Limit	Number	-	When paginating, how many records to return
offset	Offset	Number	-	When paginating, which record to start from
token	Token	String	-	The API token to authenticate
Word Search	fulltext fulltext_operator	String	Contains (default) NotContains	Set fulltext_operator to the desired operator if changing from the default
ID	id id_operator	String	equals (default) notEquals in	Aliases: id; Set id_operator to the desired operator if changing from the default
Online	online	Boolean	None
On Duty	onduty	Boolean	None
Active	active	Boolean	None
On Call	oncall	Boolean	None
Tags	tag tag_operator	String	Tagged (default) NotTagged	Set tag_operator to the desired operator if changing from the default
Organisation	organisationId organisationId_operator	String	In (default) NotIn	Set organisationId_operator to the desired operator if changing from the default
Competencies	roleId roleId_operator	Number	RelatedTo (default) NotRelatedTo	Set roleId_operator to the desired operator if changing from the default
Receive SMS	receiveSMS	Boolean	None
Receive Email	receiveEmail	Boolean	None

Example

Participant (RPC)

A read-only command to search for participants by event, type, and optional query string (eg users name)

GET Parameters

Key	Type	Required?	Default	Details

Key

Type

Required?

Default

Details

event

Number

Yes

(None)

The ID of the event.

query

String

No

(None)

The full name of a participant.

types[]

String

No

(None)

The type of participants to return, including 'User', 'Resource' and 'Position'.

This key may be repeated to return multiple participant types.

Import (POST)

An RPC command to schedule an import job, or to check the status of an existing import job.

To learn about importing, see the section Importing Data into Crisisworks. This API provides an endpoint to replace the user interface version of the import process described in that support article.

Scheduling an import

Parameters

Key	Type	Required	Default	Notes

Key	Type	Required	Default	Notes
General settings
mode	string	Y		Must be set to schedule
importType	string	Y		One of `item`, `user` or `asset`. Most types are "item" imports.
importRule	string	Y		The rule name. See the inline import documentation in the Crisisworks Import user interface for details, or contact Datalink's service desk for information.
Data
data	string	Y		Either plaintext or a base64-encoded string of import data
dataType	string	N		Not usually required, but can help the import system determine the file type in the event it cannot automatically determine the file type. Advice can be provided by Datalink's service desk if needed.
encoding	`plain`\|`base64`		`plain`	Sets the type of `data`. For CSV imports use `plain`, otherwise base64 encode the file.
Rule processing
matchingId	string	N		This is the name of the field used to match existing records. Valid field names are based on the record being imported. Examples for importing register items: `id`: is the Crisisworks ID of the record `code`: for register items, this is the asset's configured code (e.g. PROPNUM). This configuration is system-wide, so consult Datalink's service desk for your system's configuration. `assetId`: for register items, this is the linked Crisisworks Asset ID of the record
overwriteRule	string	N		Defines the rule used for overwriting matched records: `updateOnly`: If a record matches then update it. If it doesn't match, do not insert it. `insertOnly`: If a record matches then skip it. If it doesn't match, insert it. `updateAndInsert`: If a record matches then update it. If it doesn't match, insert a new record. `deleteAndInsert`: Delete all existing records and insert all records as new records.
eventId	integer	Depends		Required for import types that are stored within events (e.g. items, contacts, cases, documents). Not required for import types such as users, assets and resources.
regionId	integer	Depends		Required for import types that are stored within events (e.g. items, contacts, cases, documents). Not required for import types such as users, assets and resources.
Import settings
dryRun	integer (0 or 1)	N	0	Set to 1 to have the system perform a dry run
rollbackOnError	integer (0 or 1)	N	0	Set to 1 to have the import system roll back the changes if any error occurs
importTag	string	N		If set, all records will be tagged with this tag.
message	string	N		If set, the audit log will contain this message.

Supported data types

This API receives its data in a JSON payload, however imports are generally accepted in different formats such as Shapefile or CSV. The API accepts its data by specifying the parameters data, dataType and encoding.

The two most common file formats are CSV and Shapefile.

For CSV

prepare the data by escaping special characters as per the JSON specification (e.g. backslash quotes, carriage returns, etc),
supply the escaped data in data
set encoding to plain
set dataType to csv

For Shapefile

zip the shapefile files into a single zip file
base64 encode the zip file
supply the base64 encoded string as data
Set encoding to base64
Set the dataType to zip

The API will return an ID on success. This ID can be used to query the progress of the import job.

Checking import progress

If called without an id parameter, the API will return a summary of all import jobs. If called with an id parameter, it will return specifics about that job.

You will typically poll this API once a job has been submitted, until the job completes. Please poll no more than once per 60 seconds to not disrupt the user experience.

Key	Type	Description

Key	Type	Description
code	integer	An HTTP result code. Expect 200 for success.
id	integer	The process ID
status	string	A simplified process status, one of `NOT_STARTED`, `RUNNING`, `COMPLETE` or `FAILED`.
dateCreated	date	The date in GMT that the job was scheduled
dateCompleted	date	The date in GMT that the job finished processing
userId	string	The user that the job ran as
result	string	The result of the import job, as an HTML formatted string

Report (POST)

The /api/json/report API provides report run automation, and allows users to run a report, check its run status and download the results.

To run a report and retrieve the results:

run it — triggers the report to run asynchronously
check status — monitor the report execution via polling to know when it has completed
fetch it — pull down the report results in a number of formats

Running a report

To enqueue a report to run, call the following API.

This API call accepts a JSON document with either a reportId of a known report in the system, or a reportInstanceId of a previous run to repeat. It also optionally allows params to be specified to provide detailed configuration of the report.

Example 1: run a report by its ID

Example 2: run a report based on a previous run

This method is most convenient because you can set up a report’s parameters via the reporting user interface, and then re-run it with the same set of filters, columns and format options. If params are provided, they will overwrite any params of the report instance being re-run.

Results

If successful, the result will return the report instance ID scheduled to run.

Checking a report status

Reports run asynchronously and some can take a while to run, so you can poll this API to check the job’s status.

Results

When initially queued the results will return a QUEUED status:

When complete it will return additional data:

Note the params attribute which will show the params used to run the report. This is useful to return a structured set of parameters from a previous report run, which you can then modify when crafting your own API calls.

Fetching report data

To fetch report data, call the API in fetch mode and specify the reportInstanceId and a format.

Example: fetching a report in JSON

The results of the /api/json/report call with the fetch mode is a JSON document of the same shape as for the status mode, but with an additional contents property.

This contents property contains one of the following:

for the json format, the report data in a nested JSON format
for all other formats, the binary file is returned in Base-64 encoding

For example, the above example will return the following:

This JSON format provides a tabular (e.g. two-dimensional) data structure in a parsable format, along with a built-in data dictionary for each field.

$schema — a JSON Schema document URL to validate the content
name — the name of the report
meta — a series of metadata values indicating the data quality of the report (as set in the report instance at run-time)
filter — all available report filters and their set values for this report
spec — a data dictionary of all the fields contained in each data row
data — the rows of data

By changing the format to any other supported format, the data is encoded into Base-64 and returned.

Example: fetching data using the binary adapter

Use the binary API adapter to download the report file in its raw format.

Available formats:

Format	Description

Format	Description
csv	A CSV representation of the data
html	A formatted HTML report (compatible reports only)
json	The JSON representation above
xlsx	An Excel spreadsheet

Example: downloading the CSV format directly

A response may look like this:

Different file types will have different Content-Type headers, and will contain binary data. To fetch these, use a tool such as wget or curl like any other HTTP resource of that type:

Further Examples

The following examples provide quick integrations for popular requirements.

Displaying all Fire Prevention Notices on a map using GeoJSON

This example displays a set of icons for each fire prevention notice record in Crisisworks on an OpenLayers map.

Steps

Obtain your authentication token
Prepare and test a URL to fetch the data
Add the URL into OpenLayers

Step 1

First, fetch an API token based on a user account with credentials that provide access to the FPN registers and event. This is described above in the section Working with Authentication.

Step 2

The following URL will fetch a live list of all FPN records for a given event. Replace site, token and event with your own values.

URL

Example: Testing the URL

Step 3

Add the URL above into your system as a GeoJSON layer. If developing on OpenLayers, this tutorial explains how to add a GeoJSON layer.

Fetching all Fire Prevention Notices to import into another system using CSV

This example downloads CSV data for import into another system

Steps:

Obtain your authentication token
Prepare and test a URL to fetch the data
Add the URL into OpenLayers

Step 1

First, fetch an API token based on a user account with credentials that provide access to the FPN registers and event. This is described above in the section Working with Authentication.

Step 2

The following URL will fetch a live list of all FPN records for a given event. Replace site, token and event with your own values.

Example

Step 3

Now consume the URL in your application.

Example

Importing asset contacts via the API

Example of importing asset contacts from a CSV file.

Note the data used in this example is embedded CSV within the JSON data. If you have a CSV file, look at the next example.

Uploading an import file

The following example shows how you may upload a CSV file to the import API, using BASH.

Adding images to Infrastructure Assessments

Attaching images to Register Items in Crisisworks happens in 2 steps.

Upload the image

First, the image needs to be be uploaded to Crisisworks. On successful upload, a file id is returned.

Example Request

Example Response:

The file id 289 from the response is used to update the register item.

Update the item to attached the file
The specific item then needs to be updated to include the file. In the case of an Infrastructure Item, we are adding to the "Damage Photos" - field name descriptionPhotos

Please note, when updating an item, all the required fields also need to be included in the payload, so you will need to get this data before making any updates.

In the instance of Infrastructure Assessment, the required fields are:

Field Name	Description

Field Name	Description
id	The item ID of the record being updated.
type	Should be set to "recoveryInfrastructure".
itemSchemaName	Set to "default".
infrastructureType	Set to the existing value for this field.
damageLevel	Set to the existing value for this field.
description	Set to the existing value for this field.
priority	Set to the existing value for this field.
eventId	Set to the existing value for this field.

Using Windows Command Prompt

Users may receive the following message when attempting to register an API Token when using Windows Command Prompt.

Windows command prompt has no support for single quotes like the Unix-like shells. As a result, you will need to replace the single quotes with double quotes AND escape them wherever necessary using back slashes.

API Integration Guide

On this page

Introduction

Working with Authentication

Crisisworks account & Duty Status

Fetching an API token

Inputs

Results

Example: calling the "register" command to fetch an API token

Example

Using a token to access secure API commands

Example: supplying the token in the Authorization header

Working with RPC APIs

Example: calling the "ping" command

Example

Working with REST APIs

Collections

Fetching a single record

Example

Fetching a collection of records

Example

Searching and filtering records

Paginating records

Submitting new records

Example

Updating existing records

Example

DELETE

Example

API Command Reference

Asset (REST)

GET Parameters

Example

Asset Type (REST)

Example

Asset Lookup

Single Query Mode

Multiple Query Mode

Options

Example: Look up a single address

Example: Look up multiple addresses

Create Event (RPC)

Example

Parameters

Duty (RPC)

Parameters

Event (REST)

Fetch Individual Event

Example

Search Events

Example

Parameters

Example: Fetch the most recent event

Update Event

Parameters

Example: Close an event and update its description

File Attachment (RPC)

Register Item (REST)

GET Parameters

Output

Example

POST|PUT|PATCH

Matching assets

Audit Log

GET Parameters

Example

Register Item Media (REST)

Ping (RPC)

Example

Device Registration (RPC) — Authentication

Example

Resource (REST)

GET Parameters

Example

User (REST)

GET Parameters

Participant (RPC)

GET Parameters

Import (POST)

Scheduling an import