Endpoints

BatchRecommended

POST /v1/iot/events:batch

Use for production traffic. Send 1–500 events per request; split larger batches into separate requests.

Single

POST /v1/iot/events

Use for testing or low-volume sources. Send one event per request.

Authentication

Include these headers in every request. AIZEN provides separate staging and production API keys. Keep keys private; missing or invalid keys return 401.

Content-Type: application/json
X-API-Key: your-api-key-here

Base URLs

Request Body

Batch

{
  "events": [
    { "id": "…", "event_type": "vehicle", "vehicle_type":"string", "payload": { … } },
    { "id": "…", "event_type": "battery", "vehicle_type":"string", "payload": { … } }
  ]
}

Single

{
  "id":"string",
  "event_type":"string",
  "vehicle_type":"string",
  "payload": {}
}

Event Fields

All four fields are required.

Request Examples

POST /v1/iot/events:batch
X-API-Key: your-api-key-here
Content-Type: application/json

{
  "events": [
    {
      "id": "MX69112200547506",
      "event_type": "vehicle",
      "vehicle_type":"E-Scooter Pro",
      "payload": {
        "dataTime": 1783987597177,
        "status": "STOP",
        "ignition_status": "OFF",
        "movement_status": "false",
        "speed": 30,
        "soc": 57,
        "soh": 99,
        "latitude": -6.426598,
        "longitude": 106.770133
      }
    },
    {
      "id": "ZZ00384100154922",
      "event_type": "battery",
      "vehicle_type":"E-Bike Model X",
      "payload": {
        "dataTime": 1783987575519,
        "status":"CHARGING",
        "voltage": 78100,
        "soc": "97",
        "soh": "98",
        "latitude": -6.426598,
        "longitude": 106.770133
      }
    }
  ]
}

{
  "id":"VIN-ABC123XYZ456",
  "event_type":"vehicle",
  "vehicle_type":"E-Scooter Pro",
  "payload": {
    "timestamp":"2025-01-15T10:30:45Z",
    "vin":"VIN-ABC123XYZ456",
    "motorcycle_id":"MC-2024-001",
    "battery_current":-12.5,
    "battery_id":"BAT-789456",
    "movement_status": "false",
    "battery_temperature":32.5,
    "battery_voltage":52.3,
    "ignition":true,
    "imei":"350612078626668",
    "latitude":-6.2088,
    "longitude":106.8456,
    "odometer":1523.4,
    "plate_number":"B 1234 ABC",
    "soc":85,
    "soh":99,
    "speed":45.5,
    "status":"moving"
  }
}

{
  "id":"BAT-789456",
  "event_type":"battery",
  "vehicle_type":"E-Bike Model X",
  "payload": {
	  "status":"CHARGING",
    "timestamp":"2025-01-15T16:57:23Z",
    "battery_id":"BAT-789456",
    "vin":"VIN-ABC123XYZ456",
    "capacity":23475,
    "cell_voltage_max":4173,
    "cell_voltage_min":3677,
    "charging_status":true,
    "current":8.5,
    "latitude":-6.2762416,
    "longitude":106.910805,
    "motorcycle_id":"MC-2024-001",
    "soc":47,
    "soh":100,
    "temperature":35,
    "voltage":73.6
  }
}

Responses

202 Accepted confirms receipt for asynchronous processing. Batch requests can be partially accepted; always check rejected.

Batch: Accepted

{
  "status": "accepted",
  "accepted": 500,
  "rejected": [],
  "event_ids": ["evt_…", "evt_…"],
  "timestamp": "2026-07-14T10:30:01.234Z"
}

Batch: Partially Accepted

{
  "status": "accepted",
  "accepted": 498,
  "rejected": [
    { "index": 12, "error": "missing timestamp in payload" },
    { "index": 88, "error": "could not resolve identifier" }
  ],
  "event_ids": ["evt_…"],
  "timestamp": "2026-07-14T10:30:01.234Z"
}

Single: Accepted

{
  "status":"accepted",
  "event_id":"evt_1a2b3c4d5e6f7g8h9i0j",
  "timestamp":"2025-01-15T10:30:01.234Z"
}

Errors

Service unavailable:

{"status":"error","error_code":"SERVICE_UNAVAILABLE","message":"Please retry","timestamp":"…"}

Data Requirements

Required Payload Data

• timestamp: telemetry time.
• At least one identifier: vin, battery_id, or motorcycle_id.

Recommended Vehicle Fields

Recommended Battery Fields

Recommended Frequency

• Moving vehicles: every 30–60 seconds.
• Idle or charging: about every 5 minutes.

Deduplication

Duplicate events can occur. Keep source IDs stable and agree on event deduplication with AIZEN.

Receiver Requirements

Provide an HTTPS endpoint that:

• Accepts POST requests with application/json payloads.
• Returns 2xx when the payload is received.

POST https://partner-domain.com/webhooks/aizen/fleet-daily-report
Content-Type: application/json

Authentication

Validate each request using the shared bearer token agreed with AIZEN. All deliveries use HTTPS.

Authorization: Bearer <shared-token>

Payload

All partners use the same payload schema. Timestamps are UTC.

{
  "event_type": "fleet.daily_report",
  "schema_version": "1.0",
  "report_date": "2026-03-25",
  "generated_at": "2026-03-26T00:05:00Z",
  "batch_id": "rpt_abc123",
  "batch_sequence": 1,
  "batch_total": 5,
  "vehicles": [
    {
      "vin": "...",
      "trip_summary": {
        "total_trips": 5,
        "total_distance_km": 42.3,
        "total_energy_consumed_kwh": 2.1,
        "odometer_end_km": 1234.5,
        "avg_speed_kph": 28.4
      },
      "battery": {
        "avg_level_pct": 65,
        "avg_health_pct": 92
      },
      "last_location": {
        "latitude": -6.123,
        "longitude": 106.456,
        "recorded_at": "2026-03-25T22:45:00Z"
      },
      "impact": {
        "estimated_co2e_reduced_kg": 6.77,
        "calculation_method": "v1"
      }
    }
  ]
}

Report Fields

All fields are required.

Vehicle Fields

All fields are required.

trip_summary

battery

last_location

impact

Impact Calculation

estimated_co2e_reduced_kg estimates the greenhouse gas emissions avoided by using an electric vehicle instead of a combustion-engine vehicle.

Formula (kg CO₂e)

GHG Avoided (kg CO₂e) =
(distance_km ÷ fuel_efficiency_km_per_liter)
× 44.3 (NCV of gasoline)
× 18.9 (emission factor)
× (44/12) (converts kg Carbon to kg CO₂)
÷ 1000

Delivery

Reports are delivered daily in one or more batches. Delivery is at least once; duplicates can occur.

Batch Handling

Batches may arrive out of order. Use batch_id to identify the report batch, batch_sequence to order its batches, and batch_total to verify completeness.

{
  "batch_id":"rpt_abc123",
  "batch_sequence":1,
  "batch_total":5
}

Idempotency

Process duplicate deliveries idempotently using:

batch_id + batch_sequence

Retries

After the final failed attempt, delivery is marked as failed. Use the Replay API to recover missed reports.

Replay API

Recover missed reports after webhook retries are exhausted.

GET /reports?date=YYYY-MM-DD

Example

GET /reports?date=2026-03-01
Authorization: Bearer <shared-token>

Returns the webhook payload structure for the requested date. Results may be paginated or batched.