Campaign

As mentioned in “Creating a Project,” a campaign initiates active data collection on our vehicles.
A project without any campaigns does not collect any data.
A campaign defines which metrics are recorded.
It also lets you configure how the collected data is processed for that specific campaign.

Create a Campaign

Frontend:

Click the "+"-Button.
Select an active project.
Provide a campaign name and description.
Select “Record Trip-File” to save each trip as a sample file.
Select “Notify on Trip-File” to receive a notification whenever a new sample file is created.
This option is only available if “Record Trip-File” is enabled.
Select “Accept incomplete data” to allow storing incomplete or corrupted trip records (e.g., caused by connection loss).
This option is only available if “Record Trip-File” is enabled.
In some cases, a trip may never be properly finished—for example, if a vehicle loses connectivity or is parked in an underground garage. After a certain timeout, the system will automatically end the trip. These trips are considered incomplete because some data (such as the trip end) is missing.
Disabled: Incomplete trips are discarded.
Enabled: Incomplete trips are saved as sample files and clearly marked as incomplete.
Provide a "Trip-File TTL".
This option is only available if “Record Trip-File” is enabled.
Time-to-Life (TTL) in seconds, minimum is 7200s (= 2h).
If not null, all samples will be deleted after this time.
Select “Activation while driving.” This setting determines what happens if a campaign reaches a vehicle that is already in the middle of a trip.
Enabled: The campaign starts immediately, and data recording begins while the vehicle is still driving.
Disabled: The campaign does not start right away. It waits and begins when the vehicle starts its next trip.
Choose "Stream Data" to directly receive the trip files as media stream.
Provide a "Start -& End Date" to define the time period in which the records should be active.
start_date: The campaign will only be executed after this datetime.
end_date: Specifies a datetime on which the campaign will be disabled automatically. Can be null.
Select the metrics that should be collected.
Each metric can contain an optional maximum sample rate in ms.
By default, the maximum sample rate is set to null.
If you enter 1000 ms as maximum sample rate, we will record the metric value every second.
We won't store duplicates within the recorded data. If you include the outside temperature with a maximum sample rate of 1000 ms and the temperature remains static for one minute, we won’t repeat the same value 60 times. The static value will be stored only once.
Each metric also has a mandatory "required" property. It is possible that certain cars don't have the sensors to resolve a given metric. If the metric is marked as "required", the campaign won't execute on that car. If the property is set to "false", the campaign will execute, but the recorded data won’t include values for that metric.

API:

POST /campaigns/{organization_id}/{project_id}

request body: 
{
  "profile": {
    "description": "string",
    "name": "string"
  },
  "activation_trigger": [
    {
      "geo_triggers": [
        {
          "latitude": -90,
          "longitude": -180,
          "radius_meters": 1
        }
      ],
      "metric_triggers": [
        {
          "compare_operator": "equals",
          "compare_value": "string",
          "metric_id": "string"
        }
      ],
      "time_triggers": [
        {
          "end_time": "2026-04-10T08:00:09.512Z",
          "start_time": "2026-04-10T08:00:09.512Z"
        }
      ]
    }
  ],
  "included_metrics": [
    {
      "max_sample_rate": 1000,
      "metric_id": "string",
      "must_be_present": true
    }
  ],
  "processing_options": {
    "accept_incomplete_data": true,
    "activation_while_driving": true,
    "end_date": "2026-04-10T08:00:09.512Z",
    "notify_on_sample": true,
    "record_samples": true,
    "sample_ttl": 7200,
    "start_date": "2026-04-10T08:00:09.512Z",
    "stream_data": true
  }
}

Note:

activation_trigger: Not yet active. Once available, these triggers will allow you to control campaign execution more precisely. For example, you will be able to run campaigns only within a defined geographic area or when specific conditions are met (e.g., outside temperature below 10 °C).
must_be_present: The sensors available in our vehicles vary. This flag defines the minimum set of metrics that must be available in a vehicle for the campaign to run. All metrics for which this flag is set to true must be present.

Disable a Campaign

There is a limit of five active campaigns per project.
Once a campaign has been disabled it will not be executed anymore on the vehicle.
Persisted samples will not be deleted.

Frontend:
1. Click on the "action arrow" of a campaign.
2. Click the "Disable"-Botton at end of the page.

API:

PUT /campaigns/{organization_id}/{project_id}/{campaign_id}/:disable