Forwarders API

Once a forwarder is created by the DCT staff, developers can retrieve its configuration using a GET request to the appropriate API endpoint. The response will include several parameters that define how the forwarder behaves.

Below is an example response:

{
    "__created": 1634760253.175798,
    "__updated": 1738800080.328601,
    "__version": "7.5.4",
    "dates_format": "ISOFORMAT",
    "extra_headers": {},
    "forward_conn_events": false,
    "forward_gps_events": true,
    "forward_other_eventtypes_csv": null,
    "general": {
      "stop_send": true,
      "stop_queue": true,
      "discard": true
    },
    "groups_filter": [456],
    "id": 123,
    "INBOX_DB_DUMP_AT": 1010000,
    "include_evname": null,
    "include_vinfo": true,
    "MAX_MESS_PER_CALL": 50,
    "port": null,
    "protocol": "FWD:json_fwd",
    "resource": "https://yourwebsite.com/pegasus-forwarder/",
    "time_zone": "UTC",
    "vehicle_count": 1010
}

Forwarder Parameters

Note that parameters marked editable parameters can be modified using the PUT request.

Parameter	Editable	Description
`__created`	❌	Timestamp indicating when the forwarder was created.
`__updated`	❌	Timestamp of the last update to the forwarder configuration.
`__version`	❌	Version of the forwarder configuration.
`dates_format`	✅	Defines the format in which dates are sent (e.g., `ISOFORMAT`) Python datetime compatible. (Example: %Y-%m-%d %H:%M:%S will yield 2025-12-24 23:59:59
`extra_headers`	✅	Additional headers that will be included in the HTTP request to the destination endpoint.
`forward_conn_events`	✅	Whether connection events (online/offline status) should be forwarded.
`forward_gps_events`	✅	Whether GPS location events should be forwarded.
`forward_other_eventtypes_csv`	✅	Allows specifying additional event types to be forwarded using a CSV format.
`general`	✅	General configuration options such as stopping message sending, queue management, and discarding old events. More info below
`groups_filter`	✅	A list of group IDs to filter which vehicles’ data should be forwarded.
`id`	❌	Unique identifier for the forwarder.
`INBOX_DB_DUMP_AT`	❌	Internal parameter related to the maximum number of events that are stored before they are discarded.
`include_evname`	✅	Whether to include event names in the forwarded data.
`include_vinfo`	✅	Whether to include vehicle information (such as name and attributes) in the forwarded data.
`MAX_MESS_PER_CALL`	✅	Maximum number of messages that can be sent per request.
`port`	✅	The port used for forwarding messages (if applicable).
`protocol`	✅	Defines the forwarder type (e.g., `json_fwd`, `devicepkg`).
`resource`	✅	The destination URL where the forwarded messages will be sent.
`time_zone`	✅	Defines the time zone in which timestamps should be formatted.
`vehicle_count`	❌	The number of vehicles associated with the forwarder.

`general` params

Note that when sending the request, make sure to use the entire JSON object as the body of the PUT request, with the modifications.

`general` params	type	description
discard	boolean	discards old messages in queue & any new messages
filter_fields	object	available for `FWD:devicepkg` protocol, it allows you to filter specific device fields to forward. The list of available fields are found in the device payload section of Live Communications.
keys	array	use it to only forward certain keys (there are special keys `primary_name` and `primary` that allow you to forward the entity's name and entire description info respectively.)
keys_all	boolean	use it to forward all keys
keys_include	array	use it to include keys that are not defined in the base set (has priority over keys)
keys_exclude	array	use it to exclude any keys from the forwarder
stop_send	boolean	when true it stops the forwarder and queues events
stop_queue	boolean	when true it stops queuing events, discarding any new events
labels_in	array	only allows certain labels to forward data
labels_out	array	exclude the following labels from forwarding data
default_values	object	key and default value, ex: `{"ib": "000000000000"}`
include_primary	boolean	when true along with the field `primary` in `keys` or `keys_include` it includes a key called primary which contains the vehicle's information and custom properties

Example general configs

// defining certain keys or fields to send
...
{
    "general": {
        "keys": [
            "lat",
            "lon",
            "speed",
            "primary_name",
            "event_time"
        ]
    }
}
...

// results in
[
    {
        "lat": -34.88844,
        "lon": -56.11606,
        "speed": 33,
        "primary_name": "Blue Toyota",
        "event_time": "2026-12-17T14:22:09+00:00",
        "system_time": "2026-12-17T14:51:37.969868+00:00"
    }
]

// Adding an extra header for security purposes
...
{
    "extra_headers": {
        "Authorization": "Bearer YWRqZmFsZGpmbGFqc2RmbGFhZGxmam"
    }
}

// including primary info
...
{
    "include_primary": true,
    "keys_include": [
        "primary"
    ]
}

[
    {
        "vid": 2292,
        "lon": -80.19266,
        "primary": {
            "info": {
                "range_unit": "mile",
                "description": "Sample vehicle",
                "tank_volume": null,
                "color": "Black",
                "make": "Peterbilt",
                "vin": null,
                "license_plate": "ABC123",
                "alias": "foxtrot",
                "range": 400,
                "year": "2020",
                "model": "567",
                "tank_unit": "gallon"
            },
            "associations": [
                {
                    "device": 862831032123456,
                    "time": 1592847039,
                    "id": 86,
                    "association": true,
                    "vehicle": 2292
                }
            ],
            "__updated": 1596475523.951629,
            "associated_at": 1592847871,
            "name": "My special car",
            "primary": 9,
            "__created": 1592607412.826321,
            "images": {
                "photo": false,
                "on_icon": false,
                "idle_icon": false,
                "off_icon": false,
                "icon": false
            },
            "token": null,
            "properties": {
                "custom_properties": "yes",
                "network": "4G",
                "city": "FLORIDA",
                "sensor": "v1.2",
                "ID": "10073367",
                "region": "SOUTH",
                "my_info": {
                    "code": "11223344",
                    "state": "UPDATING"
                },
                "country": "US"
            },
            "groups": [
                6
            ],
            "__version": "5.3.2",
            "device": 862831032123456,
            "configuration": "0000",
            "type": "vehicle",
            "id": 2292
        },
        "label": "new",
        "lat": 26.68205,
        "device_id": 862831032123456
    }
]

Forwarder Parameters

general params

Example general configs

`general` params