Generate Alarm Signals
This documentation will describe the Generate Alarm Signals (XMGENSIG
) endpoint. This endpoint is responsible for manually generating alarm signals assigned to a specific DICE subscriber account.
Use cases
- Panel/alarm application developers sending signals to the central station.
Supported attributes
Attribute | Type | Required | Description |
---|---|---|---|
*setMethod | string | Yes | Determines the endpoint you are calling. Must be XMGENSIG to generate signals. |
ACCOUNT | string | Yes | The Matrix account number (9 character max). This is the account the alarm will deliver to. |
FORMAT | string | Yes | Signaling format the alarm will use: CNTID , DMP , SEIA , or SIA . |
CODE | string | Yes | The alarm signal code. The signal code used is determined by the format. For example: E130 is a CNTID signal for a burglary. |
ZONE | string | No | The account zone that will be assigned to the alarm (6 character max). |
AREA | string | No | The panel area code (3 character max). |
USER | string | No | The panel user code (3 character max). |
SIGNAL_TIME | string | No | The time that should be written to the alarm. Expected in YYYYMMDDHHMISS format (20240109102422 ). Defaults to the time the request is made. |
MESSAGE | string | No | Any additional text to add to alarm signal. |
IS_MANUAL | string | No | Determines if the signal should indicate it was manually generated by a human (Y or N ). |
PANEL_PHONE | string | No | The phone number to dial back when processing the alarm, signal is treated like a 2 way panel. |
GPS_URL | string | No | The URL containing extra information such as a GPS map of the signal location. |
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}}' \
--header 'Accept: application/json' \
--form '*setMethod="XMGENSIG"' \
--form 'ACCOUNT="DOC123"' \
--form 'FORMAT="CNTID"' \
--form 'CODE="E130"' \
--form 'ZONE="1"' \
--form 'AREA="1"' \
--form 'USER="1"' \
--form 'SIGNAL_TIME="20240101000000"' \
--form 'MESSAGE="Additional information"' \
--form 'IS_MANUAL="Y"' \
--form 'PANEL_PHONE="5558912800"' \
--form 'GPS_URL="https://example.com"' \
Example response
{
"SIGNAL": {
"STATUS": "SUCCESS",
"INCIDENT_NUMBER": " 198320",
"ACCOUNT": " DOC123"
}
}
Response fields
Field | Description |
---|---|
STATUS | Displays that the request succeeded. See below for error messages. |
INCIDENT_NUMBER | Unique identifier created by the system and assigned to the event. |
ACCOUNT | The Matrix account number (9 character max). |
Possible error messages
Invalid signal format
The FORMAT
attribute was populated with an unrecognized signal format or, the FORMAT
and CODE
attributes are mismatched.
{
"STATUS": "ERROR",
"MESSAGE": "INVALID SIGNAL FORMAT",
"ERRORCODE": "001"
}
Invalid zone length
The specified zone exceeds the character limit.
{
"STATUS": "ERROR",
"MESSAGE": "INVALID ZONE LENGTH. 0-6 IS VALID.",
"ERRORCODE": "002"
}
Invalid user length
The specified user code exceeds the character limit.
{
"STATUS": "ERROR",
"MESSAGE": "INVALID USER LENGTH. 0-3 IS VALID.",
"ERRORCODE": "003"
}
Invalid area length
The specified area exceeds the character limit.
{
"STATUS": "ERROR",
"MESSAGE": "INVALID AREA LENGTH. 0-3 IS VALID.",
"ERRORCODE": "004"
}
Invalid code length
The specified alarm code exceeds the character limit.
{
"STATUS": "ERROR",
"MESSAGE": "INVALID CODE LENGTH. 0-5 IS VALID.",
"ERRORCODE": "005"
}
Specify information
Required information is missing from the request.
{
"STATUS": "ERROR",
"MESSAGE": "MUST SPECIFY CODE, ZONE, USER OR AREA.",
"ERRORCODE": "006"
}