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.

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

Authorization: BRAVO-AUTH uuid=YOUR_DEVICE_UUID, token=YOUR_TOKEN

Example: supplying the token in the Authorization header

$ curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=8162e97a0fabf76b3bf0b1bfa50e90e8" \ 
    https://demo4.crisisworks.com/api/binary/file?id=568373 > myfile.png

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

# call the "ping" RPC command
$ curl https://moira.crisisworks.com/api/json/ping

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

Example

# Call the "auth" RPC command to check the validity of a token
curl --data "uuid=$YOUR_USERNAME&token=$YOUR_TOKEN" $SITE_URL/api/json/auth

# Example
$ curl --data "uuid=dl&token=8162e97a0fabf76b3bf0b1bfa50e90e8" https://demo.crisisworks.com/api/json/auth
{
    "user": {
        "name": "David Jones",
        "userId": "dl",
        "roles": []
    }
}

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

{
    "models": {
        "1": { ... }
        "2": { ... }
        "3": { ... }
        "4": { ... }
        "5": { ... }
    },
    "count": 5,
    "total": "22608"
}

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.

GET /api/json/item/id/1

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

# fetch item id=1
curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" https://demo.crisisworks.com/api/json/item/id/1

{
    "id": "1",
    "eventId": "234",
    "due": null,
    "isSensitive": false,
    "itemSchemaName": "default",
    "userId": "myuser",
    "status": "10",
    "templateName": null,
    "costEstimate": "10000.00",
    "type": "recoveryInfrastructure",
    "title": "Small Rd (ACCESS RURAL) ",
    "address": "Small Rd (ACCESS RURAL) ",
    "geo": {
        "points": [
            {
                "longitude": "142.35820543",
                "latitude": "-36.84567206999998"
            }
        ],
        "polygons": [],
        "linestrings": []
    },
    "assetId": "72784",
    "assignee": 0,
    "_canEdit": true,
    "dateCreated": "2016-09-29T15:07:27+10:00",
    "dateUpdated": "2016-09-29T15:07:27+10:00",
    "isTemplate": false,
    "tags": "",
    "descriptionPhotos": [],
    "scopePhotos": [],
    "contractors": [],
    "description": null,
    "scope": null,
    "costActual": "0",
    "priority": "2",
    "riskLevel": null
}

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.

GET /api/json/item

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

GET /api/json/item?limit=5&offset=50&type=recoveryInfrastructure

Example

# Get results 50-55 of recoveryInfrastructure
curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \
     https://demo.crisisworks.com/api/json/item?limit=5&offset=50&type=recoveryInfrastructure

{
    "models": {
        "10744": {
            "id": "10744",
            "eventId": "138",
            "due": null,
            "isSensitive": false,
            "itemSchemaName": "default",
            "userId": "depot2",
            "status": "10",
            "templateName": null,
            "costEstimate": "0.00",
            "type": "recoveryInfrastructure",
            "title": "Foo Rd, Smallville VIC 1234",
            "address": "Foo Rd, Smallville VIC 1234",
            "assetId": "58758",
            "assignee": 0,
            "_canEdit": true,
            "dateCreated": "2016-09-19T14:04:10+10:00",
            "dateUpdated": "2016-09-19T14:58:30+10:00",
            "isTemplate": false,
            "tags": "",
            "descriptionPhotos": [],
            "scopePhotos": [],
            "contractors": [],
            "description": null,
            "scope": null,
            "costActual": "0",
            "priority": "2",
            "riskLevel": null,
            "_order": 2
        },
        "10755": {
            ...
        },
        "10756": {
            ...
        },
        "10757": {
            ...
        },
        "10759": {
            ...
        }
    },
    "count": 5,
    "total": "312",
}

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:

GET /api/json/item?type=recoveryInfrastructure&limit=100&offset=0

Will return

{
  "models": [...],
  "count": 100,
  "total": "212",
}

You can then fetch the second set:

GET /api/json/item?type=recoveryInfrastructure&limit=100&offset=101

{
  "models": [...],
  "count": 100,
  "total": "212",
}

And the final set

GET /api/json/item?type=recoveryInfrastructure&limit=100&offset=201

{
  "models": [...],
  "count": 12,
  "total": "212",
}

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.

POST /api/json/item

Example

# submit a new record with some sample data
$ curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \
     -d '{
        "title": "Test submission via API",
        "requestor": "Scott Davey",
        "type": "Recovery_Infrastructure"
      }` \
     "https://demo.crisisworks.com/api/json/item"

{
    "id": 234,
    "title": "Test submission via API",
    "requestor": "Scott Davey",
    "type": " Recovery_Infrastructure",
}

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.

PUT /api/json/item/id/246

Example

# update existing record 246
$ curl -X PUT \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \
     -d '{
        "title": "Test submission via API",
        "requestor": "Scott Davey",
        "type": "Recovery_Infrastructure",
        "token": "7d47548fca3226d32d9404f604bed9bb",
      }` \
     "https://demo.crisisworks.com/api/json/item/id/246"


{
    "id": 246,
    "title": "Test submission via API",
    "requestor": "Scott Davey",
    "type": " Recovery_Infrastructure",
}

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.

DELETE /api/json/item/id/1

Example

# delete record 1
curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \
     DELETE https://demo.crisisworks.com/api/json/item/id/1

true

API Command Reference

The following public API commands are available:

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|POST /api/json/asset
GET|PUT|PATCH|DELETE /api/json/asset/id/123

GET Parameters

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

# return 1 matching asset

$ curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \ 
       https://demo4.crisisworks.com/api/json/asset?limit=1

{
    "models": {
        "1": {
            "id": "1",
            "name": "TP827623",
            "code": "100044818",
            "type": "Asset_Property",
            "friendlyType": "Property",
            "geo": {
                "points": [],
                "polygons": [
                    {
                        "points": [
                            {
                                "longitude": "144.01960063",
                                "latitude": "-37.67845485"
                            },
                            {
                                "longitude": "144.01926323",
                                "latitude": "-37.67851867"
                            },
                            {
                                "longitude": "144.01912979",
                                "latitude": "-37.67853825"
                            },
                            {
                                "longitude": "144.01899564",
                                "latitude": "-37.67855447"
                            }
                        ]
                    }
                ],
                "linestrings": []
            },
            "_distance": null,
            "style": "green",
            "_within": false,
            "_order": 1
        }
    },
    "count": 1,
    "total": "22608",
    "updated": "2016-08-03T00:33:44+00:00"
}

Asset Type (REST)

This command fetches the available asset types.

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

GET /api/json/asset-type

Example

# fetch the available asset types
$ curl -H "Authorization: BRAVO-AUTH uuid=$YOUR_DEVICE_UUID, token=$YOUR_TOKEN" \
       https://demo4.crisisworks.com/api/json/asset-type


{
    "models": {
        "Asset_Bridge": "Bridge",
        "Asset_Culvert": "Culvert",
        "Asset_Facility": "Facility",
        "Asset_Footpath": "Footpath",
        "Asset_Other": "Other",
        "Asset_PointOfInterest": "Point of Interest",
        "Asset_Property": "Property",
        "Asset_Reserve": "Reserve",
        "Asset_Road": "Road",
        "Asset_Stormwater_Pipe": "Stormwater Pipe",
        "Asset_Stormwater_Pit": "Stormwater Pit"
    },
    "count": 11,
    "total": 11,
    "updated": null
}

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

GET /api/json/asset-lookup?query={{query}}&output={{output}}&key={{val}}...

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

POST https://{{host}}/api/json/asset-lookup
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}
{
    "options": {
        // option key/vals go here
    },
    "query": [
        {
            "code": "{{reference code}}",
            "str": "{{query string}}"
        },
        // additional queries go here
    ]
}

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).

{
    {{user reference code}}: {
        "reference": {{user reference code}},
        "query": {{user query}},
        "asset": {{asset return value}},
        "err": {{error message if available}}
    }
}

Options

These additional options are available

Parameter

Purpose

mode

One of the modes /wiki/spaces/ENG/pages/698810369. 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.

"upgradeExternalLookupToInternalAsset": true,
"assetClass": "Asset_Property_Vicmap"

geocoderOptions

For useExternalLookups, this is a JSON options array to configure the plugin. The most useful option is restrict matches to houses only:

"geocoderOptions": {
    "requiredFeatures": [
        "premise"
    ]
}

Example: Look up a single address

GET https://{{host}}/api/json/asset-lookup?query=555+Bourke+Street&output=id
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

Result

{
    "1": {
        "reference": 1,
        "query": "555 Bourke Street",
        "asset": "123",
        "err": null
    }
}

Example: Look up multiple addresses

POST https://{{host}}/api/json/asset-lookup
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

{
    "options": {
        "mode": "soundex",
        "useExternalLookups": true,
        "geocoderOptions": {
            "requiredFeatures": [
                "premise"
            ]
        }
    },
    "query": [
        {
            "code": 123,
            "str": "555 Bourke Street Melbourne"
        },
        {
            "code": 124,
            "str": "100000000 Bourke Streete Melbourne"
        }
    ]
}

Result:

{
    "123": {
        "reference": 123,
        "query": "555 Bourke Street Melbourne",
        "asset": {
            "id": "1",
            "type": "Asset_Property",
            "code": "Datalink HQ",
            "regionId": null,
            "geo": {
                "points": [
                    {
                        "longitude": "144.95731",
                        "latitude": "-37.81617"
                    }
                ],
                "polygons": [],
                "linestrings": []
            },
            "source": "Google",
            "accuracy": "3",
            "friendly": "555 Bourke Street Melbourne 3000",
            "name": "555 Bourke Street Melbourne 3000",
            "friendlyType": "Property",
            "extraInfo": [],
            "infoLabel": null,
            "infoUrl": null,
            "regionName": null
        },
        "err": null
    },
    "124": {
        "reference": 124,
        "query": "100000000 Bourke Streete Melbourne",
        "asset": null,
        "err": "No matching asset found"
    }
}

Create Event (RPC)

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

POST /api/json/create-event

Example

$ curl -X POST \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{
           "templateId": "12",
           "title": "My event",
           "description": "This is a demo event",
           "startDate": "2017-01-08T14:00:00",
           "endDate": "2017-01-08T15:00:00",
           "severity": "3",
           "uuid": "marketManager",
           "token": "f999008ef01f92d85cf77fd0918130c8"
          }' \
          https://demo4.crisisworks.com/api/json/create-event


{"code":200,"id":"26"}

Parameters

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

POST /api/json/duty

Example

$ curl -X POST \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{
           "participantId": "88",
           "onDuty": "1"
           "uuid": "marketManager",
           "token": "f999008ef01f92d85cf77fd0918130c8"
          }' \
          https://demo4.crisisworks.com/api/json/duty





{
  "code": 200,
  "duties": [
    "88"
  ],
  "onDuty": true,
  "eventId": "25",
  "id": "88"
}

Parameters

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

GET /api/json/event/id/123

Search Events

Example

GET /api/json/event

Parameters

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

$ curl "https://demo4.crisisworks.com/api/json/event?limit=1&order=id&orderDirection=DESC"

{
    "models": {
        "1021": {
            "id": "1021",
            "title": "Fire at Broadbeach",
            "description": "",
            "startDate": "2016-08-11T03:58:00+00:00",
            "endDate": null,
            "status": {
                "label": "Open",
                "value": 1,
                "style": "yellow"
            },
            "severity": "2",
            "participants": [
                {
                    "id": "2758",
                    "type": "position",
                    "name": "Archive Officer",
                    "positionId": "81"
                },
                {
                    "id": "2759",
                    "type": "user",
                    "name": "Pete Bool",
                    "userId": "pbool"
                }
            ],
            "userParticipants": [],
            "_isSelectable": true,
            "parentId": "1",
            "_order": 1
        }
    },
    "count": 1,
    "total": "50",
    "updated": null
}

Update Event

Parameters

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

$ curl -X PUT \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -d '{
           "id": "25",
           "description": "This event was closed today",
           "status": -1
         }' \
     "https://demo.crisisworks.com/api/json/event?uuid=marketManager"

{
  "id": "25",
  "title": "My Event",
  "description": "This event was closed today",
  "startDate": "2017-01-08T03:00:00+00:00",
  "endDate": "2017-01-08T04:00:00+00:00",
  "status": {
    "label": "Closed",
    "value": -1,
    "style": "grey"
  },
  "severity": "3",
  "participants": [],
  "userParticipants": [],
  "_isSelectable": true,
  "parentId": "1"
}

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|POST /api/json/item
GET|PUT|PATCH|DELETE /api/json/item/id/123

GET Parameters

In addition to the standard filters listed below, each register may also have a list of additional filters. Please consult the register guide or contact Datalink's Service Desk for more 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

# fetch all active 'fpn' records
$ curl "https://demo4.crisisworks.com/api/json/item?type=fpn&active=1"


{
    "models": {
        "14919": {
            "id": "14919",
            "eventId": "1014",
            "due": null,
            "isSensitive": false,
            "itemSchemaName": "moorabool",
            "userId": "pkakris.mb",
            "status": "20",
            "templateName": null,
            "costEstimate": "0.00",
            "type": "fpn",
            "title": null,
            "address": null,
            "assetId": "1345678",
      		"asset_friendly": "7 TEST STREET 3000",
            "asset_code": "pr_1234567",
            "asset_type": "Asset_Property_Vicmap",
            "asset_extra": {
                "spi": "2\\PS12345",
                "code": "pr_1234567",
                "crefno": "11111",
                "propnum": "22222",
                "fur_desc": null,
                "prop_pfi": "4444444",
                "parcel_pfi": "444444"
            },
            "assignee": "2632",
            "assignee_info": "Pete Kakris",
            "_canEdit": true,
            "dateCreated": "2016-03-03T13:13:33+11:00",
            "dateUpdated": "2016-03-03T13:13:33+11:00",
            "isTemplate": false,
            "tags": "",
            "infringementNumber": null,
            "contractors": [],
            "media": [
                {
                    "id": "602",
                    "uri": "\/api\/binary\/media\/602",
                    "thumbUri": "\/api\/binary\/media\/602?type=thumb",
                    "type": "image\/jpeg",
                    "name": "blob.jpg",
                    "created": "2016-03-03T02:13:22+00:00",
                    "size": "71785"
                }
            ],
            "mergedFile": [],
            "activity": null,
            "cutGrassWeeds10cm": false,
            "removeDebris": false,
            "firebreak10m": false,
            "cutGrassWeeds5cm": false,
            "trimTrees": false,
            "removeFlammable": false,
            "notes": null,
            "dateNewFromWeb": null,
            "dateNewFromMobile": null,
            "date1stInspectionRequired": null,
            "dateHazardExists": "2016-03-03T02:13:33+00:00",
            "dateComplianceInspectionRequired": null,
            "dateRequestCompulsoryClearing": null,
            "datePostClearanceInspectionReview": null,
            "dateHazardCleared": null,
            "dateTemporaryExemptionGranted": null,
            "dateClosed": null,
            "dateNoticeWithdrawn": null,
            "dateFpnSent": null,
            "infringementSentDate": null,
            "_order": 1
        },
        "14968": {
            "id": "14968",
            "eventId": "1014",
            "due": null,
            "isSensitive": false,
            "itemSchemaName": "moorabool",
            "userId": "pkakris.mb",
            "status": "20",
            "templateName": null,
            "costEstimate": "0.00",
            "type": "fpn",
            "title": "PARCEL 45530943",
            "address": "PARCEL 45530943",
            "assetId": "24733",
            "assignee": "2632",
            "assignee_info": "Pete Kakris",
            "_canEdit": true,
            "dateCreated": "2016-06-20T14:06:27+10:00",
            "dateUpdated": "2016-06-20T14:06:27+10:00",
            "isTemplate": false,
            "tags": "",
            "infringementNumber": null,
            "contractors": [],
            "media": [],
            "mergedFile": [],
            "activity": null,
            "cutGrassWeeds10cm": true,
            "removeDebris": false,
            "firebreak10m": false,
            "cutGrassWeeds5cm": false,
            "trimTrees": false,
            "removeFlammable": false,
            "notes": null,
            "dateNewFromWeb": null,
            "dateNewFromMobile": null,
            "date1stInspectionRequired": null,
            "dateHazardExists": "2016-06-20T04:06:27+00:00",
            "dateComplianceInspectionRequired": null,
            "dateRequestCompulsoryClearing": null,
            "datePostClearanceInspectionReview": null,
            "dateHazardCleared": null,
            "dateTemporaryExemptionGranted": null,
            "dateClosed": null,
            "dateNoticeWithdrawn": null,
            "dateFpnSent": null,
            "infringementSentDate": null,
            "_order": 2
        }
    },
    "count": 2,
    "total": 2,
    "updated": null
}

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:

PUT /api/json/item/id/123

{
  "id": "14968",
  "eventId": "1014",
  "status": "20",
  "type": "fpn",
  "title": "PARCEL 45530943",
  "assetId": "24733",
  "cutGrassWeeds10cm": true,
  "removeDebris": false,
  "firebreak10m": false,
  "cutGrassWeeds5cm": false,
  "trimTrees": false,
  "removeFlammable": false,
  "notes": "This is a note"
}

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.

POST /api/json/item

{
  "eventId": "1014",
  "status": "20",
  "type": "fpn",
  "itemSchemaName": "vicCouncil",
  "asset_lookup": "123456",
  "asset_codefield": "propnum"
}

Example: looking up a property by a name search:

POST /api/json/item

{
  "eventId": "1014",
  "status": "20",
  "type": "fpn",
  "itemSchemaName": "vicCouncil",
  "asset_friendly": "12 smith street collingwood"
}

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 /api/json/log

GET Parameters

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

#fetch the audit log for item 14968
$ curl "https://demo4.crisisworks.com/api/json/log?limit=5&item=14968"


{
    "models": {
        "1004527": {
            "time": "2016-06-20 4:06:27 +0000",
            "id": "1004527",
            "type": "Items",
            "summary": "created a fire prevention notice and set it to hazard exists",
            "message": "",
            "images": [],
            "labels": [
                {
                    "style": "yellow",
                    "label": "Hazard Exists"
                }
            ],
            "dataChangeCount": 10,
            "itemCount": 1,
            "userName": "Pete Kakris",
            "userPosition": "Crisisworks Administrator, FPN Coordinator",
            "userOrganisation": "Datalink",
            "userId": "pkakris.mb",
            "userPositionId": "7",
            "userAvatarUrl": "https:\/\/demo4.crisisworks.com\/var\/files\/thumbs\/80ea44413272ba499ddd0413fc2858cf_57c193f71dbbed2361bce727c9ce1642_w60_h60_fit.png",
            "objId": "14968",
            "objType": "Fire Prevention Notice",
            "objIcon": "ico_hazard_fire.png",
            "title": "PARCEL 45530943",
            "url": "https:\/\/demo4.crisisworks.com\/register\/item\/view\/id\/14968",
            "registerId": "fpn",
            "registerName": "Fire Prevention Notice",
            "eventId": "1014",
            "eventName": "FPN Inspections",
            "assignments": [
                {
                    "id": "pkakris.mb",
                    "name": "Pete Kakris",
                    "type": "Mecc_User",
                    "avatarUrl": "https:\/\/demo4.crisisworks.com\/var\/files\/thumbs\/80ea44413272ba499ddd0413fc2858cf_57c193f71dbbed2361bce727c9ce1642_w60_h60_fit.png"
                }
            ],
            "status": "Hazard Exists",
            "statusClass": "yellow",
            "statusValue": 20,
            "visibility": "",
            "targetUsers": [
                "pkakris.mb"
            ],
            "targetPositions": [],
            "comment": null,
            "targetOrganisations": [],
            "sound": "message_received",
            "logEntries": [
                {
                    "objId": "1031017",
                    "objClass": "Fpn_Inspection",
                    "objTitle": "PARCEL 45530943",
                    "subject": "created a Fire Prevention Notice",
                    "dataChanges": [
                        {
                            "name": "eventId",
                            "label": "Event",
                            "oldValue": "FPN Inspections",
                            "newValue": "FPN Inspections"
                        },
                        {
                            "name": "status",
                            "label": "Status",
                            "oldValue": "",
                            "newValue": "Hazard Exists"
                        },
                        {
                            "name": "assetId",
                            "label": "Asset",
                            "oldValue": "",
                            "newValue": "PARCEL 45530943"
                        },
                        {
                            "name": "cutGrassWeeds10cm",
                            "label": "Cut grass and weeds over the whole property to a height of no more than 10cm.",
                            "oldValue": "",
                            "newValue": "Yes"
                        },
                        {
                            "name": "removeDebris",
                            "label": "Leaves, twigs and other vegetation debris must be removed at regular intervals.",
                            "oldValue": "",
                            "newValue": "No"
                        },
                        {
                            "name": "firebreak10m",
                            "label": "A firebreak of 10 metres wide is to be cut inside the property boundary as close as practicable to the fence-line, to a height of not more than 10cm",
                            "oldValue": "",
                            "newValue": "No"
                        },
                        {
                            "name": "cutGrassWeeds5cm",
                            "label": "Cut all grass and weeds within 30m of any building to a height of no more than 5cm.",
                            "oldValue": "",
                            "newValue": "No"
                        },
                        {
                            "name": "trimTrees",
                            "label": "Trim trees and shrubs clear of roofline, walls and other elements of the buildings.",
                            "oldValue": "",
                            "newValue": "No"
                        },
                        {
                            "name": "removeFlammable",
                            "label": "Remove flammable objects such as firewood, mulches, rubbish and garden furniture from within 10m of the vulnerable parts of the building like windows, decks and eaves.",
                            "oldValue": "",
                            "newValue": "No"
                        },
                        {
                            "name": "assignee",
                            "label": "Assign To",
                            "oldValue": "",
                            "newValue": "Pete K"
                        }
                    ]
                },
                {
                    "objId": "1031018",
                    "objClass": "Fpn_Inspection",
                    "objTitle": "PARCEL 45530943",
                    "subject": "linked to User Pete K"
                }
            ],
            "userOrganisationId": "",
            "subject": "",
            "_order": 1
        }
    },
    "count": 1,
    "total": 1,
    "updated": null
}

Register Item Media (REST)

Documentation is currently unavailable for this command

Ping (RPC)

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

GET /api/json/ping

Example

$ curl "https://demo4.crisisworks.com/api/json/ping"


"2016-10-24T08:41:07+00:00"

Device Registration (RPC) — Authentication

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

POST /api/json/register

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

Example

$ curl -X POST \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
        "uuid": "40fjsjf0r-djsdjdks3-sjdhfhj3",
        "platform": "iPhone/7",
        "version": "2",
        "name": "Scott Davey's Phone",
        "username": "sdavey",
        "password": "itsasecret"
        }` \
     "https://demo4.crisisworks.com/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"
}

Resource (REST)

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

GET|POST /api/json/resource
GET|PUT|PATCH|DELETE /api/json/resource/id/123

GET Parameters

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

# fetch 5 resources
curl "https://demo4.crisisworks.com/api/json/resource?token=8162e97a0fabf76b3bf0b1bfa50e90e8&limit=5"


{
    "models": {
        "1": {
            "id": "1",
            "title": "Sand Bags",
            "description": null,
            "_order": 1
        },
        "2": {
            "id": "2",
            "title": "Grader No. 1 ZNO159",
            "description": "Moorabool Shire Council Graders (Total 4)",
            "_order": 2
        },
        "3": {
            "id": "3",
            "title": "Loader No. 1 SWQ492",
            "description": "Moorabool Shire Council Loaders (2)",
            "_order": 3
        },
        "4": {
            "id": "4",
            "title": "Grader No. 2 YHV493",
            "description": "Moorabool Shire Council (4 available)",
            "_order": 4
        },
        "5": {
            "id": "5",
            "title": "Grader No. 3 TGN897",
            "description": "Moorabool Shire Council Graders (4 in total)",
            "_order": 5
        }
    },
    "count": 5,
    "total": "339",
    "updated": null
}

User (REST)

Provides a RESTful way to access and manage users.

GET|POST /api/json/user
GET|PUT|PATCH|DELETE /api/json/user/id/abc

GET Parameters

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

curl "https://demo4.crisisworks.com/api/json/user?limit=5&active=1"


{
  "models": {
    "andrew": {
      "id": "andrew",
      "firstName": "Andrew",
      "lastName": "Salzano",
      "phone": null,
      "mobile": "0401234567",
      "email": "noc+andrew@datalink.com.au",
      "externalId": null,
      "address": null,
      "position": null,
      "organisationId": "POLICE",
      "profile": null,
      "onCall": false,
      "receiveSMS": false,
      "receiveEmail": false,
      "optInLearningCentre": false,
      "optInNewsletter": false,
      "optInAnnouncements": false,
      "active": true,
      "competencies": [
        "17"
      ],
      "tags": "",
      "lastPosition": {},
      "geo": {},
      "lastPositionDate": "2017-03-03T03:37:59+00:00",
      "lastLoginAt": null,
      "lastOnline": null,
      "lastUpdated": null,
      "isOnline": false,
      "_order": 1
    },
    "ben": {
      "id": "ben",
      "firstName": "Ben",
      "lastName": "Gusler",
      "phone": null,
      "mobile": "0404567890",
      "email": "noc+ben@datalink.com.au",
      "externalId": null,
      "address": null,
      "position": null,
      "organisationId": "COUNCIL",
      "profile": null,
      "onCall": false,
      "receiveSMS": false,
      "receiveEmail": false,
      "optInLearningCentre": false,
      "optInNewsletter": false,
      "optInAnnouncements": false,
      "active": true,
      "competencies": [
        "10"
      ],
      "tags": "",
      "lastPosition": {},
      "geo": {},
      "lastPositionDate": "2017-03-03T03:37:40+00:00",
      "lastLoginAt": null,
      "lastOnline": null,
      "lastUpdated": null,
      "isOnline": false,
      "_order": 2
    }
  },
  "count": 2,
  "total": 2,
  "updated": "2017-03-03T03:37:19+00:00"
}

Participant (RPC)

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

GET /api/json/participant

GET Parameters

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

POST /api/json/import

{
    "mode": "schedule",
    "data": "...",
    "dataType": "application/csv",
    "encoding": "plain",
    "importType": "users",
    "importRule": "userimport",
    "rollbackOnError": false,
    "selectedImportType": "Users",
    "message": "Test import",
    "regionId": "DEV1"
}

Parameters

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

POST /api/json/import

{
    "mode": "status",
	"id": <processid>
}

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
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.

POST https://{{host}}/api/json/report
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

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

{
    "mode": "run",
    "reportId": 2,
    "params": {
      // see below
    }
}

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.

{
    "mode": "run",
    "reportInstanceId": 212
}

Results

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

{
  "code": 200,
  "result": "Report instance scheduled",
  "id": "100203"
}

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.

POST https://{{host}}/api/json/report
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

{
    "mode": "status",
    "id": 1
}

Results

When initially queued the results will return a QUEUED status:

{
  "code": 200,
  "id": "1",
  "status": "QUEUED",
  "dateRun": null,
  "dateCompleted": null,
  "userId": "lance",
  "result": "Report queued for execution",
  "timeTaken": null,
  "rowCount": null,
  "params": null
}

When complete it will return additional data:

{
  "code": 200,
  "id": "1",
  "status": "COMPLETED",
  "dateRun": "2021-08-27T06:29:10+00:00",
  "dateCompleted": "2021-08-27T06:36:35+00:00",
  "userId": "lance",
  "result": "Report execution completed. ",
  "timeTaken": "445",
  "rowCount": "1861",
  "params": {}
}

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

POST https://{{host}}/api/json/report
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

{
    "mode": "fetch",
    "reportInstanceId": 1,
    "format": "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:

{
  "code": 200,
  "id": "1",
  "status": "COMPLETED",
  "dateRun": "2021-08-27T06:29:10+00:00",
  "dateCompleted": "2021-08-27T06:36:35+00:00",
  "userId": "lance",
  "result": "Report execution completed. ",
  "timeTaken": "1",
  "rowCount": "2",
  "params": null,
  "contents": {
    "$schema": "https://crisisworks.com/schemas/analytics-export-v1.json#",
    "name": "My Report",
    "meta": [
      {
        "key": "summary",
        "label": "Summary",
        "value": null,
        "display": "Not set"
      },
      // ... other meta fields ...
    ],
    "filter": [
      {
        "key": "startDate",
        "label": "From date",
        "value": null,
        "display": "Not set"
      },
      ... other filters ...
    ],
    "spec": [
      {
        "key": "auditActionLogTimestamp",
        "label": "Time",
        "type": "timestamp"
      },
      {
        "key": "auditActionTitle",
        "label": "Title",
        "type": "string"
      },
      // ... other field definitions ...
    ],
    "data": [
        {
          "auditActionLogTimestamp": 1630040582,
          "auditActionTitle": "This is an example line item 1",
          // ... more fields as per 'spec' ...
        },
        {
          "auditActionLogTimestamp": 1630040582,
          "auditActionTitle": "This is an example line item 2",
          // ... more fields as per 'spec' ...
        }
    ]
  }
}

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.

{
  "code": 200,
  "id": "1",
  "status": "COMPLETED",
  "dateRun": "2021-08-27T06:29:10+00:00",
  "dateCompleted": "2021-08-27T06:36:35+00:00",
  "userId": "lance",
  "result": "Report execution completed. ",
  "timeTaken": "445",
  "rowCount": "1861",
  "params": null,
  "contents": "YXVkaXRBY3Rpb25Mb2dUaW1lc3RhbXAsYXVkaXRBY3Rpb25UaXRsZSxhdWRpdEFjdGlvblVzZXJJZCxhdWRpdEFjdGlvbkxvZ0l0....",
  "format": "csv"
}

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

POST https://{{host}}/api/binary/report
Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}

{
    "mode": "fetch",
    "reportInstanceId": 1,
    "format": "csv"
}

A response may look like this:

HTTP/1.1 200 OK
Date: Fri, 27 Aug 2021 08:04:04 GMT
Content-Type: text/plain;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

auditActionLogTimestamp,auditActionTitle
"2021-08-27 15:03:02","This is an example line item 1"
"2021-08-27 15:03:02","This is an example line item 1"

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:

curl -X POST --location "https://{{host}}/api/binary/report" \
  -H "Authorization: BRAVO-AUTH uuid={{uuid}}, token={{token}}" \
  -d "{\"mode\": \"fetch\",\"reportInstanceId\": 1,\"format\": \"xlsx\"}" \
  -O

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

https://site.crisisworks.com/api/geojson/item?event=1014&type=fpn

Example: Testing the URL

# Test the URL
curl "https://demo4.crisisworks.com/api/geojson/item?event=1014&type=fpn"


{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "GeometryCollection",
                "geometries": [
                    {
                        "type": "Polygon",
                        "coordinates": [
                            [
                                [
                                    144.32965753,
                                    -37.74266446
                                ],
                                [
                                    144.32848934,
                                    -37.73833017
                                ],
                                [
                                    144.34002576,
                                    -37.73953299
                                ],
                                [
                                    144.34046432,
                                    -37.73957869
                                ],
                                [
                                    144.34008872,
                                    -37.74173357
                                ],
                                [
                                    144.3397433,
                                    -37.74371525
                                ],
                                [
                                    144.32965753,
                                    -37.74266446
                                ]
                            ]
                        ]
                    },
                    {
                        "type": "Point",
                        "coordinates": [
                            144.32965753,
                            -37.74266446
                        ]
                    }
                ]
            },
            "properties": {
                "iconFile": "ico_fire_yellow.png",
                "iconShadow": "sq_shadow_full.png",
                "iconSize": "[messa32,40]",
                "iconAnchor": "[16,34]",
                "style": "yellow",
                "status": "yellow",
                "id": "14968",
                "title": "PARCEL 45530943",
                "url": "https:\/\/demo4.crisisworks.com\/register\/item\/view\/id\/14968",
                "info": [
                    "Status: Hazard Exists",
                    "Updated: 2016-06-20 14:06:27"
                ]
            },
            "_hasLineStrings": false
        }
    ]
}

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 method is deprecated and will not be available in Crisisworks 5. Use the Report API instead.

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

# Fetch all FPN records via CSV
curl "https://demo4.crisisworks.com/api/csv/item?type=fpn&event=1014"

id,eventId,due,isSensitive,itemSchemaName,userId,status,templateName,costEstimate,type,title,address,assetId,assignee,assignee_info,_canEdit,dateCreated,dateUpdated,isTemplate,tags,infringementNumber,contractors,media,mergedFile,activity,cutGrassWeeds10cm,removeDebris,firebreak10m,cutGrassWeeds5cm,trimTrees,removeFlammable,notes,dateNewFromWeb,dateNewFromMobile,date1stInspectionRequired,dateHazardExists,dateComplianceInspectionRequired,dateRequestCompulsoryClearing,datePostClearanceInspectionReview,dateHazardCleared,dateTemporaryExemptionGranted,dateClosed,dateNoticeWithdrawn,dateFpnSent,infringementSentDate,_order
14919,1014,,,moorabool,pkakris.mb,20,,0.00,fpn,,,,2632,"Pete Kakris",1,2016-03-03T13:13:33+11:00,2016-03-03T13:13:33+11:00,,,,Array,Array,Array,,,,,,,,,,,,"Thu, 03 Mar 2016 13:13:33 +1100",,,,,,,,,,1
14968,1014,,,moorabool,pkakris.mb,20,,0.00,fpn,"PARCEL 45530943","PARCEL 45530943",24733,2632,"Pete Kakris",1,2016-06-20T14:06:27+10:00,2016-06-20T14:06:27+10:00,,,,Array,Array,Array,,1,,,,,,,,,,"Mon, 20 Jun 2016 14:06:27 +1000",,,,,,,,,,2

Step 3

Now consume the URL in your application.

Example

#!/bin/bash

# Prepare a file with the import data
# Note we're using the 'CSV' adapter in this example, but you could also use the 'JSON' adapter for structured output.
cd /tmp
rm -f daily-import.csv
curl "https://demo4.crisisworks.com/api/csv/item?type=fpn&event=1014" > daily-import.csv


# Now import into my system 
# (this part is dependant on your application)
import daily-import.csv

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.

###
# Uses the asset contact import
###

POST /api/json/import

{
    "mode": "schedule",
    "dataType": "application/csv",
    "data": "Asset Code,Code Field,Title,First Name,Last Name,Company,Full Name,Address 1,Address 2,Address 3,Address 4,Email,Mobile,Phone,Registers,Notes,External ID,Relationship to Property\n43626,propnum,Mrs,Joy,Brown,ACMI Corp,,3 Bourke Street,Melbourne,VIC,3000,joy@acmicorp.com.au,0123 45667,,fpn,This is the CEO,,Owner\n43627,propnum,Mr,Fred,Smith,Datalink,,2 Foo Street,Fooville,,,fred.smith@foo.com,,,,,,\n43628,propnum,Mrs,Colleen,Davey,Colgate,,3 Elizabeth St,Melbourne,VIC,3000,colleen.davey@foo.com,,,,,,\n",
    "encoding": "plain",
    "selectedImportType": "Assets",
    "importType":"Assets",
    "importRule": "contact",
    "rollbackOnError": false,
    "message": "Test Asset Contacts import",
    "regionId": "DEV1"
}

Uploading an import file

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

# Auth credentials
SITE_URL="your Crisisworks site url"
API_TOKEN="token you received from above curl command"
API_UUID="your CW username"

# The file to send
IMPORT_FILE="myfile.csv"
IMPORT_TYPE="Assets"
IMPORT_RULE="contact"
IMPORT_REGION="your site region"
IMPORT_MESSAGE="Import of asset contacts"

AUTH="Authorization: BRAVO-AUTH uuid=${API_UUID}, token=${API_TOKEN}"
JSON="{\"mode\": \"schedule\",\"data\": \"$(base64 --input=${IMPORT_FILE})\",\"dataType\": \"application/csv\",\"encoding\": \"base64\",\"importType\": \"${IMPORT_TYPE}\",\"importRule\": \"${IMPORT_RULE}\",\"rollbackOnError\": false,\"message\": \"${IMPORT_MESSAGE}\",\"regionId\": \"${IMPORT_REGION}\"}"

curl -X POST \
     -d ${JSON} \
     -H 'Accept: application/json' \
     -H ${AUTH} \
     -H 'Content-Type: application/json\;charset=UTF-8' \
     "https://${SITE_URL}/api/json/import"

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

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

Parameters

Supported data types