DigitWeb API

Introduction
Vehicles API
Get Vehicles
Live Data API
Get Vehicle Live Data Get Vehicle Live Map
Trips API
Get Vehicle Trips
Expense Type API
Get Expense Types Add Expense Type Edit Expense Type Delete Expense Type
Expenses API
Add Expense Slip Get Expense Slip Get Expense Slips Edit Expense Slip Delete Expense Slip
Operators API
Get Operators Get Operator Add Operator Edit Operator Delete Operator
User Locations API
Get User Locations Get User Location Add User Location Edit User Location Delete User Location
Fill-to-Fill Report API
Get Fuel Fill Report Add Fuel Fill Slip
Job Cards API
Get Job Cards Get Job Card Add Job Card Edit Job Card Get Job Card History
Routes API
Add Route Update Route Delete Route Cancel Route Assign Route Vehicle Set Webhook Webhook Events
Maersk Integration API
Assign Job Card & Container

Introduction

Before making use of the DigitWeb API service, you will need your .

You can get an under "System Management > Api Keys". The DigitWeb API service operates as a RESTFul service transmitting JSON payloads over HTTPS.

 Download Postman Collection Import into Postman to try every endpoint instantly — just set the api_key collection variable.

All requests require the following HTTPS request headers:

Header Description
application/json
application/json

Get Vehicles

Description

Return List of all Vehicles.

URL

Example Request

curl "https://www.digitweb.co.za/api/getVehicles?api_key=API_KEY&filter=356495049383161"

Method

Parameters

Description
api_key
filter Comma delimited list of IMEI numbers, if left out then all vehicels associated with API Key will be send

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
filter Vehicle filter
cnt Number of vehicle records returned
vehicles Array of vehicle records

Vehicle Record

Description
vehicle_uid Internal vehicle unique number
imei IMEI number of device
device_type Type of device installed
config Config number if available of device type
veh_grp Vehicle Group
name Name Of Vehicle
reg_num Vehicle Registration Number
veh_make Vehicle Make
veh_model Vehicle Model
veh_model_year Vehicle Model Year
veh_vin Vehicle VIN number
start_odo Last Odo Reading Entered
start_odo_date Date Of Last Odo Reading Entered
start_hours Last Hours Reading Entered
start_hours_date Date Of Last Hours Reading Entered
licence_expire_date Vehicle Licence Expiry Date
fuel_capacity Vehicle Fuel Capacity
fuel_factor Calibration multiplier applied to raw fuel-sensor values. Defaults to 1 if no calibration has been set for the vehicle (1 = no scaling)
curent_odo Current Estimated Odo Reading
current_odo_date Date of Current Estimated Odo Reading

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "filter":"",
  "cnt":3,
  "vehicles":
    [
      {
        "vehicle_uid":"42972",
        "imei":"600000000000002",
        "device_type":"DIGIT5b",
        "config":"5.57",
        "veh_grp":"Default",
        "name":"Dev 2",
        "reg_num":"Reg 2",
        "veh_make":"",
        "veh_model":"",
        "veh_model_year":"",
        "veh_vin":"",
        "start_odo":"0",
        "start_odo_date":"0000-00-00",
        "start_hours":"0",
        "start_hours_date":"2000-01-01",
        "licence_expire_date":"2000-01-01",
        "fuel_capacity":"0",
        "fuel_factor":"1"
      },
      {
        "vehicle_uid":"42970",
        "imei":"352503090363828",
        "device_type":"DLITEXS",
        "config":"DLITEXS",
        "veh_grp":"Default",
        "name":"Citroen DS5",
        "reg_num":"CY388427",
        "veh_make":"Citroen",
        "veh_model":"DS",
        "veh_model_year":"2017",
        "veh_vin":"VF7KF5FVADS517030",
        "start_odo":"1000",
        "start_odo_date":"2020-01-01",
        "start_hours":"100",
        "start_hours_date":"2020-01-01",
        "licence_expire_date":"2000-01-01",
        "fuel_capacity":"0",
        "fuel_factor":"1"
      },
      {
        "vehicle_uid":"42971",
        "imei":"356495049383161",
        "device_type":"DIGIT5b",
        "config":"5.45",
        "veh_grp":"Default",
        "name":"Hyundai H1",
        "reg_num":"CY352-800",
        "veh_make":"Hyundai",
        "veh_model":"H1",
        "veh_model_year":"2011",
        "veh_vin":"KMHWH81JMCU419252",
        "start_odo":"0",
        "start_odo_date":"2018-09-19",
        "start_hours":"0",
        "start_hours_date":null,
        "licence_expire_date":null,
        "fuel_capacity":"101",
        "fuel_factor":"1"
      }
    ]
  }

Error Messages

MessageDescription
api key missing Api Key is a required field and are missing
unknown api key The Api Key provided is unknown
api key locked The Api Key has been locked

Example Return Data

{
  "version":"1",
  "result":"error",
  "error_msg":"api key missing"
}


Get Vehicle Live Data

Description

Return List of current information of all Vehicles.

URL

Example Request

curl "https://www.digitweb.co.za/api/getLiveData?api_key=API_KEY&filter=356495049383161"

Method

Parameters

Description
api_key
filter Comma delimited list of IMEI numbers, if left out then all vehicels associated with API Key will be send

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
filter Vehicle filter
cnt Number of vehicle records returned
vehicles Array of vehicle records

Vehicle Record

Description
vehicle_uid Internal vehicle unique number
imei IMEI number of device
device_type Type of device installed
config Config number if available of device type
veh_grp Vehicle Group
name Name Of Vehicle
reg_num Vehicle Registration Number
last_response Last Communication To Server
gps_datetime GPS DateTime (GMT+0)
latitude Vehicle Latitude
longitude Vehicle Longitude
speed Vehicle Speed (km/h)
heading Vehicle Heading
driver_id Driver ID
supp_volt Supply Voltage (V)
int_batt_volt Internal Battery Voltage (V)
int_temp Device Internal Temperature
ext_temp Device External Temperature
fuel_value Vehicle Fuel Value (L)
fuel_percent Vehicle Fuel Percentage (%)

Example Return Data

		
{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "filter":"",
  "cnt":13,
  "vehicles":
    [
      {
        "vehicle_uid":"1",
        "imei":"356495046474088",
        "device_type":"DIGIT5b",
        "config":"5.42",
        "veh_grp":"Default",
        "name":"Cape Town - Sandero",
        "reg_num":"DZ70BS GP",
        "last_response":"2024-08-27 13:04:48",
        "gps_datetime":"2024-08-27 11:04:45",
        "latitude":"-32.825203",
        "longitude":"18.105911",
        "speed":"73",
        "heading":"232",
        "driver_id":"00000000",
        "supp_volt":"14.3",
        "int_batt_volt":"0",
        "int_temp":"30",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"1027",
        "imei":"356495040083430",
        "device_type":"DIGIT5b",
        "config":"5.72",
        "veh_grp":"Default",
        "name":"C4 - DHS384FS",
        "reg_num":"C4 - DHS384FS",
        "last_response":"2024-08-27 13:04:35",
        "gps_datetime":"2024-08-27 11:04:27",
        "latitude":"-26.805235",
        "longitude":"27.793959",
        "speed":"58",
        "heading":"232",
        "driver_id":"17533bb4",
        "supp_volt":"28.7",
        "int_batt_volt":"4.2",
        "int_temp":"35",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"4",
        "imei":"356495048771325",
        "device_type":"DIGIT5b",
        "config":"5.50",
        "veh_grp":"Default",
        "name":"Vito with Fuel",
        "reg_num":"DEMO KZN",
        "last_response":"2024-07-26 20:30:05",
        "gps_datetime":"2024-07-26 18:30:01",
        "latitude":"-28.593563",
        "longitude":"31.401396",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"4.4",
        "int_batt_volt":"3.6",
        "int_temp":"19",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"4717",
        "imei":"358679064882318",
        "device_type":"DIGIT5b",
        "config":"5.64",
        "veh_grp":"Default",
        "name":"ZGF765GP",
        "reg_num":"ZGF765GP",
        "last_response":"2023-01-20 13:48:50",
        "gps_datetime":"2023-01-20 11:48:37",
        "latitude":"-26.61114",
        "longitude":"27.810093",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"1",
        "int_batt_volt":"4.1",
        "int_temp":"36",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"13402",
        "imei":"351628096298875",
        "device_type":"DIGIT5b",
        "config":"5.68",
        "veh_grp":"Default",
        "name":"FUEL TEST",
        "reg_num":"JPM 902 MP",
        "last_response":"2024-05-31 17:36:33",
        "gps_datetime":"2020-10-26 08:49:20",
        "latitude":"-22.184723",
        "longitude":"29.99923",
        "speed":"0",
        "heading":"324",
        "driver_id":"00000000",
        "supp_volt":"27.6",
        "int_batt_volt":"4.2",
        "int_temp":"40",
        "ext_temp":"38",
        "fuel_value":"220",
        "fuel_percent":"46"
      },
      {
        "vehicle_uid":"11772",
        "imei":"351628093385600",
        "device_type":"DIGIT5b",
        "config":"15.64",
        "veh_grp":"Default",
        "name":"BOWSER 015",
        "reg_num":"BV68MYGP",
        "last_response":"2023-11-17 12:54:30",
        "gps_datetime":"2020-09-23 15:08:50",
        "latitude":"-26.355692",
        "longitude":"27.8361",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"1.3",
        "int_batt_volt":"0",
        "int_temp":"0",
        "ext_temp":"0",
        "fuel_value":"316",
        "fuel_percent":"28"
      },
      {
        "vehicle_uid":"11366",
        "imei":"358014091253913",
        "device_type":null,
        "config":null,
        "veh_grp":"Default",
        "name":"WiebeG",
        "reg_num":"CY3809",
        "last_response":null,
        "gps_datetime":null,
        "latitude":null,
        "longitude":null,
        "speed":null,
        "heading":null,
        "driver_id":null,
        "supp_volt":null,
        "int_batt_volt":null,
        "int_temp":null,
        "ext_temp":null,
        "fuel_value":null,
        "fuel_percent":null
      },
      {
        "vehicle_uid":"42972",
        "imei":"600000000000002",
        "device_type":"DIGIT5b",
        "config":"5.57",
        "veh_grp":"Default",
        "name":"Dev 2",
        "reg_num":"Reg 2",
        "last_response":"2024-07-19 00:20:37",
        "gps_datetime":"2024-07-10 08:49:03",
        "latitude":"-33.80969",
        "longitude":"18.66443",
        "speed":"0",
        "heading":"336",
        "driver_id":"00000000",
        "supp_volt":"0",
        "int_batt_volt":"4.2",
        "int_temp":"0",
        "ext_temp":"0",
        "fuel_value":"385",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"42971",
        "imei":"356495049383161",
        "device_type":"DIGIT5b",
        "config":"5.45",
        "veh_grp":"Default",
        "name":"Hyundai H1",
        "reg_num":"CY352-800",
        "last_response":"2022-07-06 14:20:35",
        "gps_datetime":"2022-03-23 22:13:40",
        "latitude":"-33.909687",
        "longitude":"18.561508",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"12.4",
        "int_batt_volt":"4.2",
        "int_temp":"26",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"42970",
        "imei":"352503090363828",
        "device_type":"DLITEXS",
        "config":"DLITEXS",
        "veh_grp":"Default",
        "name":"Citroen DS5",
        "reg_num":"CY388427",
        "last_response":"2022-06-07 23:57:10",
        "gps_datetime":"2022-06-07 21:57:10",
        "latitude":"-25.78421",
        "longitude":"28.326887",
        "speed":"0",
        "heading":"178",
        "driver_id":"",
        "supp_volt":"99",
        "int_batt_volt":"4.2",
        "int_temp":"0",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
      },
      {
        "vehicle_uid":"19500",
        "imei":"351628099936141",
        "device_type":"DIGIT5b",
        "config":"5.74",
        "veh_grp":"Default",
        "name":"CANCELLED B37 FJF613L (B37-1)",
        "reg_num":"B37-1",
        "last_response":"2024-08-27 13:04:33",
        "gps_datetime":"2024-08-27 11:03:56",
        "latitude":"-25.543203",
        "longitude":"26.106613",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"25.4",
        "int_batt_volt":"4.2",
        "int_temp":"41",
        "ext_temp":"39",
        "fuel_value":"670",
        "fuel_percent":"67"
      },
      {
        "vehicle_uid":"19736",
        "imei":"351628099962840",
        "device_type":"DIGIT5b",
        "config":"5.74",
        "veh_grp":"Default",
        "name":"B56 FCY693L",
        "reg_num":"B56",
        "last_response":"2024-08-27 13:03:06",
        "gps_datetime":"2024-08-27 11:02:28",
        "latitude":"-25.675419",
        "longitude":"28.28011",
        "speed":"0",
        "heading":"0",
        "driver_id":"00000000",
        "supp_volt":"25.7",
        "int_batt_volt":"4.2",
        "int_temp":"41",
        "ext_temp":"34",
        "fuel_value":"995",
        "fuel_percent":"100"
      },
      {
        "vehicle_uid":"41750",
        "imei":"999900000000003",
        "device_type":"MDVR",
        "config":"",
        "veh_grp":"Default",
        "name":"DEF",
        "reg_num":"B84_FLB479L",
        "last_response":"2023-10-31 11:14:44",
        "gps_datetime":"2023-10-31 11:14:44",
        "latitude":"-26.401028",
        "longitude":"28.898061",
        "speed":"72",
        "heading":"79",
        "driver_id":"",
        "supp_volt":"0",
        "int_batt_volt":"0",
        "int_temp":"0",
        "ext_temp":"0",
        "fuel_value":"0",
        "fuel_percent":"0"
	  }
	]
  }

Error Messages

MessageDescription
api key missing Api Key is a required field and are missing
unknown api key The Api Key provided is unknown
api key locked The Api Key has been locked

Example Return Data

{
  "version":"1",
  "result":"error",
  "error_msg":"api key missing"
}


Get Vehicle Live Map

Description

Return a Maps of current location of Vehicles.

URL

Example Request

curl "https://www.digitweb.co.za/api/getLiveMap?api_key=API_KEY&map_api_key=MAP_API_KEY&width=600&height=600" --output livemap.png

Method

Parameters

Description
api_key
map_api_key
filter Comma delimited list of IMEI numbers, if left out then all vehicels associated with API Key will be send
width Width of map image (Default: 600)
height Height of map image (Default: 600)
zoom Zoom Level of map image (Default: 13)

The following list shows the approximate level of detail you can expect to see at each zoom level:

1: World
5: Landmass/continent
10: City
15: Streets
20: Buildings

Success Response

Example Return Data

Error Messages

Example Return Data



Get Vehicle Trips

Description

Return List of Vehicle's trips between a specific date start and end date.

URL

Example Request

curl "https://www.digitweb.co.za/api/getTrips?api_key=API_KEY&filter=356495049383161&start_date=2026-05-01&end_date=2026-05-31"

Method

Parameters

Description
api_key
filter Comma delimited list of IMEI numbers, if left out then all vehicels associated with API Key will be send
start_date Start Date of the trips required
end_date End Date of the trips required

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
filter Vehicle filter
start_date Start date of query
end_date End date of query
vehicles Array of vehicle records

Vehicle Record

Description
vehicle_uid Internal vehicle unique number
imei IMEI number of device
trip_cnt Number of trips found
trips Array of vehicle trips

Trip Record

Description
trip_uid Internal trip unique number
start_time Time the trip starts
stop_time Time the trip stops
start_odo Odo reading at the start of the trip
distance Duration of trip in km
duration Duration of trip in seconds
max_speed Max Speed during trip in km/h
fuel_start Fuel value at start of trip
fuel_end Fuel value at end of trip
start_location_lat Start location Latitude
start_location_lng Start location Longitude
start_location Start location of trip
stop_location_lat Stop location Latitude
stop_location_lng Stop location Longitude
stop_location Stop location of trip
driver_name Name of Driver
driver_tag_id Tad Id of Driver

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "cnt":3,
  "vehicles":
    [
      {
        "vehicle_uid":"42972",
        "imei":"600000000000002",
        "filter":"",
        "start_date":"2024-07-01",
        "end_date":"2024-07-31",
        "trip_cnt":5,
        "trips":
        [
        {
          "trip_uid":"9",
          "start_time":"2024-07-01 09:10:58",
          "stop_time":"2024-07-01 23:59:34",
          "start_odo":1427.08,
          "distance":"377.18",
          "duration":"53316",
          "max_speed":"200",
          "fuel_start":"0",
          "fuel_end":"0",
          "start_location_lat":"-33.84083",
          "start_location_lng":"18.65481",
          "start_location":"37 De Villiers Dr, Valmary Park, Cape Town",
          "stop_location_lat":"-33.84089",
          "stop_location_lng":"18.65483",
          "stop_location":"37 De Villiers Dr, Valmary Park, Cape Town",
          "driver_name":null,
          "driver_tag_id":null
        },
        {
          "trip_uid":"10",
          "start_time":"2024-07-02 00:00:29",
          "stop_time":"2024-07-02 23:59:41",
          "start_odo":1804.26,
          "distance":"63.22",
          "duration":"86352",
          "max_speed":"200",
          "fuel_start":"0",
          "fuel_end":"0",
          "start_location_lat":"-33.8406",
          "start_location_lng":"18.65499",
          "start_location":"39 De Villiers Dr, Valmary Park, Cape Town",
          "stop_location_lat":"-33.8255",
          "stop_location_lng":"18.65654",
          "stop_location":"1 Wellington Rd, Wellway Park East, Cape Town",
          "driver_name":null,
          "driver_tag_id":null
        },
        {
          "trip_uid":"11",
          "start_time":"2024-07-03 00:01:14",
          "stop_time":"2024-07-03 16:44:16",
          "start_odo":1867.48,
          "distance":"340.57",
          "duration":"60182",
          "max_speed":"200",
          "fuel_start":"0",
          "fuel_end":"0",
          "start_location_lat":"-33.8226",
          "start_location_lng":"18.66459",
          "start_location":"Wellington Rd, Halali, Cape Town",
          "stop_location_lat":"-33.81964",
          "stop_location_lng":"18.66408",
          "stop_location":"11 Boland Way, Halali, Cape Town","driver_name":null,
          "driver_tag_id":null
        },
        {
          "trip_uid":"14",
          "start_time":"2024-07-09 20:35:23",
          "stop_time":"2024-07-09 23:59:54",
          "start_odo":2208.05,
          "distance":"159.53",
          "duration":"12271",
          "max_speed":"200",
          "fuel_start":"0",
          fuel_end":"0",
          "start_location_lat":"-33.84089",
          "start_location_lng":"18.65483",
          "start_location":"Wiebe House",
          "stop_location_lat":"-33.8159",
          "stop_location_lng":"18.66258",
          "stop_location":"29-31 Boland Way, Vierlanden, Cape Town",
          "driver_name":null,
          "driver_tag_id":null
        },
        {
          "trip_uid":"15",
          "start_time":"2024-07-10 00:00:00",
          "stop_time":"2024-07-10 10:49:03",
          "start_odo":2367.58,
          "distance":"9.11",
          "duration":"38943",
          "max_speed":"200",
          "fuel_start":"0",
          "fuel_end":"0",
          "start_location_lat":"-33.817352",
          "start_location_lng":"18.66316",
          "start_location":"Boland Way, Vierlanden, Durbanville, Western Cape",
          "stop_location_lat":"-33.80969",
          "stop_location_lng":"18.66443",
          "stop_location":"9 De Dam Rd, Vierlanden, Cape Town",
          "driver_name":null,
          "driver_tag_id":null
        }
      ]
    },
    {
      "vehicle_uid":"42970",
      "imei":"352503090363828",
      "trip_cnt":0,
      "trips":[]
    },
    {
      "vehicle_uid":"42971",
      "imei":"356495049383161",
      "trip_cnt":0,
      "trips":[]
    }
  ]
}

Error Messages

MessageDescription
api key missing Api Key is a required field and are missing
unknown api key The Api Key provided is unknown
api key locked The Api Key has been locked

Example Return Data

{
  "version":"1",
  "result":"error",
  "error_msg":"api key missing"
}


Get Expense Types

Description

Return the expense slip types valid for the API Key's user — the type (id 2) plus the user's own expense types. Use the returned value when calling Add Expense Slip.

URL

Example Request

curl "https://www.digitweb.co.za/api/getExpenseTypes?api_key=API_KEY"

Method

Parameters

Description
api_key

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
cnt Number of expense types returned
expense_types Array of expense type records

Expense Type Record

Description
type Type id to send when adding a slip (2 = Fuel)
name Name of the expense type

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "cnt":3,
  "expense_types":
    [
      { "type":2, "name":"Fuel" },
      { "type":14, "name":"Service" },
      { "type":15, "name":"Tyres" }
    ]
}

Error Messages

MessageDescription
api key missing Api Key is a required field and are missing
unknown api key The Api Key provided is unknown
api key locked The Api Key has been locked


Add Expense Type

Description

Create a new expense type for the API Key's user. A duplicate name (for the same user) is rejected. The returned id can be used with Add Expense Slip.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/addExpenseType?api_key=API_KEY" \
  --data-urlencode "expense_name=Toll Fees"

Method

Parameters

api_key may be sent as a query parameter or in the POST body. All other parameters are sent in the POST body.

Description
api_key
expense_name Name of the new expense type (max 255 chars)

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
type Id of the newly created expense type
name Name of the new expense type

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "type":21,
  "name":"Toll Fees"
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
expense_name is required expense_name missing or blank
expense_name is too long (max 255 chars) Name exceeds 255 characters
expense type already exists A non-deleted type with that name already exists for this user


Edit Expense Type

Description

Rename an expense type owned by the API Key's user. A duplicate name on another of the user's types is rejected. The built-in Fuel type (2) cannot be edited.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/editExpenseType?api_key=API_KEY" \
  --data-urlencode "type=21" \
  --data-urlencode "expense_name=Toll & Gate Fees"

Method

Parameters

Description
api_key
type Expense type id (from Get Expense Types)
expense_name New name for the expense type (max 255 chars)

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "type":21,
  "name":"Toll & Gate Fees"
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
type is required and must be an integer type missing or not numeric
expense type not found or not linked to this api key The type does not belong to this user
expense_name is required / too long Name missing, blank, or over 255 chars
expense type already exists Another of the user's types already has that name


Delete Expense Type

Description

Delete an expense type owned by the API Key's user. This is a soft delete (the type is hidden but existing slips that reference it keep their type and name). The built-in Fuel type (2) cannot be deleted.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/deleteExpenseType?api_key=API_KEY" \
  --data-urlencode "type=21"

Method

Parameters

Description
api_key
type Expense type id (from Get Expense Types)

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "type":21
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
type is required and must be an integer type missing or not numeric
expense type not found or not linked to this api key The type does not belong to this user


Add Expense Slip

Description

Add a manual expense slip for a vehicle. The vehicle must be linked to the API Key's user.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/addExpenseSlip?api_key=API_KEY" \
  --data-urlencode "vehicle_uid=42971" \
  --data-urlencode "type=2" \
  --data-urlencode "amount=1024.75" \
  --data-urlencode "qty=45.5" \
  --data-urlencode "event_datetime=2026-05-04 08:12:00" \
  --data-urlencode "slip_number=INV-1023" \
  --data-urlencode "comment=Full tank"

Method

Parameters

api_key may be sent as a query parameter or in the POST body. All other parameters are sent in the POST body.

Description
api_key
vehicle_uid Internal vehicle unique number (must be linked to this API Key's user)
type 2 for Fuel, or an expense type id from Get Expense Types
amount Slip amount (must be greater than 0)
event_datetime Slip date/time (format: yyyy-mm-dd hh:mm:ss, or yyyy-mm-dd)
qty Quantity (e.g. litres for fuel). Defaults to 0
slip_number Slip / receipt number
comment Free text comment

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
slip_uid Unique id of the newly created slip

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "slip_uid":80214
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
vehicle_uid is required and must be an integer vehicle_uid missing or not numeric
vehicle not found or not linked to this api key The vehicle is not linked to this user
type is invalid ... type is not 2 (Fuel) or a valid expense type id
amount is required and must be greater than 0 amount missing or not positive
event_datetime is required ... event_datetime missing or wrong format


Get Expense Slip

Description

Return a single expense slip by its id. The slip must belong to a vehicle linked to the API Key's user.

URL

Example Request

curl "https://www.digitweb.co.za/api/getExpenseSlip?api_key=API_KEY&slip_uid=80211"

Method

Parameters

Description
api_key
slip_uid Unique id of the slip

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
slip Slip record
Description
slip_uid Unique id of the slip
vehicle_uid Internal vehicle unique number
type Slip type id (2 = Fuel)
type_name Slip type name
slip_number Slip / receipt number
slip_qty Quantity
slip_amount Amount
event_datetime Slip date/time
comment Free text comment

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "slip":
    {
      "slip_uid":80211,
      "vehicle_uid":42971,
      "type":2,
      "type_name":"Fuel",
      "slip_number":"INV-1023",
      "slip_qty":"45.50",
      "slip_amount":"1024.75",
      "event_datetime":"2026-05-04 08:12:00",
      "comment":"Full tank"
    }
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
slip_uid is required and must be an integer slip_uid missing or not numeric
slip not found or not linked to this api key The slip does not belong to this user


Get Expense Slips

Description

Return the expense slips for a vehicle between a start and end date. Returns expense / fuel slips only (it does not include the Fill-to-Fill report's automatic fuel-fill slips).

URL

Example Request

curl "https://www.digitweb.co.za/api/getExpenseSlips?api_key=API_KEY&vehicle_uid=42971&start_date=2026-05-01&end_date=2026-05-31"

Method

Parameters

Description
api_key
vehicle_uid Internal vehicle unique number (must be linked to this API Key's user)
start_date Start date of the slips required (format: yyyy-mm-dd)
end_date End date of the slips required (format: yyyy-mm-dd)

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
vehicle_uid Vehicle queried
start_date Start date of query
end_date End date of query
cnt Number of slips returned
slips Array of slip records

Slip Record

Description
slip_uid Unique id of the slip
vehicle_uid Internal vehicle unique number
type Slip type id (2 = Fuel)
type_name Slip type name
slip_number Slip / receipt number
slip_qty Quantity
slip_amount Amount
event_datetime Slip date/time
comment Free text comment

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "vehicle_uid":42971,
  "start_date":"2026-05-01 00:00:00",
  "end_date":"2026-05-31 23:59:59",
  "cnt":2,
  "slips":
    [
      {
        "slip_uid":80211,
        "vehicle_uid":42971,
        "type":2,
        "type_name":"Fuel",
        "slip_number":"INV-1023",
        "slip_qty":"45.50",
        "slip_amount":"1024.75",
        "event_datetime":"2026-05-04 08:12:00",
        "comment":"Full tank"
      },
      {
        "slip_uid":80212,
        "vehicle_uid":42971,
        "type":14,
        "type_name":"Service",
        "slip_number":"S-558",
        "slip_qty":"0",
        "slip_amount":"3500.00",
        "event_datetime":"2026-05-18 00:00:00",
        "comment":"60 000 km service"
      }
    ]
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
vehicle not found or not linked to this api key The vehicle is not linked to this user
start_date is required / end_date is required Date missing or wrong format


Edit Expense Slip

Description

Update an existing expense slip. The slip must belong to a vehicle linked to the API Key's user. Any omitted field keeps its current value. The slip type cannot be changed.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/editExpenseSlip?api_key=API_KEY" \
  --data-urlencode "slip_uid=80211" \
  --data-urlencode "amount=1100.00" \
  --data-urlencode "comment=Corrected amount"

Method

Parameters

Description
api_key
slip_uid Unique id of the slip to update
amount Slip amount (must be greater than 0)
qty Quantity
slip_number Slip / receipt number
event_datetime Slip date/time (format: yyyy-mm-dd hh:mm:ss)
comment Free text comment

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "slip_uid":80211
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
slip_uid is required and must be an integer slip_uid missing or not numeric
slip not found or not linked to this api key The slip does not belong to this user
amount must be greater than 0 amount not positive


Delete Expense Slip

Description

Delete an existing expense slip. The slip must belong to a vehicle linked to the API Key's user.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/deleteExpenseSlip?api_key=API_KEY" \
  --data-urlencode "slip_uid=80211"

Method

Parameters

Description
api_key
slip_uid Unique id of the slip to delete

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "slip_uid":80211
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
slip_uid is required and must be an integer slip_uid missing or not numeric
slip not found or not linked to this api key The slip does not belong to this user


Get Operators

Description

Return all operators (drivers) linked to the API Key's user.

URL

Example Request

curl "https://www.digitweb.co.za/api/getOperators?api_key=API_KEY"

Method

Parameters

Description
api_key

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
cnt Number of operators returned
operators Array of operator records

Operator Record

Description
operator_uid Internal operator unique number
id_number ID number
fullname Full name
tag_id Tag / iButton id (driver id if no tag)
default_trip_type Default trip type id
mobile_number Mobile number
home_number Home number
driver_licence_expiry_datetime Driver licence expiry
pdp_expiry_datetime PDP expiry
dgp_expiry_datetime DGP expiry
mc_expiry_datetime Medical certificate expiry
employee_number Employee number
current_points Current demerit points
home_address Home address
next_of_kin Next of kin
next_of_kin_contact_number Next of kin contact number
active_flag 1 = active, 0 = inactive
email_address Email address

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "cnt":1,
  "operators":
    [
      {
        "operator_uid":3312,
        "id_number":"8001015009087",
        "fullname":"John Smith",
        "tag_id":"17533BB4",
        "default_trip_type":0,
        "mobile_number":"0820000000",
        "home_number":"",
        "driver_licence_expiry_datetime":"2027-03-31 00:00:00",
        "pdp_expiry_datetime":"2026-03-31 00:00:00",
        "dgp_expiry_datetime":"2001-01-01 00:00:00",
        "mc_expiry_datetime":"2001-01-01 00:00:00",
        "employee_number":"EMP-102",
        "current_points":"0",
        "home_address":"",
        "next_of_kin":"",
        "next_of_kin_contact_number":"",
        "active_flag":1,
        "email_address":"john@example.com"
      }
    ]
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems


Get Operator

Description

Return a single operator linked to the API Key's user. The record fields are the same as Get Operators.

URL

Example Request

curl "https://www.digitweb.co.za/api/getOperator?api_key=API_KEY&operator_uid=3312"

Method

Parameters

Description
api_key
operator_uid Internal operator unique number

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "operator": { "operator_uid":3312, "fullname":"John Smith", "...":"..." }
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
operator_uid is required and must be an integer operator_uid missing or not numeric
operator not found or not linked to this api key The operator is not linked to this user


Add Operator

Description

Create an operator and link it to the API Key's user. The tag_id must be globally unique.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/addOperator?api_key=API_KEY" \
  --data-urlencode "fullname=John Smith" \
  --data-urlencode "id_number=8001015009087" \
  --data-urlencode "tag_id=17533BB4" \
  --data-urlencode "mobile_number=0820000000" \
  --data-urlencode "driver_licence_expiry_datetime=2027-03-31"

Method

Parameters

api_key may be sent as a query parameter or in the POST body. All other parameters are sent in the POST body.

Description
api_key
fullname Full name
id_number ID number
tag_id Tag id (use the driver's id number if no tag). Must be globally unique
default_trip_type Default trip type id (default 0)
active_flag 1 = active (default), 0 = inactive
mobile_number / home_number Contact numbers
employee_number / current_points Employee number / demerit points
home_address / next_of_kin / next_of_kin_contact_number / email_address Extra details
driver_licence_expiry_datetime / pdp_expiry_datetime / dgp_expiry_datetime / mc_expiry_datetime Expiry dates (yyyy-mm-dd). Default 2001-01-01

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "operator_uid":3312
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
fullname is required / id_number is required / tag_id is required A required field was blank
tag_id already exists Another operator already uses that tag_id
expiry dates must be yyyy-mm-dd An expiry date was in the wrong format


Edit Operator

Description

Update an operator linked to the API Key's user. Any omitted field keeps its current value. tag_id must stay globally unique.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/editOperator?api_key=API_KEY" \
  --data-urlencode "operator_uid=3312" \
  --data-urlencode "mobile_number=0830000000" \
  --data-urlencode "active_flag=1"

Method

Parameters

Description
api_key
operator_uid Operator to update
(any field from Add Operator) fullname, id_number, tag_id, default_trip_type, active_flag, contact numbers, expiry dates, etc.

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "operator_uid":3312
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
operator not found or not linked to this api key The operator is not linked to this user
fullname / id_number / tag_id may not be blank A required field was cleared
tag_id already exists Another operator already uses that tag_id
expiry dates must be yyyy-mm-dd An expiry date was in the wrong format


Delete Operator

Description

Delete an operator linked to the API Key's user.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/deleteOperator?api_key=API_KEY" \
  --data-urlencode "operator_uid=3312"

Method

Parameters

Description
api_key
operator_uid Operator to delete

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "operator_uid":3312
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
operator not found or not linked to this api key The operator is not linked to this user


Get User Locations

Description

Return all user locations (geofences / points) owned by the API Key's user, including the polygon "points" geometry. "points" is a JSON array of {lat,lng} vertices for polygon locations, and an empty string for point locations.

URL

Example Request

curl "https://www.digitweb.co.za/api/getUserLocations?api_key=API_KEY"

Method

Parameters

Description
api_key

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
cnt Number of locations returned
locations Array of location records

Location Record

Description
user_location_uid Internal location unique number
latitude Latitude
longitude Longitude
description Location name / label
icon Icon
color Colour
radius Geofence radius
location_type 'point' or 'polygon'
points Polygon geometry: JSON array of {lat,lng} vertices (empty string for points)
speed Speed limit for the zone
no_go 1 = no-go zone
only_push 1 = push notifications only

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "cnt":2,
  "locations":
    [
      {
        "user_location_uid":5521,
        "latitude":-33.84089,
        "longitude":18.65483,
        "description":"Head Office",
        "icon":"",
        "color":"blue",
        "radius":150,
        "location_type":"point",
        "points":"",
        "speed":0,
        "no_go":0,
        "only_push":0
      },
      {
        "user_location_uid":5522,
        "latitude":-33.8225,
        "longitude":18.6646,
        "description":"Depot Yard (No-Go Zone)",
        "icon":"",
        "color":"red",
        "radius":0,
        "location_type":"polygon",
        "points":"[{\"lat\":-33.8221,\"lng\":18.6640},{\"lat\":-33.8221,\"lng\":18.6652},{\"lat\":-33.8230,\"lng\":18.6652},{\"lat\":-33.8230,\"lng\":18.6640}]",
        "speed":40,
        "no_go":1,
        "only_push":0
      }
    ]
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems


Get User Location

Description

Return a single user location owned by the API Key's user. The fields are the same as Get User Locations (including the polygon "points" geometry).

URL

Example Request

curl "https://www.digitweb.co.za/api/getUserLocation?api_key=API_KEY&user_location_uid=5521"

Method

Parameters

Description
api_key
user_location_uid Internal location unique number

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "location":
    {
      "user_location_uid":5521,
      "latitude":-33.84089,
      "longitude":18.65483,
      "description":"Head Office",
      "icon":"",
      "color":"blue",
      "radius":150,
      "location_type":"point",
      "points":"",
      "speed":0,
      "no_go":0,
      "only_push":0
    }
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
user_location_uid is required and must be an integer user_location_uid missing or not numeric
location not found or not linked to this api key The location does not belong to this user


Add User Location

Description

Create a user location owned by the API Key's user.

URL

Method

Parameters

api_key may be sent as a query parameter or in the POST body. All other parameters are sent in the POST body.

Description
api_key
description Location name / label
latitude Latitude (-90..90)
longitude Longitude (-180..180)
color Colour (default 'blue')
radius Geofence radius (default 1)
location_type 'point' (default) or 'polygon'
points Polygon geometry JSON (for location_type=polygon)
icon Icon
speed / no_go / only_push Zone speed limit / no-go flag / push-only flag (default 0)

Example Request (polygon with points)

For a polygon, set and send as a JSON array of {lat,lng} vertices. The latitude/longitude you send is the polygon's centre/reference point.

curl -X POST "https://www.digitweb.co.za/api/addUserLocation?api_key=API_KEY" \
  --data-urlencode "description=Depot Yard (No-Go Zone)" \
  --data-urlencode "latitude=-33.8225" \
  --data-urlencode "longitude=18.6646" \
  --data-urlencode "color=red" \
  --data-urlencode "location_type=polygon" \
  --data-urlencode "no_go=1" \
  --data-urlencode "speed=40" \
  --data-urlencode 'points=[{"lat":-33.8221,"lng":18.6640},{"lat":-33.8221,"lng":18.6652},{"lat":-33.8230,"lng":18.6652},{"lat":-33.8230,"lng":18.6640}]'

Example Request (point)

curl -X POST "https://www.digitweb.co.za/api/addUserLocation?api_key=API_KEY" \
  --data-urlencode "description=Head Office" \
  --data-urlencode "latitude=-33.84089" \
  --data-urlencode "longitude=18.65483" \
  --data-urlencode "color=blue" \
  --data-urlencode "radius=150"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "user_location_uid":5521
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
description is required description was blank
latitude / longitude is required and must be numeric Coordinate missing or not numeric
latitude / longitude out of range Coordinate outside valid bounds
location_type must be 'point' or 'polygon' Invalid location_type


Edit User Location

Description

Update a user location owned by the API Key's user. Any omitted field keeps its current value.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/editUserLocation?api_key=API_KEY" \
  --data-urlencode "user_location_uid=5521" \
  --data-urlencode "description=Head Office" \
  --data-urlencode "color=green" \
  --data-urlencode "radius=200"

Method

Parameters

Description
api_key
user_location_uid Location to update
(any field from Add User Location) description, latitude, longitude, color, radius, location_type, points, icon, speed, no_go, only_push

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "user_location_uid":5521
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
location not found or not linked to this api key The location does not belong to this user
description may not be blank description was cleared
latitude / longitude out of range Coordinate outside valid bounds


Delete User Location

Description

Delete a user location owned by the API Key's user.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/deleteUserLocation?api_key=API_KEY" \
  --data-urlencode "user_location_uid=5521"

Method

Parameters

Description
api_key
user_location_uid Location to delete

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "user_location_uid":5521
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
location not found or not linked to this api key The location does not belong to this user


Get Fuel Fill Report

Description

Return the Fill-to-Fill fuel report for a vehicle between two dates. Each row is a detected fuel fill (from fuel_events) with its linked slip, the odo/hours at the fill, the distance and litres used since the previous fill, and consumption (km/l and l/hr). Dates use the API Key user's GMT offset. Read-only — it returns already-processed data and does not trigger trip processing.

URL

Example Request

curl "https://www.digitweb.co.za/api/getFuelFillReport?api_key=API_KEY&vehicle_uid=13402&start_date=2026-05-01&end_date=2026-05-31"

Method

Parameters

Description
api_key
vehicle_uid Internal vehicle unique number (must be linked to this API Key's user)
start_date Start date (yyyy-mm-dd)
end_date End date (yyyy-mm-dd, inclusive). Max range 366 days

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
vehicle_uid / imei / vehicle_name / registration_number Vehicle identity
fuel_factor Vehicle fuel factor applied to fill litres
start_date / end_date Query range
cnt Number of fills returned
fills Array of fill records

Fill Record

Description
event_uid Internal fuel-event id
event_date / event_time Date and time of the fill (vehicle GMT)
slip_number / slip_uid Linked slip (null if no slip captured)
slip_qty / slip_amount Slip quantity and amount
slip_diff slip_qty minus measured fill_qty (null if no slip)
fill_qty Measured litres added (after fuel_factor)
operator_uid / operator_name Driver at the time of the fill
odo / hours Odometer (km) and engine hours at the fill
fuel_level_before Tank level just before the fill (null if unknown)
fuel_level_after Tank level after the fill
latitude / longitude Fill location coordinates
location Fill location name (user location or reverse-geocoded address)
trip_uid Trip immediately preceding the fill
distance Km travelled since the previous fill (null on first fill)
duration Seconds of engine time since the previous fill
fuel_used Litres used since the previous fill (clamped to ≥ 0)
consumption_km_per_l distance / fuel_used (null if not computable)
consumption_l_per_hr fuel_used / hours since previous fill (null if not computable)

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "vehicle_uid":13402,
  "imei":"351628096298875",
  "vehicle_name":"FUEL TEST",
  "registration_number":"JPM 902 MP",
  "fuel_factor":1,
  "start_date":"2026-05-01",
  "end_date":"2026-05-31",
  "cnt":2,
  "fills":
    [
      {
        "event_uid":90233,
        "event_date":"2026-05-04",
        "event_time":"08:12:00",
        "slip_number":"INV-1023",
        "slip_uid":80211,
        "slip_qty":"45.50",
        "slip_amount":"1024.75",
        "slip_diff":1.5,
        "fill_qty":44,
        "operator_uid":3312,
        "operator_name":"John Smith",
        "odo":120345,
        "hours":2103,
        "fuel_level_before":12,
        "fuel_level_after":56,
        "latitude":-22.184723,
        "longitude":29.99923,
        "location":"Engen Musina",
        "trip_uid":55012,
        "distance":null,
        "duration":null,
        "fuel_used":0,
        "consumption_km_per_l":null,
        "consumption_l_per_hr":null
      },
      {
        "event_uid":90240,
        "event_date":"2026-05-18",
        "event_time":"16:40:00",
        "slip_number":"INV-1099",
        "slip_uid":80240,
        "slip_qty":"50.00",
        "slip_amount":"1150.00",
        "slip_diff":2,
        "fill_qty":48,
        "operator_uid":3312,
        "operator_name":"John Smith",
        "odo":120789,
        "hours":2119,
        "fuel_level_before":8,
        "fuel_level_after":56,
        "latitude":-22.95,
        "longitude":30.48,
        "location":"Total Louis Trichardt",
        "trip_uid":55061,
        "distance":444,
        "duration":57600,
        "fuel_used":48,
        "consumption_km_per_l":9.25,
        "consumption_l_per_hr":3
      }
    ]
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
vehicle_uid is required and must be an integer vehicle_uid missing or not numeric
vehicle not found or not linked to this api key The vehicle is not linked to this user
start_date / end_date is required Date missing or wrong format
start_date may not be after end_date Range reversed
date range may not exceed 366 days Range too large


Add Fuel Fill Slip

Description

Link a fuel slip to a detected fuel fill event — pass the you got from Get Fuel Fill Report. The slip is stored as a fill slip (type 1) with its datetime taken from the fill event, so it reconciles against that fill in the report. Only one slip is allowed per fill; delete or edit the existing one (via deleteExpenseSlip / editExpenseSlip on the returned slip_uid) to change it.

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/addFuelFillSlip?api_key=API_KEY" \
  --data-urlencode "event_uid=90240" \
  --data-urlencode "qty=50" \
  --data-urlencode "amount=1150.00" \
  --data-urlencode "slip_number=INV-1099"

Method

Parameters

api_key may be sent as a query parameter or in the POST body. All other parameters are sent in the POST body.

Description
api_key
event_uid Fuel fill event id from Get Fuel Fill Report (must be on a vehicle linked to this user)
qty Slip quantity in litres (must be greater than 0)
amount Slip amount
slip_number Slip / receipt number

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "slip_uid":80240,
  "event_uid":90240
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
event_uid is required and must be an integer event_uid missing or not numeric
fuel fill event not found or not linked to this api key No such fill on a vehicle linked to this user
qty is required and must be greater than 0 qty missing or not positive
a slip already exists for this fill ... The fill already has a slip; delete or edit it instead


Get Job Cards

Description

List job cards belonging to this API Key's user. Returns up to 1000 most-recent rows. Use the date and reference filters to narrow if needed. The payload is returned re-parsed into a JSON object so consumers don't have to double-decode.

URL

Example Request

curl "https://www.digitweb.co.za/api/getJobCards?api_key=API_KEY&from_date=2026-06-01&to_date=2026-06-30"

Method

Parameters

Description
api_key
from_date Earliest created_datetime to include (yyyy-mm-dd, inclusive)
to_date Latest created_datetime to include (yyyy-mm-dd, inclusive)
external_reference Exact-match filter on the extracted external_reference

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
cnt Number of job cards returned
job_cards Array of job card records (job_card_uid, created_datetime, source_ip, external_reference, payload)

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
from_date / to_date format error (yyyy-mm-dd) Date filter in the wrong format


Get Job Card

Description

Return a single job card by id, owned by this API Key's user. The payload is returned re-parsed into a JSON object.

URL

Example Request

curl "https://www.digitweb.co.za/api/getJobCard?api_key=API_KEY&job_card_uid=1234"

Method

Parameters

Description
api_key
job_card_uid Unique id of the job card

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "job_card":
    {
      "job_card_uid":1234,
      "created_datetime":"2026-06-03 09:12:30",
      "source_ip":"196.x.x.x",
      "external_reference":"JHB20260301857",
      "payload": { "SiteReferenceNumber":"JHB20260301857", "...": "..." }
    }
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
job_card_uid is required and must be an integer job_card_uid missing or not numeric
job card not found or not linked to this api key The job card does not belong to this user


Add Job Card

Description

Receive a JSON job-card payload from an external system and store it for this API Key's user. The full payload is preserved verbatim. Every known top-level JSON field (and the nested SiteAddress object) is also extracted into named columns so jobs can be filtered, reported on, and linked without re-parsing the JSON. See the Extracted Fields table below for the column map.

Extracted Fields

The following JSON keys are mapped to columns when present. Anything else stays in the verbatim payload only.

JSON KeyColumnType
CompanyIdcompany_idvarchar(50)
Consignorconsignorvarchar(200)
Consigneeconsigneevarchar(200)
SiteNamesite_namevarchar(200)
SiteLastnamesite_lastnamevarchar(100)
SiteReferenceNumbersite_reference_number (+ external_reference)varchar(100), indexed
TripsheetReferencetripsheet_referencevarchar(100)
SiteContactNumbersite_contact_numbervarchar(50)
SiteEmailsite_emailvarchar(200)
SiteAddress.Line1site_address_line1varchar(200)
SiteAddress.Line2site_address_line2varchar(200)
SiteAddress.Line3site_address_line3varchar(200)
SiteAddress.Suburbsite_address_suburbvarchar(100)
SiteAddress.Citysite_address_cityvarchar(100)
SiteAddress.PostalCodesite_address_postal_codevarchar(20)
DueDatedue_datedatetime (ISO 8601 in → UTC datetime out)
ReferenceNumberreference_numbervarchar(100)
Instructionsinstructionstext
Latitudelatitudedouble
Longitudelongitudedouble
DriverNamedriver_namevarchar(200)
DriverUsernamedriver_usernamevarchar(100)
DriverMobileNumberdriver_mobile_numbervarchar(50)
DriverExternaldriver_externalvarchar(50)
IsDeliveryis_deliverytinyint (0/1)
IsPriorityis_prioritytinyint (0/1)
PlannedSequenceplanned_sequenceint
SyncStatesync_stateint
TripStopIdtrip_stop_idint
LoadAssignmentIdload_assignment_idint, indexed
LoadAssignmentTransactionNoload_assignment_transaction_novarchar(100)
TripTransactionNotrip_transaction_novarchar(100), indexed

URL

Example Request

Send the JSON as the raw POST body with Content-Type: application/json:

curl -X POST "https://www.digitweb.co.za/api/addJobCard?api_key=API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @job_card.json

Or as a form field if you can't change the Content-Type:

curl -X POST "https://www.digitweb.co.za/api/addJobCard?api_key=API_KEY" \
  --data-urlencode "payload={\"SiteReferenceNumber\":\"JHB20260301857\",\"TripTransactionNo\":\"TR26030285\",\"DueDate\":\"2026-03-26T16:21:00+02:00\"}"

Method

Parameters

Description
api_key (query string or X-Api-Key header)
payload JSON object. Send as the raw POST body with Content-Type: application/json, or as a "payload" form field containing the JSON string

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
job_card_uid Unique id of the stored job card
external_reference Convenience id extracted from the payload's SiteReferenceNumber / ReferenceNumber (null if neither was present)

Example Return Data

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "job_card_uid":1234,
  "external_reference":"JHB20260301857"
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
payload is required ... No JSON body and no "payload" POST field
payload is not valid JSON The body couldn't be parsed as JSON


Edit Job Card

Description

Replace the stored JSON payload of a job card owned by this API Key's user. The body is the new JSON (same options as Add Job Card: raw JSON body OR payload form field). The indexed external_reference is refreshed from the new payload's SiteReferenceNumber / ReferenceNumber.

When sending a raw JSON body, api_key and job_card_uid must be in the query string (since PHP's $_POST is empty for JSON bodies).

URL

Example Request

curl -X POST "https://www.digitweb.co.za/api/editJobCard?api_key=API_KEY&job_card_uid=1234" \
  -H "Content-Type: application/json" \
  --data-binary @job_card.json

Method

Parameters

Description
api_key
job_card_uid Unique id of the job card to update
payload New JSON object (raw body or "payload" form field)

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "job_card_uid":1234,
  "external_reference":"JHB20260301857"
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
job_card_uid is required and must be an integer job_card_uid missing or not numeric
job card not found or not linked to this api key The job card does not belong to this user
payload is required ... No JSON body and no "payload" POST field
payload is not valid JSON The body couldn't be parsed as JSON


Get Job Card History

Description

Return the append-only audit history of a job card. Every Add Job Card writes a create snapshot, and every Edit Job Card writes an edit snapshot — so the full edit history is replayable. Snapshots are returned oldest first; diff consecutive payloads to observe what changed.

URL

Example Request

curl "https://www.digitweb.co.za/api/getJobCardHistory?api_key=API_KEY&job_card_uid=1234"

Method

Parameters

Description
api_key
job_card_uid Unique id of the job card

Success Response

Description
version Version Number of API
result Success or Error
error_msg Description of error
job_card_uid Job card the history belongs to
cnt Number of snapshots returned
history Array of snapshots (history_uid, snapshot_datetime, action: 'create'/'edit', changed_by_user_uid, source_ip, external_reference, payload)

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
job_card_uid is required and must be an integer job_card_uid missing or not numeric
job card not found or not linked to this api key The job card does not belong to this user


Add Route

Description

Create a route in route planning/management from an ordered list of stops. The endpoint computes the driving path and timing between stops (via the Google Directions API, cached), and — if a is supplied — schedules that vehicle onto the new route in the same call.

Each stop is either an existing saved location () or a raw / pair. For a raw lat/lng stop, if a saved location already exists at (approximately) that point it is reused; otherwise a new location is created (de-duplicated import).

URL

Method

Parameters

api_key may be sent as a query parameter or in the POST body. Other parameters are sent form-encoded (or as an application/json body). is a JSON array.

Description
api_key
route_name Name for the route
route_datetime Planned start, format YYYY-MM-DD HH:MM[:SS] (or YYYY-MM-DD)
stops JSON array of at least 2 stops (see below)
round_trip 0 (default) or 1 (return to the first stop)
vehicle_uid If given and owned by this key, the route is scheduled to this vehicle
webhooks true to emit route/stop webhooks for this route (default false). The endpoint + signing secret come from the account webhook config (see Set Webhook).

The array

An ordered JSON array. Each element is EITHER a saved-location reference OR a raw coordinate:

Description
user_location_uid A saved location owned by this key (e.g. one created via Add User Location)
lat / lng Raw coordinates (used instead of user_location_uid); reused or created as a saved location
name Optional label for a lat/lng stop (default 'Stop N')
stop_time Optional minutes spent at the stop (default 0)

Example Request

curl -X POST "https://www.digitweb.co.za/api/addRoute?api_key=API_KEY" \
  --data-urlencode "route_name=Monday CT Deliveries" \
  --data-urlencode "route_datetime=2026-07-28 08:00" \
  --data-urlencode "round_trip=1" \
  --data-urlencode "vehicle_uid=1234" \
  --data-urlencode 'stops=[{"lat":-33.9249,"lng":18.4241,"name":"Depot","stop_time":10},{"user_location_uid":5521,"stop_time":15},{"lat":-33.9010,"lng":18.5123,"name":"Client B","stop_time":5}]'

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "route_uid":87421,
  "route_name":"Monday CT Deliveries",
  "route_datetime":"2026-07-28 08:00:00",
  "end_datetime":"2026-07-28 09:14:22",
  "total_distance_km":42.7,
  "drive_time_secs":3262,
  "round_trip":1,
  "stop_count":3,
  "vehicle_scheduled":true,
  "vehicle_uid":1234,
  "stops":[
    {"stop_order":1,"user_location_uid":5610,"name":"Depot","lat":-33.9249,"lng":18.4241,"reused":false},
    {"stop_order":2,"user_location_uid":5521,"name":"Client A","lat":-33.86,"lng":18.63,"reused":true},
    {"stop_order":3,"user_location_uid":5611,"name":"Client B","lat":-33.901,"lng":18.5123,"reused":false}
  ]
}

Error Messages

MessageDescription
api key missing / unknown api key / api key locked API Key problems
method not allowed, use POST The request was not a POST
route_name is required route_name was blank
route_datetime is required, format YYYY-MM-DD HH:MM[:SS] Missing or badly formatted start date/time
stops is required and must be a JSON array stops missing or not valid JSON
a route needs at least 2 stops Fewer than 2 stops supplied
stop #N needs either user_location_uid, or numeric lat and lng A stop had neither a valid location id nor coordinates
stop #N lat/lng out of range Coordinates outside -90..90 / -180..180
location not found or not linked to this api key A user_location_uid does not belong to this user
vehicle not found or not linked to this api key vehicle_uid not owned by this user


Assign Route Vehicle

Description

Schedule (or re-assign / clear) a vehicle on an existing route. Pass to unassign.

URL

Method

Parameters

Description
api_key
route_uid A route owned by this key
vehicle_uid A vehicle owned by this key; use 0 to unassign

Example Request

curl -X POST "https://www.digitweb.co.za/api/assignRouteVehicle?api_key=API_KEY" \
  --data-urlencode "route_uid=87421" \
  --data-urlencode "vehicle_uid=1234"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "route_uid":87421,
  "vehicle_uid":1234,
  "scheduled":true
}

Error Messages

MessageDescription
route_uid is required route_uid missing or not positive
route not found or not linked to this api key The route does not belong to this user
vehicle_uid is required (use 0 to unassign) vehicle_uid not supplied
vehicle not found or not linked to this api key vehicle_uid not owned by this user


Update Route

Description

Update an existing route's details, and optionally replace its stops. Only the fields you send are changed; timing/distance is recomputed. Send (same format as Add Route) to replace all stops.

URL

Method

Parameters

Description
api_key
route_uid A route owned by this key
route_name New name
route_datetime New planned start, YYYY-MM-DD HH:MM[:SS]
round_trip 0 or 1
stops JSON array (>=2) that REPLACES all stops (same format as Add Route)
webhooks true/false — turn this route's webhook emission on or off

At least one of route_name / route_datetime / round_trip / stops / webhooks must be supplied.

Example Request

curl -X POST "https://www.digitweb.co.za/api/updateRoute?api_key=API_KEY" \
  --data-urlencode "route_uid=87421" \
  --data-urlencode "route_name=Monday CT Deliveries (rev 2)" \
  --data-urlencode "round_trip=1"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "route_uid":87421,
  "route_name":"Monday CT Deliveries (rev 2)",
  "route_datetime":"2026-07-28 08:00:00",
  "end_datetime":"2026-07-28 09:41:07",
  "total_distance_km":58.9,
  "drive_time_secs":4210,
  "round_trip":1,
  "stop_count":3,
  "stops":[ ... ]
}

Error Messages

MessageDescription
route_uid is required route_uid missing or not positive
route not found or not linked to this api key The route does not belong to this user
nothing to update (send route_name, route_datetime, round_trip and/or stops) No updatable field supplied
route_name cannot be blank route_name sent but empty
route_datetime format must be YYYY-MM-DD HH:MM[:SS] Bad date format
a route needs at least 2 stops stops sent with fewer than 2 entries


Delete Route

Description

Delete a route owned by this key, along with its planning data: stops, vehicle assignment, execution records and any monitor flag. (The GPS execution trail on the data server is not touched.)

URL

Method

Parameters

Description
api_key
route_uid A route owned by this key

Example Request

curl -X POST "https://www.digitweb.co.za/api/deleteRoute?api_key=API_KEY" \
  --data-urlencode "route_uid=87421"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "route_uid":87421,
  "deleted":true
}

Error Messages

MessageDescription
route_uid is required route_uid missing or not positive
route not found or not linked to this api key The route does not belong to this user (or was already deleted)


Cancel Route

Description

Cancel a route owned by this key. Sets the route to the cancelled state (exec_completed = -2), which removes it from the route-monitor engine's active set. Only affects routes that are still active; a route that has already completed, been superseded, cancelled or abandoned is left unchanged and reported back.

Route states (exec_completed): active, completed, superseded (vehicle moved to a newer route), cancelled, abandoned.

URL

Method

Parameters

Description
api_key
route_uid A route owned by this key

Example Request

curl -X POST "https://www.digitweb.co.za/api/cancelRoute?api_key=API_KEY" \
  --data-urlencode "route_uid=87421"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "route_uid":87421,
  "cancelled":true,
  "previous_state":0
}

cancelled is true only when the route was active and is now cancelled. If it was already finished/superseded/cancelled, cancelled is false and previous_state shows what it was.

Error Messages

MessageDescription
route_uid is required route_uid missing or not positive
route not found or not linked to this api key The route does not belong to this user


Set Webhook

Description

Store (or update) the account-level webhook configuration (delivery endpoint + shared secret) for this api key's organization — it is scoped by the user behind the api_key, so no route/user id is passed. The route monitor engine uses it to deliver and sign events for any route flagged (see Add Route): each delivery is a POST with header = HMAC-SHA256 of the raw body using the secret. This endpoint only persists config; it sends nothing.

URL

Method

Parameters

Description
api_key — determines which organization's config is set
webhook_secret Per-organization shared secret used to sign deliveries (HMAC-SHA256)
webhook_url Delivery endpoint (default https://routeplan.digitweb.co.za/v1/webhooks/tracking)
webhook_enabled 1 (default) or 0 to store but disable

Example Request

curl -X POST "https://www.digitweb.co.za/api/setWebhook?api_key=API_KEY" \
  --data-urlencode "webhook_secret=YOUR_SHARED_SECRET"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "user_uid":14,
  "endpoint_url":"https://routeplan.digitweb.co.za/v1/webhooks/tracking",
  "enabled":true
}

The secret is stored for the engine but is never returned in API responses.

Error Messages

MessageDescription
webhook_secret is required No secret supplied


Webhook Events

Description

Once an organization has a webhook configured (see Set Webhook), the route monitor engine POSTs an event to the endpoint for every route created with (see Add Route). Eight event types are sent over a route's life:

EventSent when
The route is picked up for monitoring (from 00:00 on the day of the route), and again whenever its stops are changed. Carries the planned road path and a stop-by-stop schedule.
The vehicle leaves the first stop.
The vehicle enters a stop's radius.
The vehicle leaves any stop after the first.
The vehicle has been off the planned road continuously for 60 seconds.
The vehicle is back on the planned road after a route.deviated.
Live position ping while the route is running, at most once per minute per route.
All stops are done.

Delivery

Fields present on every event

Description
eventId Unique id of the event (UUID format)
type Event type, e.g. stop.arrived
routeUid The route's id, as returned by Add Route
occurredAt When the engine recorded the event

Stop fields

Events about a specific stop carry userLocationUid (the stop's location id from Add User Location) and stopOrder (its 1-based position on the route). Either is left out when it does not apply.

The stops schedule

route.path, route.departed, stop.arrived, stop.departed, route.deviated, route.returned and route.completed include a stops array: one entry per stop in driving order, with an up-to-date ETA for each. On a round trip the final entry is the return to the starting location.

Description
stopOrder 1-based position on the route
userLocationUid The stop's location id, or null if the stop was not created from a user location
eta For stops already reached: the actual arrival time. For the rest: the estimated arrival time. Before the route starts, the first stop's value is the planned departure time. null when it cannot be estimated.
legDurationSecs Planned driving time of the leg that ends at this stop (null on the first stop)
legDistanceKm Planned road distance of the leg that ends at this stop (null on the first stop)
arrived true once the vehicle has reached (or left) this stop

Before departure, ETAs are planned from the route's start time, each leg's driving time and the time spent at each stop. Once the route is under way they are recalculated from the vehicle's progress, including any remaining planned time at the stop it is currently parked at.

route.path

The planned road path as a list of points, the route totals, and the stop schedule. The eventId is derived from the path itself, so you receive it once per distinct path; a new one arrives only if the route's stops change.

{
  "eventId": "d4ffb9f7-bc4e-f28b-1e25-e48f03ad888d",
  "type": "route.path",
  "routeUid": 93777,
  "occurredAt": "2026-09-21T06:12:04+02:00",
  "distanceKm": 23.82,
  "durationSecs": 2447,
  "path": [
    {"lat": -33.84096, "lng": 18.65536},
    {"lat": -33.84121, "lng": 18.65602},
    ...
    {"lat": -33.84096, "lng": 18.65536}
  ],
  "stops": [
    {"stopOrder": 1, "userLocationUid": 107234, "eta": "2026-09-21T08:00:00+02:00", "legDurationSecs": null, "legDistanceKm": null,  "arrived": false},
    {"stopOrder": 2, "userLocationUid": 114763, "eta": "2026-09-21T08:17:11+02:00", "legDurationSecs": 1031, "legDistanceKm": 10.46, "arrived": false},
    {"stopOrder": 3, "userLocationUid": 114764, "eta": "2026-09-21T08:44:44+02:00", "legDurationSecs": 753,  "legDistanceKm": 6.48,  "arrived": false},
    {"stopOrder": 4, "userLocationUid": 107234, "eta": "2026-09-21T09:05:47+02:00", "legDurationSecs": 663,  "legDistanceKm": 6.88,  "arrived": false}
  ]
}

distanceKm and durationSecs are the whole route's planned totals.

route.departed

The vehicle has left the first stop. stopOrder is always 1.

{
  "eventId": "5b0e2f71-93c4-7d1a-a0f6-2c8e41d9b7e3",
  "type": "route.departed",
  "routeUid": 93777,
  "userLocationUid": 107234,
  "stopOrder": 1,
  "occurredAt": "2026-09-21T08:03:40+02:00",
  "stops": [
    {"stopOrder": 1, "userLocationUid": 107234, "eta": "2026-09-21T07:48:15+02:00", "legDurationSecs": null, "legDistanceKm": null,  "arrived": true},
    {"stopOrder": 2, "userLocationUid": 114763, "eta": "2026-09-21T08:20:51+02:00", "legDurationSecs": 1031, "legDistanceKm": 10.46, "arrived": false},
    {"stopOrder": 3, "userLocationUid": 114764, "eta": "2026-09-21T08:48:24+02:00", "legDurationSecs": 753,  "legDistanceKm": 6.48,  "arrived": false},
    {"stopOrder": 4, "userLocationUid": 107234, "eta": "2026-09-21T09:09:27+02:00", "legDurationSecs": 663,  "legDistanceKm": 6.88,  "arrived": false}
  ]
}

stop.arrived

The vehicle has entered the stop's radius. That stop now shows arrived: true with its actual arrival time, and the following ETAs include the planned time at this stop.

{
  "eventId": "8c41d6a2-0f7e-35b9-b2d4-7e19a3c05f68",
  "type": "stop.arrived",
  "routeUid": 93777,
  "userLocationUid": 114763,
  "stopOrder": 2,
  "occurredAt": "2026-09-21T08:22:05+02:00",
  "stops": [
    {"stopOrder": 1, "userLocationUid": 107234, "eta": "2026-09-21T07:48:15+02:00", "legDurationSecs": null, "legDistanceKm": null,  "arrived": true},
    {"stopOrder": 2, "userLocationUid": 114763, "eta": "2026-09-21T08:22:05+02:00", "legDurationSecs": 1031, "legDistanceKm": 10.46, "arrived": true},
    {"stopOrder": 3, "userLocationUid": 114764, "eta": "2026-09-21T08:49:38+02:00", "legDurationSecs": 753,  "legDistanceKm": 6.48,  "arrived": false},
    {"stopOrder": 4, "userLocationUid": 107234, "eta": "2026-09-21T09:10:41+02:00", "legDurationSecs": 663,  "legDistanceKm": 6.88,  "arrived": false}
  ]
}

stop.departed

The vehicle has left a stop other than the first. Same shape as stop.arrived.

{
  "eventId": "e27a9b50-4c13-6f8d-91a5-d03b6e84c21f",
  "type": "stop.departed",
  "routeUid": 93777,
  "userLocationUid": 114763,
  "stopOrder": 2,
  "occurredAt": "2026-09-21T08:39:12+02:00",
  "stops": [
    {"stopOrder": 1, "userLocationUid": 107234, "eta": "2026-09-21T07:48:15+02:00", "legDurationSecs": null, "legDistanceKm": null,  "arrived": true},
    {"stopOrder": 2, "userLocationUid": 114763, "eta": "2026-09-21T08:22:05+02:00", "legDurationSecs": 1031, "legDistanceKm": 10.46, "arrived": true},
    {"stopOrder": 3, "userLocationUid": 114764, "eta": "2026-09-21T08:51:45+02:00", "legDurationSecs": 753,  "legDistanceKm": 6.48,  "arrived": false},
    {"stopOrder": 4, "userLocationUid": 107234, "eta": "2026-09-21T09:12:48+02:00", "legDurationSecs": 663,  "legDistanceKm": 6.88,  "arrived": false}
  ]
}

route.deviated

The vehicle has been off the planned road for 60 seconds without a break. userLocationUid / stopOrder identify the stop it was driving towards. Brief wobbles shorter than 60 seconds are not reported.

Description
lat, lng Vehicle position when the event was sent
offPathKm Current distance from the planned road
deviatedAt When the vehicle first left the planned road
 
{
  "eventId": "3f9d0c84-b6a1-2e57-c8f3-19a04d7e6b25",
  "type": "route.deviated",
  "routeUid": 93777,
  "userLocationUid": 114764,
  "stopOrder": 3,
  "occurredAt": "2026-09-21T08:44:31+02:00",
  "lat": -33.848213,
  "lng": 18.690477,
  "offPathKm": 0.53,
  "deviatedAt": "2026-09-21T08:43:29+02:00",
  "stops": [ ... ]
}

route.returned

The vehicle is back on the planned road. Only sent after a matching route.deviated; both events share the same deviatedAt.

Description
lat, lng Vehicle position on rejoining the road
offPathKm The furthest the vehicle got from the planned road during the deviation
deviatedAt When the deviation began
durationSecs How long the vehicle was off the planned road
 
{
  "eventId": "a61e7f23-5d08-4b9c-e3a7-60c2f18d94b0",
  "type": "route.returned",
  "routeUid": 93777,
  "userLocationUid": 114764,
  "stopOrder": 3,
  "occurredAt": "2026-09-21T08:47:02+02:00",
  "lat": -33.851066,
  "lng": 18.697310,
  "offPathKm": 0.84,
  "deviatedAt": "2026-09-21T08:43:29+02:00",
  "durationSecs": 213,
  "stops": [ ... ]
}

vehicle.position

Periodic live position while the route is running, at most once per minute per route. It has a fresh random eventId each time and does not include the stops array.

Description
lat, lng Vehicle position
speedKmh Speed in km/h (whole number)
deviation true while the vehicle is off the planned road
etaNextStop Estimated arrival at the next stop
etaComplete Estimated arrival at the final stop
 
{
  "eventId": "0d7c5e91-2a46-4f3b-9e18-b54a7c6d2e03",
  "type": "vehicle.position",
  "routeUid": 93777,
  "occurredAt": "2026-09-21T08:30:14+02:00",
  "lat": -33.843587,
  "lng": 18.671942,
  "speedKmh": 54,
  "deviation": false,
  "etaNextStop": "2026-09-21T08:49:02+02:00",
  "etaComplete": "2026-09-21T09:10:05+02:00"
}

etaNextStop and etaComplete are left out if the route's schedule has not been loaded yet.

route.completed

All stops are done. The stops array shows the actual arrival time at every stop.

{
  "eventId": "71b3a8e4-c902-5d6f-a4e0-8f25d17c39ab",
  "type": "route.completed",
  "routeUid": 93777,
  "occurredAt": "2026-09-21T09:11:37+02:00",
  "stops": [
    {"stopOrder": 1, "userLocationUid": 107234, "eta": "2026-09-21T07:48:15+02:00", "legDurationSecs": null, "legDistanceKm": null,  "arrived": true},
    {"stopOrder": 2, "userLocationUid": 114763, "eta": "2026-09-21T08:22:05+02:00", "legDurationSecs": 1031, "legDistanceKm": 10.46, "arrived": true},
    {"stopOrder": 3, "userLocationUid": 114764, "eta": "2026-09-21T08:52:10+02:00", "legDurationSecs": 753,  "legDistanceKm": 6.48,  "arrived": true},
    {"stopOrder": 4, "userLocationUid": 107234, "eta": "2026-09-21T09:11:37+02:00", "legDurationSecs": 663,  "legDistanceKm": 6.88,  "arrived": true}
  ]
}

Verifying the signature

PHP:

$body     = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, 'YOUR_SHARED_SECRET');
if (!hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
http_response_code(200);

Node.js (Express):

const crypto = require('crypto');
app.post('/webhooks/tracking', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', 'YOUR_SHARED_SECRET').update(req.body).digest('hex');
  const given = Buffer.from(req.get('X-Signature') || '');
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});


Maersk — Assign Job Card & Container

Description

Maersk integration: assign a job card number and/or a container number to a vehicle. Each value is upserted onto the vehicle, and a log entry is written whenever it is new or changed. Supply the vehicle by or by .

URL

Method

Parameters

Description
api_key
vehicle_uid The vehicle to assign to (required unless imei is given)
imei Alternative to vehicle_uid; resolved to the caller's vehicle
jobcard_number Job card number to set (max 50 chars). Supply this and/or container_number
container_number Container number to set (max 50 chars). Supply this and/or jobcard_number

Example Request

curl -X POST "https://www.digitweb.co.za/api/maerskAssign?api_key=API_KEY" \
  --data-urlencode "vehicle_uid=1234" \
  --data-urlencode "jobcard_number=JC-2026-0098" \
  --data-urlencode "container_number=MSKU1234567"

Success Response

{
  "version":"1",
  "result":"success",
  "error_msg":"",
  "vehicle_uid":1234,
  "jobcard_number":"JC-2026-0098",
  "container_number":"MSKU1234567",
  "jobcard_changed":true,
  "container_changed":true
}

Error Messages

MessageDescription
vehicle_uid or imei is required No vehicle supplied
vehicle not found or not linked to this api key vehicle_uid not owned by this user
vehicle (imei) not found or not linked to this api key imei not owned by this user
supply jobcard_number and/or container_number Neither field was provided