Wialon Drivers API: Bind Drivers to Units

Driver assignment is where fleet reports meet payroll: the unit drove, but a person is paid. Wialon keeps the two halves in different places — units live under accounts, drivers live on resources — and joins them with explicit bindings. This page covers the full loop over the Remote API: creating a driver, binding it to a unit, reading the binding history back, and the automatic binding that skips the manual step entirely.

If the request format itself is new to you, read the Postman setup first — everything below is POST against wialon/ajax.html with svc and params, authenticated with a session id.

Create the driver on a resource

Drivers belong to a resource, and creating one is resource/update_driver with id 0 and callMode “create”:

https://hst-api.wialon.com/wialon/ajax.html?sid=<sid>&svc=resource/update_driver&params={"itemId":<resourceId>,"id":0,"callMode":"create","n":"A. Kazlou","c":"1042"}

The short fields are the whole record: n is the name, c is the code, plus optional description (ds) and phone (p). The c code is the field hardware bindings match against later: iButton keys, RFID cards and tachograph driver cards all arrive as codes. Keep it unique per resource and treat it as the driver’s stable identifier — names change, codes should not. The same call with callMode “update” or “delete” and a real id edits or removes the driver.

Send only the fields the call mode expects

One service covers create, update, delete and image reset, and the parameter set is the same for all four:

Two of these cause more trouble than their size suggests. The phone encoding is a genuine trap: an unencoded + in a form-encoded body arrives as a space, and the driver ends up with a phone number that is silently wrong rather than rejected. And f with value 4 makes the driver exclusive, which changes what happens when a second binding arrives — set it deliberately rather than copying it out of an example.

On create and update the call returns the driver id together with the full record; on delete it returns the id and a null. Read the returned record rather than assuming your input was stored verbatim, because the server normalises some fields.

Bind the driver to a unit

Manual binding is resource/bind_unit_driver, with an explicit mode — 1 binds, 0 unbinds:

https://hst-api.wialon.com/wialon/ajax.html?sid=<sid>&svc=resource/bind_unit_driver&params={"resourceId":<resourceId>,"unitId":<unitId>,"driverId":<driverId>,"time":0,"mode":1}

time 0 means now; a past timestamp backdates the binding. Success returns an empty object. Binding is a state change, not a record: one unit has one active driver at a time, and binding a second driver replaces the first. Two consequences follow. First, reports that group by driver (report/get_report_data with a driver grouping) attribute every event to whoever was bound at the event’s time — so a late manual binding rewrites the past as far as the report is concerned. Second, nothing in the API stops you from binding a driver to two units at once; the nonsense is yours to prevent.

Note that the call names both parents — resourceId and unitId — because it touches two objects in two different hierarchies. That is also why its rights requirements are the union of both, which is the subject of the errors section below.

Let the hardware bind instead

Manual binding does not scale past a dozen vehicles. The production answer is a sensor of the “Driver assignment” type: a digital input (iButton reader, RFID, tachograph card slot) whose value is the driver’s code. When a message arrives with a code, Wialon binds the matching driver automatically and unbinds on the next code. Your integration then does nothing at bind time — it only reads.

This is why the c code field matters more than the name, and why the match is exact: the documentation calls out case explicitly — if the message carries avl_driver=000a777e10, the code field must read 000a777e10, after any conversion applied to the parameter. A mistyped code means the hardware “binds” nobody, and the unit’s trips pile up under “no driver” while the dashboard looks fine. When driver-grouped reports show gaps, check code equality first: trailing spaces and leading zeros are the classic cause.

Two failure modes are worth building alerts for rather than discovering at month end. A reader that stops working produces a unit whose trips are all unassigned from a given date — visible as a cliff in any driver-grouped report. And a driver key that has been copied or shared produces a driver bound to two units simultaneously, which the API permits and the payroll department will not.

List the drivers you already have

Drivers come back as part of the resource, not as a searchable catalogue of their own. Search resources with core/search_items and ask for the driver block in the data flags:

svc=core/search_items&params={"spec":{"itemsType":"avl_resource","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":256,"from":0,"to":0}

Combine the bits you need in one call rather than making several: the flags are additive, and asking for drivers and driver groups together costs one request. As everywhere in this API, JSON carries the decimal form, so 0x100 goes into the request as 256.

Driver groups are worth knowing about even if you do not use them yet. They are the natural place for shift teams, subcontractors and depots, and a report grouped by driver group answers a management question that a report grouped by driver does not.

Read the binding state back

The driver object itself carries the binding: bu is the currently bound unit, pu the previously bound one, bt the time of the last binding change. To answer “who drove unit X on Tuesday”, read the drivers with their bu/bt fields and intersect with the unit’s trips for the interval.

That trio is a snapshot, not a history. It tells you the current binding and the one before it, with a timestamp — which is enough for live views and not enough for payroll. If you need the full sequence over a month, the binding changes have to be captured as they happen and stored on your side; a report grouped by driver is the alternative, and it answers the question for a chosen interval without giving you the underlying series.

One subtlety: a unit with no binding in an interval is not an error — it is a real state (yard moves, workshop visits, theft). Export code should emit an explicit “unassigned” row rather than dropping those trips, or the totals will not reconcile with the unit’s own mileage.

The errors you will meet

• Error 4 (invalid input) on update_driver almost always means the resource id is wrong or the session’s access flags do not include driver management. The token page has the flag table.
• Error 7 (no rights) on binding means the token can see the unit but not the resource, or vice versa. Binding touches both objects, so it needs rights on both.
• Error 1002 on create means a driver with that code already exists on the resource. Treat it as a signal to update rather than to retry — a retry loop here creates nothing and looks like a stall.
• A binding call that returns success but changes nothing usually targeted a driver id from a different resource. Ids are only unique within their parent — always qualify with the resource.

The full code table and the reason strings that qualify them are on the error codes page.

Where next

Driver data feeds everything that groups by person: the report execution behind eco-driving scores, the notification engine for driver-specific alerts, and the rate-limit-safe sync that keeps the binding history in your own database — which is what FleetSQL exists to hold. If bindings are business-critical — payroll, billing, compliance — do not read them live per report; sync them on a schedule and join locally.