Cancel Location

6 min

Purpose

Requests a network Cancel Location for the specified SIM.

This operation can be useful if a mobile device is not reporting or appears unreachable. However, please read the information and warning below carefully before using this command.

When a mobile device registers on a network, its location information is stored in multiple network elements (such as the HLR, VLR, MSC, and SGSN). As the device moves between cells or networks, this information is updated so that inbound calls and SMS can be correctly routed.

In rare cases, this location information may become corrupted or not cleared correctly. Issuing a Cancel Location request instructs the network elements to delete any stored location information relating to the SIM. In theory, this forces the device to issue a Location Update the next time it attempts to interact with the network, refreshing its registration details.

Important behaviour notes

Many devices will not issue a location update unless they are power cycled

Power cycling a device will often trigger a location update even without a Cancel Location request

It is strongly recommended that devices:

Periodically power cycle

Can be power cycled remotely (for example, via SMS)

Warning

If a device does not respond to a Cancel Location request with a location update and does not periodically power cycle, issuing this command may result in the device being permanently excluded from network services until manual intervention is possible.

Following a Cancel Location request, the network may be unable to locate the device to deliver SMS messages. As a result, you cannot rely on SMS to remotely power cycle the device after issuing this command.

It is strongly recommended that you test the Cancel Location behaviour using a convenient test unit before applying this operation to live devices in the field.

Do not expect an instant result. The effects of a Cancel Location request may not be seen until the device next power cycles.

Operational Impact

API commands perform live configuration changes.

Changes take effect immediately.

Commands may affect SIM status, service availability, charging, or usage limits.

Requests cannot be undone automatically.

Ensure all parameters are validated before submitting requests to the production environment.

Endpoint

POST https://api.m2miportal.com
Content-Type: application/xml
Accept: application/xml

Request (XML)

<cancel-location version="1" api-id="123456">
  <authentication>
    <username>username</username>
    <password>password</password>
  </authentication>
  <iccid>1234567890123456789</iccid>
</cancel-location>

Response (Success)

<cancel-location-response api-id="123456">
  <api-outcome>Success</api-outcome>
</cancel-location-response>

Response (Failure)

If a request cannot be processed, the response will include:

api-outcome indicating failure

An error description explaining the reason

Failure responses may occur due to:

Invalid authentication credentials

Invalid or unknown identifiers (for example ICCID or MSISDN)

Invalid or missing parameters

Values not permitted for the specified SIM type or account configuration

Insufficient permissions

Integrating systems should validate input data before submission and implement appropriate error handling and logging.