Skip to main content
Omnitracs Knowledge Base

Change Vehicle UA



The purpose of this web service is to allow the integrator to associate (or disassociate) a particular mobile device to a vehicle. The vehicle is designated by its Vehicle ID and the mobile device is designated by its Unified Address (UA).

The following use cases are supported:

  • Swaps - This is the most common use case. It allows the integrator to specify a non-zero UA thereby replacing the device that was previously assigned to that vehicle.
  • Uninstalls - In this case, the integrator specifies '0000000000' for the UA, thereby causing the vehicle to have no device installed. The vehicle remains in the system with no device until such time as it is deleted or has a new device reinstalled.
  • Reinstalls - In this case, the integrator specifies a non-zero UA for a vehicle which currently has no device.


  • When swapping or reinstalling a device, the system does its best to apply attributes from the previous device to the new device.
  • If you're getting exception #10, the uninstall feature may not be enabled for company. Contact customer service.


void changeVehicleUA(AssetIdentifier vehicle, String vehicleUA) throws WSException

  • vehicle: An AssetIdentifier containing the SCAC and ID of the vehicle to be changed.
  • vehicleUA: A string containing the new serial number (unit address) of the mobile terminal to be associated with the vehicle. Unit addresses are strings containing all digits of maximum length 10. To uninstall a device from a vehicle, specify '0000000000'. To install a device, specify a UA from one of the following ranges:


    0000000001 : 0009999998


    0108000001 : 0108999999


    0100000001 : 0109999998


Authorization Requirements


The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.

Required Application Licenses
- Remote Integration

Required User Permissions
- Can use QTRACS
- Can set up vehicles
- Can see data for all assets OR the vehicle must be in the user's coverage or global group

Customer integrators are authorized to their own company's data only. 


Sample XML Request


Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.











Sample XML Response


An empty response conveys success. If there was an error, an exception would have been thrown.







002 Required field not specified.
003 Company not authorized for integration.
004 User is not authorized.
005 Vehicle invalid.
006 New UA invalid.
007 New UA already used.
008 New UA is not in a valid range for a vehicle type.
009 Cannot change the UA on an auxiliary vehicle.
010 Device uninstall feature not enabled for company.
012 New UA must be different than the vehicle's current UA.
013 TMM Integration must be disabled before installing ES device.

  • Was this article helpful?