IFTA Jurisdiction Mileage and Fuel API

1. Overview

The IFTA Jurisdiction Mileage and Fuel API returns per-truck, per-jurisdiction, per-day mileage and fuel records for IFTA filing and settlement, plus weekly and quarterly rollups, the vehicle master, fuel purchase import, special tax summaries, exceptions, audit evidence and bulk exports. It is built for fleet operators, ELD and TMS integrators, and settlement system developers.

2. Authentication and conventions

Every request carries the API key in the header. Keys are issued per fleet account from your MapUp account; write to ifta@mapup.ai to have one issued or rotated. This is the same x-api-key convention used across all MapUp APIs.

x-api-key: YOUR_API_KEY

Rate limiting

Every response includes headers so your integration can track usage and back off cleanly. When the limit is exceeded the API returns HTTP 429; implement exponential backoff using Retry-After.

Units and time zones

distance_unit (mi default, or km) controls every distance and odometer value in a response, and the response echoes it on the vehicle object. time_zone (IANA name, UTC default) controls timestamp formatting; each jurisdiction segment also carries its own local time zone.

3. Endpoints

4. Query parameters

Example requests

# Single truck, single day
GET https://api.mapup.ai/ifta/v1/daily?truck_id=fleet1-truck42&date=2026-05-12
x-api-key: YOUR_API_KEY

# Full fleet, one week, Eastern time, kilometers
GET https://api.mapup.ai/ifta/v1/fleet/weekly?week_start=2026-05-11&time_zone=America/New_York&distance_unit=km
x-api-key: YOUR_API_KEY

# Include Oregon weight-mile records (excluded from IFTA totals by default)
GET https://api.mapup.ai/ifta/v1/daily?truck_id=fleet1-truck42&date=2026-05-12&include_excluded=true
x-api-key: YOUR_API_KEY

5. Response envelope

Every daily, weekly and quarterly response carries the same three blocks before the records: status, vehicle and meta. Check status first.

Vehicle object

The canonical vehicle identity and every external system mapping needed for cross-system reconciliation.

vehicle.external_ids object

Maps the vehicle to its identifiers in the systems connected to the account. Null means that provider is not connected for this vehicle. When a fleet runs several ELD providers, this block lets a settlement system match MapUp output to its own records without a separate lookup table.

Meta block

6. Mileage records

mileage_records is an array with one object per jurisdiction per day.

daily_summary object

7. Fuel transactions

fuel_transactions is an array with one object per purchase event. Fuel is separate from mileage: it is bought at a point and consumed across jurisdictions, so IFTA apportionment happens at rollup time using fleet MPG, not per transaction.

8. Sample response

One truck operating in New York and Pennsylvania on one day, with one fuel purchase in New Jersey that morning. Values are illustrative.

{
  "status": "ok",
  "vehicle": {
    "mapup_truck_id": "fleet1-truck42",
    "unit_number": "4421",
    "vin": "1XXXXXXXXXXXXXXXX",
    "year": "2022", "make": "Freightliner", "model": "Cascadia",
    "base_jurisdiction": "MI",
    "registered_weight_lbs": 80000,
    "ifta_qualified": true,
    "distance_unit": "mi",
    "external_ids": {
      "motive_vehicle_id": null,
      "geotab_device_id": "G9-SN-44210",
      "transflow_unit_id": null,
      "tms_tractor_id": "4421",
      "efs_card_id": "EFS-001",
      "comdata_card_id": null,
      "wex_card_id": null
    }
  },
  "meta": {
    "date": "2026-05-12",
    "generated_at": "2026-05-15T04:32:11Z",
    "data_lag_days": 3, "data_complete": true,
    "time_zone": "UTC", "warnings": []
  },
  "mileage_records": [
    {
      "jurisdiction": "NY",
      "miles_total": 187.4, "miles_taxable": 187.4,
      "miles_toll_road": 52.5, "toll_road_flag": true,
      "toll_road_name": "NY-THRUWAY", "toll_road_source": "TOLLMATCH",
      "ifta_excluded": false,
      "odometer_start": 184220.1, "odometer_end": 184407.5,
      "odometer_source": "ECM", "odometer_unit": "mi",
      "gps_reconstructed_miles": 186.9,
      "reconciliation_delta_pct": 0.27, "reconciliation_flag": "OK",
      "eld_provider": "Geotab", "ping_count": 218,
      "start_lat": 42.998, "start_lon": -78.188,
      "end_lat": 41.084, "end_lon": -75.224,
      "entry_time": "2026-05-12T08:14:33Z",
      "exit_time": "2026-05-12T11:52:07Z",
      "time_zone": "America/New_York",
      "crossing_inferred": false,
      "special_tax": {
        "program": "NY-HUT", "applicable": true,
        "program_miles": 134.9,
        "ny_thruway_miles": 52.5,
        "ny_non_thruway_miles": 134.9,
        "hut_taxable_miles": 134.9, "hut_exempt_miles": 52.5
      }
    },
    {
      "jurisdiction": "PA",
      "miles_total": 96.2, "miles_taxable": 96.2,
      "miles_toll_road": 0, "toll_road_flag": false,
      "toll_road_name": null, "toll_road_source": "DERIVED",
      "ifta_excluded": false,
      "odometer_start": 184407.5, "odometer_end": 184503.9,
      "odometer_source": "ECM", "odometer_unit": "mi",
      "gps_reconstructed_miles": 96.4,
      "reconciliation_delta_pct": 0.21, "reconciliation_flag": "OK",
      "eld_provider": "Geotab", "ping_count": 121,
      "start_lat": 41.084, "start_lon": -75.224,
      "end_lat": 40.271, "end_lon": -76.882,
      "entry_time": "2026-05-12T11:52:07Z",
      "exit_time": "2026-05-12T14:05:40Z",
      "time_zone": "America/New_York",
      "crossing_inferred": false,
      "special_tax": null
    }
  ],
  "daily_summary": {
    "total_miles": 283.6, "total_taxable_miles": 283.6,
    "total_ifta_excluded_miles": 0,
    "total_fuel_gallons_purchased": 87.3,
    "jurisdictions_operated": ["NY", "PA"], "jurisdiction_count": 2,
    "has_special_taxes": true, "special_taxes_present": ["NY-HUT"]
  },
  "fuel_transactions": [
    {
      "transaction_id": "mp-fuel-00441892",
      "source_transaction_id": "EFS-20260512-00441892",
      "source": "EFS_INTEGRATION",
      "timestamp": "2026-05-12T07:48:00Z",
      "purchase_jurisdiction": "NJ",
      "fuel_type": "DIESEL", "fuel_amount": 87.3, "fuel_unit": "gal",
      "price_per_unit": 3.729, "total_cost": 325.64, "currency": "USD",
      "vendor": "Travel center",
      "ref_no": "TXN-987654",
      "location_name": "Travel center, Newark NJ",
      "location_lat": 40.713, "location_lon": -74.006,
      "odometer_at_fill": 184210, "odometer_unit": "mi",
      "tax_paid_flag": true, "tax_paid_gallons": 87.3,
      "driver_id": "D-1001", "driver_name": null
    }
  ]
}

9. Special tax handling

Five states impose mileage-based taxes alongside IFTA. IFTA detects when a truck operates in one, checks the program's weight gate against the vehicle, and populates the special_tax block on the record. There is nothing to request. Use include_excluded=true to retrieve Oregon records.

special_tax object

Per-program summary

Non-IFTA jurisdictions

Records from these jurisdictions carry ifta_excluded: true and special_tax.program: "NON-IFTA", and are omitted from all IFTA totals.

10. Rollup endpoints

Weekly rollup: GET /weekly and GET /fleet/weekly

Aggregates daily records by truck, jurisdiction and week (Monday to Sunday). Designed for owner-operator fuel settlement. Fleet MPG is applied at the weekly level.

Quarterly rollup: GET /quarterly

Aggregates to the IFTA filing period. Fleet MPG is applied at the quarter level. Feeds return preparation directly: taxable miles divided by fleet MPG gives consumed gallons; consumed less tax-paid gallons gives the net position per jurisdiction, to which the jurisdiction rate applies.

11. Vehicles

Returns every vehicle on the account with IFTA qualification, registered weight, base jurisdiction and external ID mappings across all connected ELD, fuel card and TMS providers. Filter with ifta_qualified, eld_provider and base_jurisdiction. Pages with next_cursor.

Look up one vehicle by mapup_truck_id, VIN, or any external ID. Returns the vehicle object from section 5.

GET https://api.mapup.ai/ifta/v1/vehicles?eld_provider=Geotab&ifta_qualified=true
GET https://api.mapup.ai/ifta/v1/vehicles/G9-SN-44210

12. Fuel purchases

Standalone fuel purchase endpoint. Returns normalized transactions across connected card networks (EFS, Comdata, WEX), on-premise stations and manual entries. Filter with truck_id, start_date, end_date, jurisdiction, source and fuel_type. Same schema as the fuel_transactions array in section 7, queryable without a date or truck.

Imports purchases MapUp does not receive through a direct integration: on-premise fuel that is pushed rather than pulled, other vendors, receipts. Accepts one transaction or a batch array. Supported source values: EFS_INTEGRATION, COMDATA_INTEGRATION, WEX_INTEGRATION, ON_PREM, MANUAL, CSV_IMPORT. Returns each created transaction with its MapUp transaction_id. Duplicates against an existing source_transaction_id are rejected, not double-counted.

POST https://api.mapup.ai/ifta/v1/fuel-purchases
x-api-key: YOUR_API_KEY
Content-Type: application/json

[
  {
    "truck_id": "fleet1-truck42",
    "source": "ON_PREM",
    "source_transaction_id": "YARD-A-2026-05-11-0093",
    "timestamp": "2026-05-11T19:20:00-04:00",
    "purchase_jurisdiction": "MI",
    "fuel_type": "DIESEL", "fuel_amount": 120.0, "fuel_unit": "gal",
    "price_per_unit": 3.41, "total_cost": 409.20, "currency": "USD",
    "location_name": "Yard A",
    "odometer_at_fill": 184090, "odometer_unit": "mi",
    "tax_paid_flag": false, "tax_paid_gallons": 0
  }
]

{
  "status": "ok",
  "created": [
    { "transaction_id": "mp-fuel-00441901", "source_transaction_id": "YARD-A-2026-05-11-0093" }
  ],
  "rejected": []
}

13. Special tax summary

Consolidates NY HUT, OR WMT, KYU, NM WDT and CT HUF miles separately from the core IFTA response. Filter with truck_id, program, start_date, end_date and quarter. Each program returns its miles, the applicable weight gate and the filing frequency. This endpoint is the source for special tax filing preparation and is independent of the IFTA rollup.

{
  "status": "ok",
  "quarter": "2026-Q2",
  "programs": [
    {
      "program": "NY-HUT", "filing": "QUARTERLY",
      "trucks": [
        { "mapup_truck_id": "fleet1-truck42", "applicable": true, "program_miles": 1642.7,
          "ny_thruway_miles": 588.1, "ny_non_thruway_miles": 1642.7 }
      ]
    },
    {
      "program": "OR-WMT", "filing": "STATE_SCHEDULE",
      "trucks": [
        { "mapup_truck_id": "fleet1-truck17", "applicable": true, "program_miles": 903.4 }
      ]
    }
  ]
}

Special programs have different filing frequencies, weight gates and calculation methods. Keeping them in a dedicated module means a state changing a program, or adding one, does not change the core IFTA schema.

14. Exceptions

Surfaces the records IFTA found and held rather than absorbed: missing fuel for trucks with mileage, vehicle IDs unmatched across providers, odometer reconciliation deltas over the threshold, GPS coverage gaps, inferred crossings, missing weights for a special program. Designed for fleet operations teams and integration health monitoring. Filter with truck_id, start_date, end_date, jurisdiction, reason and status. Pages with next_cursor.

GET https://api.mapup.ai/ifta/v1/exceptions?start_date=2026-05-11&end_date=2026-05-17&status=HELD

{
  "status": "ok",
  "exceptions": [
    {
      "exception_id": "exc_01J8XA7Q",
      "mapup_truck_id": "fleet1-truck63", "external_id": null,
      "date": "2026-05-14", "jurisdiction": "OH",
      "reason": "ODOMETER_DELTA", "status": "HELD",
      "detail": "ECM odometer delta 241.0 mi against 188.7 GPS-reconstructed miles (27.7 percent). Segment withheld from rollup.",
      "reconciliation_delta_pct": 27.7,
      "detected_at": "2026-05-17T04:10:52Z", "resolved_at": null, "resolution": null
    }
  ],
  "next_cursor": null
}

15. Audit evidence

Returns the full evidence packet behind a jurisdiction figure: the raw GPS points used in route reconstruction, the crossing timestamps and coordinates, the odometer readings at each crossing, the toll road segment matches and the fuel receipt references. Designed for audit defense and regulatory inquiries. Requires truck_id, date and jurisdiction.

GET https://api.mapup.ai/ifta/v1/audit/evidence?truck_id=fleet1-truck42&date=2026-05-12&jurisdiction=NY

For a whole audit request (many trucks, a quarter), submit an export with report: "audit_evidence" and the truck list; see section 16.

16. Exports

Submit an export with a format (CSV, EXCEL, PDF, JSON), a report, a date range or quarter, and an optional scope (truck list, jurisdiction). Returns a job_id. For quarterly filing preparation and back-office bulk processing, where per-request calls are impractical at scale.

POST https://api.mapup.ai/ifta/v1/exports
x-api-key: YOUR_API_KEY
Content-Type: application/json

{ "format": "EXCEL", "report": "quarterly", "quarter": "2026-Q2" }

HTTP 202
{ "status": "ok", "job_id": "exp_01J8XB2M", "state": "QUEUED" }

{
  "status": "ok",
  "job_id": "exp_01J8XB2M",
  "state": "COMPLETE",
  "download_url": "https://api.mapup.ai/ifta/v1/exports/exp_01J8XB2M/download",
  "expires_at": "2026-07-09T04:00:00Z"
}

state is QUEUED, RUNNING, COMPLETE or FAILED. Download URLs expire; re-poll for a fresh one.

17. Errors and data freshness

Error payload

{
  "status": "error",
  "error": {
    "code": "TRUCK_NOT_FOUND",
    "message": "No vehicle matching truck_id 'fleet1-truck99' in fleet registry.",
    "error_id": "err_01J8X9..."
  }
}

error_id is present on 500 responses; include it when contacting support.

HTTP status codes

The three-day window

ELD devices buffer GPS and odometer data locally and transmit when connectivity returns. A three-day rolling window ensures late-arriving data is included before records finalize.

Reconciliation flag values

18. Relationship to TollGuru state mileage

The TollGuru Toll API returns estimated per-state mileage as part of pre-trip route calculations. The IFTA API returns different data: ECM odometer-reconciled, GPS-verified, finalized actual miles driven, structured for tax compliance. If you use both, expect small differences between TollGuru's estimated state miles and IFTA actuals. The IFTA API is the authoritative source for filing. TollGuru toll segment data feeds the IFTA API's Thruway and non-Thruway split for New York HUT.

19. Support

For integration questions, reconciliation setup or held record resolution, write to ifta@mapup.ai with your fleet account ID, truck_id, date range and any error_id values. Severities and response times are on the get started page.