Manage GPS Devices
On this page
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.
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
Attribute | Type | Required | Description |
---|---|---|---|
*setMethod | string | Yes | Determines the endpoint you are calling. Must be XMGPSMNG to manage devices. |
OPTION | string | Yes | Determines the method you will be using. Use ADD when creating new device entries. |
GPS_KEY | string | Yes | The manufacturer provided unique identifier for the device (20 character max). |
ACCOUNT_NUMBER | string | Yes | The subscriber account number (9 character max). |
MIN_PHONE | string | Yes | The phone number that can be dialed to reach the device (16 character max). |
MIN_PHONE_F | string | No | The 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
Attribute | Type | Required | Description |
---|---|---|---|
*setMethod | string | Yes | Determines the endpoint you are calling. Must be XMGPSMNG to manage devices. |
OPTION | string | Yes | Determines the method you will be using. Use EDIT when updating existing devices. |
GPS_KEY | string | Yes | The manufacturer provided unique identifier for the device (20 character max). |
ACCOUNT_NUMBER | string | Yes | The subscriber account number (9 character max). |
MIN_PHONE | string | Yes | The phone number that can be dialed to reach the device (16 character max). |
MIN_PHONE_F | string | No | The 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
Attribute | Type | Required | Description |
---|---|---|---|
*setMethod | string | Yes | Determines the endpoint you are calling. Must be XMGPSMNG to manage devices. |
OPTION | string | Yes | Determines the method you will be using. Use DELETE when removing devices. |
GPS_KEY | string | Yes | The manufacturer provided unique identifier for the device (20 character max). |
ACCOUNT_NUMBER | string | Yes | The 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
Attribute | Type | Required | Description |
---|---|---|---|
*setMethod | string | Yes | Determines the endpoint you are calling. Must be XMGPSMNG to manage devices. |
OPTION | string | Yes | Determines the method you will be using. Use PHONE_FORMATS when getting the list. |
ACCOUNT_NUMBER | string | Yes | The 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
Field | Description |
---|---|
PHONE_FORMAT | The character assigned to designate the phone number masking. |
PHONE_MASK | The format phone numbers will use. |
PREFIX_START | Determines 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. |
COUNTRY | The country code assigned to the format. |
PHONE_LENGTH | The number of digits a phone number using this format should have. |
AREA_CODE_LENGTH | How 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."
}