Manage GPS Devices

This documentation will describe the Manage GPS Devices (XMGPSMNG) endpoint. This endpoint is responsible for managing the GPS devices assigned to subscribers under the Pinpoint Device Manager tab within Matrix Data Entry.

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

Use cases

  • Data entering devices on a subscriber account.
  • Updating existing device information.
  • Obtaining a list of phone masking formats.

Add devices

Create entries for new devices on the subscriber account.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMGPSMNG to manage devices.
OPTIONstringYesDetermines the method you will be using. Use ADD when creating new device entries.
GPS_KEYstringYesThe manufacturer provided unique identifier for the device (20 character max).
ACCOUNT_NUMBERstringYesThe subscriber account number (9 character max).
MIN_PHONEstringYesThe phone number that can be dialed to reach the device (16 character max).
MIN_PHONE_FstringNoThe phone number masking that should be applied (1 character max). Defaults to the first mask data entered on the account’s assigned country.
Note: See the List phone format section below for instructions on how to view the available formats.

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="XMGPSMNG"' \
--form 'OPTION="ADD"' \
--form 'GPS_KEY="39e99td9z9te"' \
--form 'ACCOUNT_NUMBER="KMN12"' \
--form 'MIN_PHONE="5553423323"' \
--form 'MIN_PHONE_F="!"' \

Example response

If the authentication and required attributes are valid, a success code will be returned.

{
    "STATUS": "SUCCESS",
    "HTTPCODE": "200"
}

Edit devices

Update existing devices on the subscriber account.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMGPSMNG to manage devices.
OPTIONstringYesDetermines the method you will be using. Use EDIT when updating existing devices.
GPS_KEYstringYesThe manufacturer provided unique identifier for the device (20 character max).
ACCOUNT_NUMBERstringYesThe subscriber account number (9 character max).
MIN_PHONEstringYesThe phone number that can be dialed to reach the device (16 character max).
MIN_PHONE_FstringNoThe phone number masking that should be applied (1 character max). Defaults to the first mask data entered on the account’s assigned country.
Note: See the List phone format section below for instructions on how to view the available formats.

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="XMGPSMNG"' \
--form 'OPTION="EDIT"' \
--form 'GPS_KEY="39e99td9z9te"' \
--form 'ACCOUNT_NUMBER="KMN12"' \
--form 'MIN_PHONE="5553423323"' \
--form 'MIN_PHONE_F="/"' \

Example response

If the authentication and required attributes are valid, a success code will be returned.

{
    "STATUS": "SUCCESS",
    "HTTPCODE": "200"
}

Delete devices

Remove existing devices from the account.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMGPSMNG to manage devices.
OPTIONstringYesDetermines the method you will be using. Use DELETE when removing devices.
GPS_KEYstringYesThe manufacturer provided unique identifier for the device (20 character max).
ACCOUNT_NUMBERstringYesThe subscriber account number (9 character max).

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="XMGPSMNG"' \
--form 'OPTION="DELETE"' \
--form 'GPS_KEY="39e99td9z9te"' \
--form 'ACCOUNT_NUMBER="KMN12"' \

Example response

If the authentication and required attributes are valid, a success code will be returned.

{
    "STATUS": "SUCCESS",
    "HTTPCODE": "200"
}

List phone formats

Get a list of phone formats available on the account.

Supported attributes

AttributeTypeRequiredDescription
*setMethodstringYesDetermines the endpoint you are calling. Must be XMGPSMNG to manage devices.
OPTIONstringYesDetermines the method you will be using. Use PHONE_FORMATS when getting the list.
ACCOUNT_NUMBERstringYesThe subscriber account number (9 character max).

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="XMGPSMNG"' \
--form 'OPTION="PHONE_FORMATS"' \
--form 'ACCOUNT_NUMBER="KMN12"' \

Example response 

{
    "DCOUNTRY": [
        {
            "PHONE_FORMAT": "!",
            "PHONE_MASK": "(XXX) XXX-XXXX",
            "PREFIX_START": "10",
            "COUNTRY": "USA",
            "PHONE_LENGTH": "10",
            "AREA_CODE_LENGTH": "03"
        },
        {
            "PHONE_FORMAT": "\"",
            "PHONE_MASK": "XXX-XXXX",
            "PREFIX_START": "07",
            "COUNTRY": "USA",
            "PHONE_LENGTH": "07",
            "AREA_CODE_LENGTH": "00"
        }
    ]
}

Response fields

FieldDescription
PHONE_FORMATThe character assigned to designate the phone number masking.
PHONE_MASKThe format phone numbers will use.
PREFIX_STARTDetermines the location of the phone number prefix (from right to left) within the phone number. For example: given the following phone number: 555-333-1234 with a prefix start of 7, would mean 333 is the prefix.
COUNTRYThe country code assigned to the format.
PHONE_LENGTHThe number of digits a phone number using this format should have.
AREA_CODE_LENGTHHow many digits the number’s area code should have.

Possible error messages

Access denied

Your user does not have access to update the selected account. Contact your central station if you believe this is incorrect.

{
    "STATUS": "ERROR",
    "MESSAGE": "Access Denied",
    "ERRORCODE": "1001"
}

Provide an account number

Verify the ACCOUNT_NUMBER attribute is populated with a valid value.

{
    "STATUS": "ERROR",
    "MESSAGE": "An account number must be provided."
}

Missing GPS key

Verify the GPS_KEY attribute is populated.

{
    "STATUS": "ERROR",
    "MESSAGE": "GPS KEY cannot be blank."
}

Duplicate entry

Verify the GPS_KEY used isn’t already in use on the account.

{
    "STATUS": "ERROR",
    "MESSAGE": "This entry already exists."
}
← Supplemental Information
Get Panel Information →