Emergency24 ICCS API 1.0

Updated 2017-08-09

Overview

Welcome to the Emergency24 ICCS API! You can use our API to access ICCS API endpoints, which can receive information and manage your organization’s data.

The API requires an Access Token to authenticate each request. Responses are in JSON format.

Base URL

All URLs referenced in the documentation have the following base: https://www.emergency24.com/api/iccs/v1

Testing Base Url: https://www.emergency24.com/api/stage/iccs/v1

Authentication

All requests to ICCS’s API require an authentication. We support two forms of authentication:

API Key Authentication

Example request:

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/ping"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"

{
    "Success": true,
    "Code": 200,
    "Message": "",
    "RefId": 10000450,
    "Data": {
        "ID": 10010,
        "Campus": "City Campus"
    }
}

If you want to get started quickly, or are developing a standalone application which can run with your credentials, follow these instructions:

To get to the API management page, login to your ICCS platform, then go to Admin > API Access. From there, you can click on the ‘Create’ button to generate your API key.

Whitelisting IP Addresses

To help prevent unauthorized access, only IP addresses in your API’s whitelist can make API calls to your network. Whitelisting is necessary to run applications on servers, or make calls on your own computer.

From the API management page (Admin > API > Edit), type in the IP address from which you want to allow access, then click Save. If adding multiple IP addresses, add one at a time. Our system doesn’t support wildcarding IP addresses.

The API Key must be sent with every API call in an HTTP authorization header. Once you have an API Key, include it in the Authorization header for every request you make:

Authorization: Bearer ll352u9jujauoqz4gstvsae05

The header name is Authorization and the value of the header is Bearer ll352u9jujauoqz4gstvsae05. Since the access token is being transmitted in clear text, all API calls are done over HTTPS.

Make sure to replace ll352u9jujauoqz4gstvsae05 with your API key.

Signing API Requests

To sign a request, you need your Access Token, Token Secret, current UNIX Timestamp and Nonce. Requests are authenticated by computing a digital signature using the MD5 signature method.

Using the HTTP header.
Adding a query string value to the request.

Here are the parameters for Authorizing a request:

Key	Description
AccessToken	Your access token.
Nonce	Assigned a nonce (number used once) for the request. It is a random string used to detect replayed request messages. A GUID is recommended.
Timestamp	The Current Unix Timestamp, the whole number of seconds since January 1, 1970 00:00:00 GMT. Requests must be made within 15 minutes of the server time or a “Request time is too skewed from server time” error will occur.
AuthSignature	A MD5 signature of the request that is generated by the client using their private key.

To ensure that the client request signature and the signature generated by the server match, the steps described below must be followed by both parties:

Prepare your Signature string. The string to sign for a request is generated by concatenating request-specific strings together: Token Secret + Timestamp + Nonce
Encode your URL. Your signature string must be URL encoded before being hashed.
Calculate the signature. passing the signature string to MD5 hashing algorithm. Furthermore, use the hex digest for the string generated by the MD5 algorithm.

Contacts

Get All Contacts

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/all"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"

{
    "Success": true,
    "Code": 200,
    "Message": "",
    "RefId": 10000460,
    "Data": {
    "PageNumber": 1,
    "pageSize": 100,
    "TotalPages": 1,
    "TotalCount": 2,
    "List":[
        {
            "ContactID": 10045230,
            "ExternalID": 11111111,
            "Status": 0,
            "Name": "Test One",
            "FirstName": "Test",
            "LastName": "One",
            "Description": "Site Manager",
            "Title": "",
            "DepartmentID": "",
            "Department": "",
            "Date": "08/17/2016 14:44:03"
        },
        {
            "ContactID": 10045220,
            "ExternalID": "002201"
            "Status": 0,
            "Name": "Test Two",
            "FirstName": "Test",
            "LastName": "Two",
            "Description": "Site Manager",
            "Title": "",
            "DepartmentID": "",
            "Department": "",
            "Date": "08/17/2016 14:44:03"
        }
    ]
  }
}

GET /contacts/all

Returns a paginated list of contacts.

Optional Parameters	How to Use	Description
Page Size	page_size= Used in the request URL	The number of records to return. Default value is 500.
Page	page=	Used to page through the results. Begin from 1.

Get Contact by ID

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/10000230"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"

{
    "Success": true,
    "Code": 200,
    "Message": "Get all contacts.",
    "RefId": 10000540,
    "Data": [
      {
        "ContactID": 10000230,
        "ExternalID": 10012240,
        "Status": 0,
        "Name": "Test One",
        "FirstName": null,
        "LastName": null,
        "Description": "Site Manager",
        "Title": "",
        "DepartmentID": "",
        "Department": "",
        "Address1":"",
        "Address2":"",
        "City":"",
        "State":"",
        "Zip":"",
        "CreatedDate": "08/17/2016 14:44:03",
        "Phones": [
            {
                "PID": 10012880,
                "PhoneNumber": "+17731111777",
                "Text": 1,
                "Voice": 1
            }
        ],
        "EmailAddresses": [
            {
                "EID": 10011100,
                "EmailAddress": "test1@test.org",
                "Status": 0
            },
            {
                "EID": 10016420,
                "EmailAddress": "test2@test.org",
                "Status": 1
            }
        ],
        "Groups": [
            {
                "GroupID": 10010,
                "Name": "Newsletter Test Group",
                "CreatedDate": "3/24/2015 4:24:32 PM"
            },
            {
                "GroupID": 10070,
                "Name": "City Public Group",
                "CreatedDate": "6/4/2015 4:46:09 PM"
            }
        ]
      }
    ]
}

GET /contacts/{contact_id}

GET /contacts/exteranl/{external_id}

Return information about a single contact by its ID. You can use Contact ID or External ID.

Required Parameters	Description
Contact ID	Unique identifier for a particular contact.
External ID	Retrieve records with a specific external ID.

Add Contact

# Example
curl "https://www.emergency24.com/api/iccs/v1/contacts/addContact"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"
  -H "Content-Type: application/json"
  -X "POST"
  -d ""

#Example Contact Add Object:
{
  "ExternalID": "5556",
  "FirstName": "Test",
  "LastName": "Test",
  "Description": "Test",
  "Title":"",
  "Department":"",
  "DepartmentID":"",
  "Address1":"",
  "Address2":"",
  "City":"",
  "State":"",
  "Zip":"",
  "Language":"English",
  "EmailAddresses": [
    "test@gmail.com",
    "test@emergency24.com"
  ],
  "BackupEmailAddresses": [
    "test2@gmail.com",
    "test2@emergency24.com"
  ],
  "CellPhones": [
    "3125558888"
  ],
  "AlternateCellPhones": [],
  "WorkPhones": [
    "3125555555"
  ],
  "AlternateWorkPhones": [],
  "HomePhones": [
    "3125556666"
  ],
  "AlternateHomePhones": [],
  "GroupIDs": [
    "10010",
    "10070"
  ],
  "CustomValues": [
    {
      "property":"website",
      "value":"http://em24.com"
    }
  ]
}

POST /contacts/addContact

Create a contact if it doesn’t exist in a portal already.

Required Parameters	Description
Contact JSON	Used in the request body. This is JSON that represents a contact that you’re creating. This should be of the format seen in the code sample given.

Required Field	Description
External ID	Unique external ID you assign to contact.
First Name	First name

If ‘FirstName’,‘LastName’ and ‘Description’ field have the same match in an existing record, the system will treat this new record as duplicate data and return 400 error.

This will return a 409 Conflict error response if you are trying to create a new record and there is an existing record with the external ID.

Update Contact

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/10000230"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"
  -H "Content-Type: application/json"
  -X "PUT"
  -d ""

# Example Contact Object:
{
    "FirstName": "Test",
    "LastName": "",
    "Description": "Site Manager",
    "Title": "",
    "DepartmentID": "",
    "Department": "",
    "Language": "",
    "Address1": "",
    "Address2": "",
    "City": "",
    "State": "",
    "Zip": "",
    "CellPhones":[],
    "AlternateCellPhones":[],
    "WorkPhones":[],
    "AlternateWorkPhones":[],
    "HomePhones":[],
    "AlternateHomePhones":[],
    "EmailAddresses":[],
    "BackupEmailAddresses":[],
    "GroupIDs":[]
}

PUT /contacts/{contact_id}

PUT /contacts/external/{external_id}

Update an existing contact.

Required Parameters	Description
Contact ID	Unique identifier for a particular contact.
External ID	Unique identifier for a particular contact.
Contact JSON	Used in the request body. This is JSON that represents a contact that you’re updating. This should be of the format seen in the code sample given.

All updates are full replacements of the contact properties. That means you need to include the original content that is not changing, plus the new and changed content in the JSON.

Delete a Contact

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/10046110"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"
  -X "DELETE"

# Example JSON output:
{
    "Success": true,
    "Code": 200,
    "Message": "",
    "RefId": 0,
    "Data": {
        "ContactID": 10046110,
        "ExternalID": "1111"
    }
}

Delete /contacts/{contact_id}

Delete /contacts/external/{external_id}

Delete an existing contact.

Required Parameters	Description
Contact ID	Unique identifier for a particular contact.
External ID	Retrieve records with a specific external ID.

Add contact to Group

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/group/10000/external/1111"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"
  -X "PUT"

{
    "Success": true,
    "Code": 200,
    "Message": "Contact add into group success.",
    "RefId": 10000970,
    "Data": null
}

PUT /contacts/group/{group_id}/contact/{contact_id}

PUT /contacts/group/{group_id}/external/{external_id}

Associate a given contact to a group. A contact can be associated to multiply groups.

Required Parameters	Description
Contact ID	Unique identifier for a particular contact.
External ID	Unique external ID you assign to contact.
Group ID	The ID of a group

Delete contact from Group

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/contacts/group/10000/external/1111"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"
  -X "DELETE"

{
    "Success": true,
    "Code": 200,
    "Message": "Contact delete from group success.",
    "RefId": 10000970,
    "Data": null
}

Delete /contacts/group/{group_id}/contact/{contact_id}

Delete /contacts/group/{group_id}/external/{external_id}

Remove a contact from a group

Required Parameters	Description
Contact ID	Unique identifier for a particular contact.
External ID	Unique external ID you assign to contact.
Group ID	The ID of a group

Groups

Get All Groups

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/groups/all"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"

{
    "Success": true,
    "Code": 200,
    "Message": "Get all groups.",
    "RefId": 10000700,
    "Data": [
        {
            "GroupID": 10000,
            "Name": "Incident Command Group",
            "Count": 52,
            "Date": "03/24/2015 16:23:54"
        },
        {
            "GroupID": 10010,
            "Name": "Newsletter Test Group",
            "Count": 16,
            "Date": "03/24/2015 16:24:32"
        }
      ]
}

GET /groups/all

Returns a list of groups.

Get contacts of a group

# Authenticate API requests with the bearer token
curl "https://www.emergency24.com/api/iccs/v1/groups/1111"
  -H "Authorization: Bearer 31b61649-5405-45ac-9927-3c1d1b2c84b2"

{
    "Success": true,
    "Code": 200,
    "Message": "Get group members.",
    "RefId": 10000700,
    "Data": [
        {
            "ContactID": 10046000,
            "ExternalID": "",
            "Name": "Janeen Dupepe",
            "Date": "07/05/2017 16:37:48"
        },
        {
            "ContactID": 10046010,
            "ExternalID": "",
            "Name": "Susanna Folse",
            "Date": "07/05/2017 16:37:48"
        }
      ]
}

GET /groups/{group_id}

Returns all of the contacts under the group.

Required Parameters	Description
Group ID	Unique identifier for a particular group.

Response Status Codes

{
    "Success": true,
    "Code": 200,
    "Message": "",
    "RefId": 10000540,
    "Data": null
}

Code	Meaning
200	OK – The request was successful and the response body contains the representation requested.
400	Bad Request – The data given failed validation. Inspect the message for details.
401	Unauthorized – The supplied credentials, if any, are not sufficient to access the resource.
404	Not Found – The request is not found
429	Too Many Requests – Your application is sending too many simultaneous requests.
500	Internal Server Error – We had a problem with our server. Try again later.