Postman Tutorial

This documentation is intended for individuals unfamiliar with using Postman to call REST APIs. While intended for beginner audiences, it is recommended you reference Postman’s formal documentation for answers to questions regarding their UI. If you are comfortable with calling DICE’s REST API, see the Get Started documentation for information on authentication.

Setting up Postman

Postman is an API platform used to build and use APIs. We recommend using Postman because it’s easy to use and we provide a MADE collection to help you get started. Postman also provides practical examples to help you learn how to call APIs.

First, Download Postman and create an account.

Once logged in, you will be directed to your workspace.

Import collection

Importing the DICE MADE collection provides you with access to all the available endpoints and their attributes.

Perform the following steps to import the DICE MADE collection.

Download the DICE MADE collection file.
From your Postman Workspace, select Import.
Open the location of the file on your computer.
Drag and drop the json file into the import dialog box.

The import will complete automatically. You now have access to the MADE endpoints.

See the Endpoint reference below for links to the available endpoint documentation.

Create environment

Creating an environment in Postman is how you configure authentication headers for calling the API.

Perform the following steps to create your first environment.

Go to the Environments tab.
Select Create Environment to view the environment variables.
Name the environment Matrix.
Input baseurl into the first Variable field.
Select Default from the Type dropdown.
Input https://{centralstation.securemcloud.com} into the Initial Value field.
- Where {centralstation.securemcloud.com} is the central station’s domain. Contact the central station if you don’t know their domain.
Input X-DICE-USERNAME into the second Variable field.
Select Default from the Type dropdown.
Input your Matrix username into the Initial Value field.
- Note: If you’re going to create an integration, a new Matrix user is recommended. This is more advanced and not required for this tutorial.
Input X-DICE-PASSWORD into the third Variable field.
Select Secret from the Type dropdown.
Input the Matrix password into the fourth Initial Value field.
Input X-DICE-APPKEY into the Variable field.
Select Default from the Type dropdown.
Input the name of the app you’re creating into the Initial Value field.
Select Save.

Proceed to the next section to make your first API call.

You can update the Current Value fields to change these variables while maintaining the Initial Values. This can be helpful to preserve the Initial Values and use alternate ones as necessary when switching between endpoints.

Calling the API

In this section, you’ll learn the basics of calling an API by making a request to the View Account History (XMHIST) endpoint.

To begin, return to your Collections tab.

Perform the following steps to call XMHIST.

Select Matrix from the No Environment dropdown.
Select the XMHIST endpoint from those available.
- For this tutorial, select the January 01 to January 02 example query.
Select Try to open a request from the template.
- Please note, you may see an error in the response body box.
Select the Body tab.
Populate the ACCOUNT attribute with the Matrix account number you wish to view history for.
Select Send.

This will populate the response body box with the account history information.

Select JSON from the HTML dropdown. This will format the response to be easily read.

Example of a response

{
    "EVENT": [
        {
            "ACCOUNT_NUMBER": "    KMN12",
            "HISTORY_EVENT_NTD": "738889.70836",
            "HISTORY_EVENT_DATE": "01/02/24 17:00:02",
            "INCIDENT_NUMBER": "  196977",
            "SEIA_CODE": "E752 ",
            "ZONE_CODE_1": "E752  ",
            "ZONE_CODE_2": "10    ",
            "TYPE": "TICKER",
            "OPR": "OPR",
            "ALARM_CATEGORY": "N",
            "PRIORITY": "B",
            "HIST_TEXT": "SMS Test                                          ",
            "ZONE_1": "E752  ",
            "ZONE_2": "10    ",
            "AM_NOTIFY": "N",
            "PENDING_TIME": "738889.70836",
            "PR_CHECKSUM": "32776",
            "SECOND_ZONE_IS": "Z",
            "COLOR": "40",
            "HAS_DETAILS": "*",
            "VIDEO": "Y"
        },
        {
            "ACCOUNT_NUMBER": "    KMN12",
            "HISTORY_EVENT_NTD": "738889.70793",
            "HISTORY_EVENT_DATE": "01/02/24 16:59:25",
            "INCIDENT_NUMBER": "  196976",
            "SEIA_CODE": "E752 ",
            "ZONE_CODE_1": "E752  ",
            "ZONE_CODE_2": "10    ",
            "TYPE": "TICKER",
            "OPR": "OPR",
            "ALARM_CATEGORY": "N",
            "PRIORITY": "B",
            "HIST_TEXT": "SMS Test                                          ",
            "ZONE_1": "E752  ",
            "ZONE_2": "10    ",
            "AM_NOTIFY": "N",
            "PENDING_TIME": "738889.70793",
            "PR_CHECKSUM": "32776",
            "SECOND_ZONE_IS": "Z",
            "COLOR": "40",
            "VIDEO": "Y"
        }
    ]
    
}

See the View Account History endpoint documentation for more information on the available attributes and response fields.

Code Snippet

The Code Snippet tool provides the option to display the request in various coding languages. This allows you to select your preferred language so you can paste the request into your program as needed.

Selecting the </> option will display the request in cURL by default.

Select the cURL dropdown to select an alternate code example.

Endpoint reference

See the following documentation for detailed information on the available endpoints.

Postman Tutorial

Setting up Postman #

Import collection #

Create environment #

Calling the API #

Example of a response #

Code Snippet #

Endpoint reference #

Account management #

Account history #

Alarm and monitoring #

System data #

Setting up Postman

Import collection

Create environment

Calling the API

Example of a response

Code Snippet

Endpoint reference

Account management

Account history

Alarm and monitoring

System data