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

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMGENSIG to generate signals.
ACCOUNTstringYesThe Matrix account number (9 character max). This is the account the alarm will deliver to.
FORMATstringYesSignaling format the alarm will use: CNTID, DMP, SEIA, or SIA.
CODEstringYesThe alarm signal code. The signal code used is determined by the format. For example: E130 is a CNTID signal for a burglary.
ZONEstringNoThe account zone that will be assigned to the alarm (6 character max).
AREAstringNoThe panel area code (3 character max).
USERstringNoThe panel user code (3 character max).
SIGNAL_TIMEstringNoThe time that should be written to the alarm. Expected in YYYYMMDDHHMISS format (20240109102422). Defaults to the time the request is made.
MESSAGEstringNoAny additional text to add to alarm signal.
IS_MANUALstringNoDetermines if the signal should indicate it was manually generated by a human (Y or N).
PANEL_PHONEstringNoThe phone number to dial back when processing the alarm, signal is treated like a 2 way panel.
GPS_URLstringNoThe 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

FieldDescription
STATUSDisplays that the request succeeded. See below for error messages.
INCIDENT_NUMBERUnique identifier created by the system and assigned to the event.
ACCOUNTThe 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"
}