View Account History

This documentation will describe the View Account History (XMHIST) endpoint. This endpoint allows users to view subscriber account history.

See the Authentication documentation for information on how to obtain the authentication headers within the request.

Use cases

Panel/alarm application developers requiring history data of a given account number.
Individuals writing reports that require history data of a given account number.

Date formats

NTD is a timestamp format used by DICE. NTD dates are used when defining time frames within endpoint calls. See the Date Format documentation for information on converting NTD to UNIX and vice versa if needed.

Supported attributes

Attribute	Type	Required	Description
*setMethod	string	Yes	Determines the endpoint you are calling. Must be `XMHIST` to view history.
ACCOUNT	string	Yes	The subscriber account number (`9` character max). The system will display the history stored on this account.
STARTDATE	string	Yes	The date the system should begin pulling history information. This will be the date of the earliest history record in the resulting report. Expects `YYYYMMDD` format (Example: `20240109`).
STARTTIME	string	No	The time on the STARTDATE the system should begin pulling history information. Defaults to `0000`. Expects `HHMI` (24-hour) format (Example: `2200`).
STOPDATE	string	Yes	The date the system should stop pulling history information. This will be the date of the latest history record in the resulting report. Expects `YYYYMMDD` format.
STOPTIME	string	No	The time on the STOPDATE the system should stop pulling history information. Defaults to `0000`. Expects `HHMI` (24-hour) format.
HOURS	integer	No	Number of hours of history to retrieve if STARTDATE and STOPDATE are not sent.
SEARCHTYPE	string	No	Determines if operator handled signals will be included in the results. Use `OPR` to include operator handled signals in the report.
SERVICEONLY	string	No	Determines if only history events related to the service system should be returned. Accepts: `Y` or `N`.
LIMITHIST	integer	No	Return no more than this many history records starting with the newest.
NOMULTIPLES	string	No	Determines if MESSAG, SYS, and events with no resolution are ignored. Accepts: `Y` or `N`.

Example request

curl --location "https://example.securemcloud.com/rest/rest.php?dataSource=methods&*view=xmsubmit" \
--header 'X-DICE-APPKEY: {{X-DICE-APPKEY}}' \
--header 'X-DICE-USERNAME: {{X-DICE-USERNAME}}' \
--header 'X-DICE-DATE: {{X-DICE-DATE}}' \
--header 'X-DICE-NONCE: {{X-DICE-NONCE}}' \
--header 'X-DICE-DIGEST: {{X-DICE-DIGEST}}' \
--form '*setMethod="XMHIST"' \
--form 'ACCOUNT="DOC123"' \
--form 'STARTDATE="20240101"' \
--form 'STARTTIME="0900"' \
--form 'STOPDATE="20240102"' \
--form 'STOPTIME="1200"' \
--form 'HOURS=""' \
--form 'SEARCHTYPE="OPR"' \
--form 'SERVICEONLY="N"' \
--form 'LIMITHIST="500"' \
--form 'NOMULTIPLES="Y"'

Example 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",
        "VIDEO": "Y"
    }
}

Response fields

Field	Description
ACCOUNT_NUMBER	The subscriber account the alarm is assigned to (the account the alarm came in from).
HISTORY_EVENT_NTD	The time the alarm was received by the system in NTD format.
HISTORY_EVENT_DATE	The date and time the alarm was received in `MM/DD/YY HH:MM:SS` format.
INCIDENT_NUMBER	Unique identifier created by the system and assigned to the event.
SEIA_CODE	The contact ID code sent from the panel.
ZONE_CODE_1	The contact ID code sent from the panel.
ZONE_CODE_2	The zone received from the panel.
TYPE	The alarm code received.
OPR	The operator code of the individual who handled the alarm.
ALARM_CATEGORY	The category assigned to the alarm. See the Alarm Category documentation for descriptions of the categories.
PRIORITY	The importance assigned to the alarm type.
HIST_TEXT	The alarm description written to account history.
ZONE_1	The contact ID code sent from the panel.
ZONE_2	The contact ID code sent from the panel.
AM_NOTIFY	Whether or not the subscriber want to receive a notification for the alarm type received.
PENDING_TIME	The event’s NTD timestamp received from the panel.
PR_CHECKSUM	Determines the process path taken by the signal.
SECOND_ZONE_IS	Determines how the zone description is created. `Z` uses the zone description within data entry. `U` uses the user who generated the signal (in the case of Opens, Closes, etc.) `N` uses the panel generated zone description.
COLOR	The color of the alarm and its assigned text when displayed in pending. The first character is the background color, the second is the foreground (text) color. See the Supplemental Information documentation for information on how to interpret this field.
VIDEO	Whether or not the alarm includes video surveillance footage attached.

Note: The HISTORY_EVENT_NTD is the date and time coded in a custom format. See the Date Format documentation for instructions on how to convert NTD to UNIX (and vice versa) as necessary.

Possible error messages

Invalid method

Verify XMHIST is specified for the *setMethod attribute.

{
    "ERROR_CODE": "999",
    "ERROR_DESCRIPTION": "INVALID%20METHOD%20METHOD",
    "PROGRAM_ERROR": "11",
    "PROGRAM_ERROR_DESCRIPTION": "Missing%20or%20Duplicate%20key",
    "ERROR_ON_LINE": "240",
    "ADDITIONAL_INFO": "%3CMETHOD_NAME%3EXMHIS%20%20%20%3C%2FMETHOD_NAME%3E"
}

Missing start tag

Verify the STARTDATE and STOPDATE attributes are populated with valid dates.

{
    "status": "error",
    "message": "XML is malformed",
    "errno": 2,
    "errstr": "simplexml_load_string(): Entity: line 2: parser error : Start tag expected, '&lt;' not found"
}

View Account History

Use cases #

Date formats #

Supported attributes #

Example request #

Example response #

Response fields #

Possible error messages #

Invalid method #

Missing start tag #