API version 1.2.1

EV+MAP Fleet API

Plan routes with charging, send point lists and read plans from your own systems with an API key, and learn about changes from signed webhooks. The reference below is generated from the same tables the API checks requests with.

Download OpenAPI 3.1 (YAML) Server: https://evmap.pl/api/v1

Keys, limits and rules

Organization API of the EVMap fleet module: routes up to 30 stops planned with charging stops, point lists, places, vehicles and exports.

Authentication: Authorization: Bearer evf_<prefix>_<secret> (created in the panel, Integrations > Fleet API keys; shown once). Test keys create, read, cancel and plan again test routes only (isTest: planned normally, outside the monthly route limit, at most 25 per UTC day, never approved, shared or assigned) and read places and vehicles; live keys never see test routes.

Creating requests (POST that creates a resource) require Idempotency-Key (16-200 visible ASCII characters): a repeat with the same key and body returns the first answer with Idempotent-Replayed: true; the same key with another body is refused (422 idempotency_key_reused). Keys are kept 24 hours; 429 and 5xx answers are not stored, so retry them with the same key after Retry-After.

Limits: the organization's planning queue holds max(10, 2 x the plan's vehicle limit) pending and running jobs (429 fleet_queue_full, Retry-After); when the plan usage cannot be read, operations counted against the plan answer 503 fleet_usage_unavailable (Retry-After) instead of assuming zero.

Every answer uses the envelope {status, messages, data, meta}; errors carry meta.code and meta.details. Times are ISO 8601 in UTC; a departureAt without an offset is the organization's local time.

Webhooks (section webhooks): signed HTTPS POST with X-EVMap-Event, X-EVMap-Delivery, X-EVMap-Timestamp and X-EVMap-Signature: sha256=HMAC_SHA256(secret, timestamp + "." + body); events fleet.route.ready, fleet.route.needs_attention, fleet.route.failed, fleet.route.replanned, fleet.route.approved, fleet.import.ready, fleet.import.failed, fleet.report.ready, fleet.assignment.created, fleet.execution.updated, fleet.stop.updated, fleet.readiness.risk, fleet.readiness.resolved, fleet.alert.raised, fleet.alert.resolved. Payloads carry identifiers, statuses, totals and codes only.

Operations

Account

Key, plan and limits.

GET `/fleet/openapi`

This OpenAPI 3.1 document (YAML, no key needed)

Response: 200 application/yaml
Error answers: 404

GET `/fleet/capabilities`

Limits, features and scopes of the calling key

Response: 200 CapabilitiesResponse
Error answers: 404, 401, 403, 429, 503

Routes

Routes with up to 30 stops, planned asynchronously (webhooks fleet.route.*).

POST `/fleet/routes`

Create a route and queue it for planning. Scope: fleet.routes:write. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: RouteCreate application/json
Response: 202 RouteResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/routes`

List routes of a service date or status. Scope: fleet.routes:read. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Description
`date`	query	string (date)	Service date (organization time zone).
`status`	query	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`vehicle`	query	string (uuid)	Vehicle identifier.
`limit`	query	integer	Page size, default 50.

Response: 200 RouteListResponse
Error answers: 404, 401, 403, 429, 503, 422

POST `/fleet/routes/batch`

Create up to 50 routes at once (all or nothing). Scope: fleet.routes:write. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: RouteBatchCreate application/json
Response: 202 RouteListResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/routes/{routeId}`

Route with its points and the current plan. Scope: fleet.routes:read. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`routeId`	path	string (uuid)	yes	Route identifier.

Response: 200 RouteResponse
Error answers: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/cancel`

Cancel a route. Scope: fleet.routes:write. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`routeId`	path	string (uuid)	yes	Route identifier.

Response: 200 RouteResponse
Error answers: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/replan`

Plan a route again (new revision). Scope: fleet.routes:write. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`routeId`	path	string (uuid)	yes	Route identifier.

Response: 202 RouteResponse
Error answers: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/approve`

Approve a planned route. Scope: fleet.routes:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`routeId`	path	string (uuid)	yes	Route identifier.

Response: 200 RouteResponse
Error answers: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/customer-links`

Customer link of one stop: that stop, its arrival window and the route status only (URL returned once; the stop's older link stops working). Scope: fleet.routes:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`routeId`	path	string (uuid)	yes	Route identifier.

Request body: CustomerLinkCreate application/json
Response: 201 CustomerLinkResponse
Error answers: 404, 401, 403, 429, 503, 422

Point lists

Lists geocoded and checked asynchronously (webhooks fleet.import.*).

POST `/fleet/point-lists`

Send a point list as JSON rows (geocoded and checked asynchronously). Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: PointListCreate application/json
Response: 202 PointListResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

POST `/fleet/point-lists/imports`

Upload a CSV or XLSX point list. Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: PointListUpload multipart/form-data
Response: 202 PointListResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/point-lists/{listId}`

State and rows of a point list. Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`listId`	path	string (uuid)	yes	Point list identifier.

Response: 200 PointListResponse
Error answers: 404, 401, 403, 429, 503

Places

Depots, customers and warehouses.

GET `/fleet/places`

List places. Scope: fleet.places:read. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Description
`kind`	query	string: depot \| customer \| warehouse \| other
`externalRef`	query	string
`status`	query	string: active \| archived
`limit`	query	integer	Page size, default 100.

Response: 200 PlaceListResponse
Error answers: 404, 401, 403, 429, 503, 422

POST `/fleet/places`

Create a place. Scope: fleet.places:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: PlaceCreate application/json
Response: 201 PlaceResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

PATCH `/fleet/places/{placeId}`

Change a place (only the fields sent). Scope: fleet.places:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`placeId`	path	string (uuid)	yes	Place identifier.

Request body: PlacePatch application/json
Response: 200 PlaceResponse
Error answers: 404, 401, 403, 429, 503, 422

Vehicles

Fleet vehicles with battery data.

GET `/fleet/vehicles`

List vehicles. Scope: fleet.vehicles:read. Test keys: yes (test routes only).

Parameters
Name	Where	Type	Required	Description
`status`	query	string: active \| archived

Response: 200 VehicleListResponse
Error answers: 404, 401, 403, 429, 503, 422

POST `/fleet/vehicles`

Create a vehicle. Scope: fleet.vehicles:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: VehicleCreate application/json
Response: 201 VehicleResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

PATCH `/fleet/vehicles/{vehicleId}`

Change a vehicle (only the fields sent). Scope: fleet.vehicles:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`vehicleId`	path	string (uuid)	yes	Vehicle identifier.

Request body: VehiclePatch application/json
Response: 200 VehicleResponse
Error answers: 404, 401, 403, 429, 503, 422

Exports

Schedules, GPX and monthly reports (webhook fleet.report.ready).

POST `/fleet/exports`

Request a schedule, GPX or monthly report file (prepared asynchronously, kept 7 days). Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: ExportCreate application/json
Response: 202 ExportResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/exports/{exportId}`

State of an export. Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`exportId`	path	string (uuid)	yes	Export identifier.

Response: 200 ExportResponse
Error answers: 404, 401, 403, 429, 503

GET `/fleet/exports/{exportId}/file`

Download a ready export file. Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`exportId`	path	string (uuid)	yes	Export identifier.

Response: 200 application/octet-stream
Error answers: 404, 401, 403, 429, 503

Charging sessions

Charging sessions of card providers for the settlement: matched to vehicles, routes and planned stops; the results are in the panel (Card settlement).

POST `/fleet/charging-sessions/imports`

Send up to 1000 charging sessions of a card provider (stored at once, matched to vehicles, routes and planned stops asynchronously). Scope: fleet.sessions:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`Idempotency-Key`	header	string	yes	16-200 visible ASCII characters, unique per creating request.

Request body: ChargingSessionImportCreate application/json
Response: 202 ChargingSessionImportResponse
Error answers: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/charging-sessions/imports/{importId}`

State of a charging session import with its session and match counts. Scope: fleet.sessions:write. Test keys: no (403 test_key_not_allowed).

Parameters
Name	Where	Type	Required	Description
`importId`	path	string (uuid)	yes	Charging session import identifier.

Response: 200 ChargingSessionImportResponse
Error answers: 404, 401, 403, 429, 503

Webhooks

Events sent to your HTTPS endpoint (panel: Integrations > Webhooks, up to 5 per organization, chosen events, secret shown once).

Headers of every delivery
Name	Type	Description
`X-EVMap-Event`	string: fleet.route.ready \| fleet.route.needs_attention \| fleet.route.failed \| fleet.route.replanned \| fleet.route.approved \| fleet.import.ready \| fleet.import.failed \| fleet.report.ready \| fleet.assignment.created \| fleet.execution.updated \| fleet.stop.updated \| fleet.readiness.risk \| fleet.readiness.resolved \| fleet.alert.raised \| fleet.alert.resolved	Event type, the same as type in the body.
`X-EVMap-Delivery`	string (uuid)	Delivery to this endpoint (the same for its retries).
`X-EVMap-Timestamp`	string	UNIX seconds of the attempt; refuse values more than 5 minutes away from your clock.
`X-EVMap-Signature`	string	`sha256=` + hex HMAC-SHA256 of `timestamp + "." + raw body`, key = the endpoint secret (`whsec_…`, shown once in the panel). Compare in constant time.

Received: any 2xx answer within 5 s acknowledges the delivery (the body is ignored).

Any other answer, a redirect, a timeout or a connection error: retried after 1, 5 and 25 minutes and about 2 hours (5 attempts); 20 failed attempts in a row switch the endpoint off.

Signature check (PHP)

$body = file_get_contents('php://input');
$timestamp = (int)($_SERVER['HTTP_X_EVMAP_TIMESTAMP'] ?? 0);
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, getenv('EVMAP_WEBHOOK_SECRET'));
if (abs(time() - $timestamp) > 300 || !hash_equals($expected, (string)($_SERVER['HTTP_X_EVMAP_SIGNATURE'] ?? ''))) {
    http_response_code(401);
    exit;
}
http_response_code(204); // acknowledge within 5 s, then process the event (deduplicate by its id)

POST `fleet.route.ready`

The first revision of a route is planned without problems.

Event body: WebhookRouteEvent

POST `fleet.route.needs_attention`

The first revision of a route is planned with something to look at (e.g. a missed time window); the plan is complete.

Event body: WebhookRouteEvent

POST `fleet.route.failed`

Planning of a route failed (errorCode).

Event body: WebhookRouteEvent

POST `fleet.route.replanned`

A later revision of a route is planned (status planned or needs_attention).

Event body: WebhookRouteEvent

POST `fleet.route.approved`

A route was approved.

Event body: WebhookRouteEvent

POST `fleet.import.ready`

A point list is geocoded and checked (rows ready, to review and rejected).

Event body: WebhookPointListEvent

POST `fleet.import.failed`

A point list could not be processed (errorCode).

Event body: WebhookPointListEvent

POST `fleet.report.ready`

An export file is ready (kept 7 days). Files of the panel only (route card, delivery proofs) are announced without links and file name.

Event body: WebhookExportEvent

POST `fleet.assignment.created`

A driver was assigned to a route (previousDriverId when another driver was replaced).

Event body: WebhookAssignmentEvent

POST `fleet.execution.updated`

The driver changed the state of the route execution; replanRequired after a check-in that needs a new plan.

Event body: WebhookExecutionEvent

POST `fleet.stop.updated`

The driver reported a stop (arrived, completed, skipped or failed, with the reason).

Event body: WebhookExecutionEvent

POST `fleet.readiness.risk`

A vehicle will not be charged at its base in time for its first route tomorrow (once per new risk or a shortfall change of 1 kWh or more).

Event body: WebhookReadinessEvent

POST `fleet.readiness.resolved`

An announced readiness risk is gone after a recalculation: status ok, unknown or none (no route that day any more); once per announced risk.

Event body: WebhookReadinessEvent

POST `fleet.alert.raised`

A dispatcher alert was raised (one active alert per route and type, per stop for stations).

Event body: WebhookAlertEvent

POST `fleet.alert.resolved`

A dispatcher alert was closed (resolution).

Event body: WebhookAlertEvent

Schemas

RoutePointInput

RoutePointInput
Field	Type	Description
`label`	string
`placeId`	string (uuid)	Saved place; its coordinates, name and default stop time are used.
`latitude`	number
`longitude`	number
`dwellMinutes`	integer	Stop time at the customer (stops only).
`timeWindowFrom`	string	Soft time window, HH:MM local time of the stop on the day of departure: the time zone of the stop's country inside the cross-border coverage (for example Europe/Vilnius in Lithuania), the organization time zone elsewhere; the route's points report it as timezone. An earlier arrival waits for it, a later one is reported as window_missed. A stop at a place without its own window takes the place's default window.
`timeWindowTo`	string
`externalRef`	string
`notes`	string	Instructions for the driver (never sent in webhooks).
`locked`	boolean	Keeps the stop's position when optimizeOrder is on.

RouteCreate

RouteCreate
Field	Type	Required	Description
`name`	string		Shown in the panel, on the route card, in e-mails and exports: no personal data of customers (names, addresses, phone numbers). Default: "<vehicle> · <date> · stops: <count>".
`vehicleId`	string (uuid)	yes
`driverId`	string (uuid)
`departureAt`	string (date-time)	yes	ISO 8601 with an offset or Z; without an offset the organization time zone applies.
`departureSocPercent`	number		Battery at departure; default: the vehicle's expected morning level.
`costCenter`	string
`optimizeOrder`	boolean
`winterMode`	boolean
`maxVariants`	integer
`notes`	string
`points`	array of RoutePointInput	yes	Start, stops in the visiting order, end.

RouteBatchCreate

RouteBatchCreate
Field	Type	Required	Description
`routes`	array of RouteCreate	yes

PointListRow

PointListRow
Field	Type	Description
`kind`	string: start \| stop \| end
`label`	string
`address`	string
`houseNumber`	string
`postalCode`	string
`city`	string
`latitude`	number
`longitude`	number
`placeRef`	string	externalRef of a saved place.
`externalRef`	string
`dwellMinutes`	integer
`timeWindowFrom`	string
`timeWindowTo`	string
`notes`	string
`vehicle`	string	Registration number or name; splits the list into routes per vehicle.
`driver`	string
`date`	string (date)
`departureTime`	string
`departureSocPercent`	number	Battery at departure of the route of this vehicle and day (the first value given in its rows applies); default: the vehicle's expected morning level.

PointListCreate

PointListCreate
Field	Type	Required	Description
`sourceRef`	string		Your list identifier; a new list with the same value synchronizes rows by externalRef.
`serviceDate`	string (date)
`departureTime`	string
`vehicleId`	string (uuid)
`dwellMinutes`	integer
`returnToDepot`	boolean
`optimizeOrder`	boolean
`winterMode`	boolean
`costCenter`	string
`rows`	array of PointListRow	yes

PointListUpload

PointListUpload
Field	Type	Required	Description
`file`	string	yes	CSV (UTF-8, ; or , separated) or XLSX, at most 2 MB and 1000 rows.
`sourceRef`	string		Your list identifier; a new list with the same value synchronizes rows by externalRef.
`serviceDate`	string (date)
`departureTime`	string
`vehicleId`	string (uuid)
`dwellMinutes`	integer
`returnToDepot`	boolean
`optimizeOrder`	boolean
`winterMode`	boolean
`costCenter`	string

PlaceCreate

PlaceCreate
Field	Type	Required	Description
`name`	string	yes
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null		Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc		Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null		Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

PlacePatch

PlacePatch
Field	Type	Description
`name`	string
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null	Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc	Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null	Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

VehicleCreate

VehicleCreate
Field	Type	Required	Description
`name`	string	yes
`registrationNumber`	string		Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	yes	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer		0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

VehiclePatch

VehiclePatch
Field	Type	Description
`name`	string
`registrationNumber`	string	Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer	0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

ExportCreate

ExportCreate
Field	Type	Required	Description
`kind`	string: route_schedule \| day_schedule \| route_gpx \| monthly	yes
`format`	string: csv \| xlsx \| gpx	yes
`routeId`	string (uuid)		route_schedule and route_gpx.
`serviceDate`	string (date)		day_schedule.
`month`	string (month)		monthly (YYYY-MM).
`groupBy`	string: vehicle \| driver \| costCenter		monthly CSV grouping.
`locale`	string: pl \| en		Language, CSV separator and decimal mark of the file; default pl.

CustomerLinkCreate

CustomerLinkCreate
Field	Type	Required	Description
`stop`	integer	yes	Number of the stop on the route (sequence of a point of kind "stop"; the start is 0).

CustomerLink

CustomerLink
Field	Type	Description
`id`	string (uuid)
`url`	string	Public page of the stop (no key or PIN needed); shown once.
`stop`	integer
`expiresAt`	string (date-time)	24 h after the end of the service day.

Route

Route
Field	Type	Description
`id`	string (uuid)
`name`	string
`status`	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`revision`	integer
`isTest`	boolean	Created with a test key: outside plan limits and monthly reports.
`serviceDate`	string (date)
`departureAt`	string (date-time)
`timezone`	string
`vehicleId`	string (uuid) \| null
`driverId`	string (uuid) \| null
`costCenter`	string \| null
`options`	object
`options.optimizeOrder`	boolean
`options.winterMode`	boolean
`options.maxVariants`	integer
`errorCode`	string \| null
`plan`	object \| null	Present once the route is planned.
`plan.plannedAt`	string (date-time) \| null
`plan.distanceMeters`	integer
`plan.drivingSeconds`	integer
`plan.chargingSeconds`	integer
`plan.dwellSeconds`	integer
`plan.windowWaitSeconds`	integer	Waiting for time windows to open (part of totalSeconds).
`plan.lateStopCount`	integer	Stops reached after their time window (the route then needs attention).
`plan.windowLateSeconds`	integer
`plan.totalSeconds`	integer
`plan.arrivalAt`	string (date-time) \| null
`plan.arrivalSocPercent`	number \| null
`plan.gridEnergyWh`	integer
`plan.chargingStopCount`	integer
`plan.chargingCost`	array of object
`plan.chargingCost[].currency`	string
`plan.chargingCost[].amount`	string
`plan.dwellChargingStopCount`	integer	Stops where the vehicle charges during the visit (no extra time).
`plan.dwellChargingEnergyWh`	integer	Energy charged during visits (battery side); the grid side is in gridEnergyWh.
`plan.warningCodes`	array of string
`plan.chargingStops`	array of object
`plan.chargingStops[].stationId`	string \| null
`plan.chargingStops[].locationId`	string \| null
`plan.chargingStops[].stationName`	string \| null
`plan.chargingStops[].operatorName`	string \| null
`plan.chargingStops[].address`	string \| null
`plan.chargingStops[].city`	string \| null
`plan.chargingStops[].latitude`	number
`plan.chargingStops[].longitude`	number
`plan.chargingStops[].powerKw`	number
`plan.chargingStops[].arrivalAt`	string (date-time) \| null
`plan.chargingStops[].departureAt`	string (date-time) \| null
`plan.chargingStops[].unplugBy`	string (date-time) \| null
`plan.chargingStops[].arrivalSocPercent`	number
`plan.chargingStops[].departureSocPercent`	number
`plan.chargingStops[].gridEnergyWh`	integer
`plan.chargingStops[].authorization`	object \| null
`plan.chargingStops[].reliability`	string \| null
`plan.chargingStops[].warningCodes`	array of string
`points`	array of object
`points[].sequence`	integer	Position in the list that was sent.
`points[].plannedIndex`	integer	Position in the planned visiting order.
`points[].kind`	string: start \| stop \| end
`points[].label`	string
`points[].placeId`	string (uuid) \| null
`points[].latitude`	number
`points[].longitude`	number
`points[].timezone`	string	IANA time zone of the point's local times (its time window as HH:MM): the zone of its country inside the cross-border coverage, the route's timezone elsewhere and wherever both keep the same offsets.
`points[].dwellMinutes`	integer
`points[].externalRef`	string
`points[].notes`	string
`points[].locked`	boolean
`points[].timeWindowFrom`	string (date-time) \| null
`points[].timeWindowTo`	string (date-time) \| null
`points[].plannedArrivalAt`	string (date-time) \| null
`points[].plannedDepartureAt`	string (date-time) \| null
`points[].arrivalSocPercent`	number \| null
`points[].departureSocPercent`	number \| null
`points[].windowWaitSeconds`	integer	Planned wait for the time window to open.
`points[].windowLateSeconds`	integer	Planned arrival after the window closes; 0 = on time.
`points[].dwellCharging`	object \| null	Charging during the visit at a station nearby or at the place's own chargers; null = none.
`points[].dwellCharging.source`	string: station \| depot
`points[].dwellCharging.current`	string: ac \| dc
`points[].dwellCharging.locationId`	string \| null
`points[].dwellCharging.stationName`	string
`points[].dwellCharging.operatorName`	string \| null
`points[].dwellCharging.latitude`	number
`points[].dwellCharging.longitude`	number
`points[].dwellCharging.distanceMeters`	integer
`points[].dwellCharging.powerKw`	number
`points[].dwellCharging.startAt`	string (date-time) \| null
`points[].dwellCharging.endAt`	string (date-time) \| null
`points[].dwellCharging.energyWh`	integer
`points[].dwellCharging.gridEnergyWh`	integer
`points[].dwellCharging.departureSocPercent`	number
`points[].dwellCharging.cost`	object \| null	From the fleet card tariffs or the depot energy price; null = unpriced.
`points[].dwellCharging.cost.currency`	string
`points[].dwellCharging.cost.amount`	string
`scenario`	object \| null	Condition scenario (winter or summer) planned next to the route; null = none. Differences are scenario minus plan in the unit of the row.
`scenario.code`	string
`scenario.status`	string
`scenario.stale`	boolean	Computed for an earlier revision of the route.
`scenario.plannedAt`	string (date-time) \| null
`scenario.rows`	object \| null	energyExpectedWh, gridWh, chargingStopCount, chargingSeconds, totalSeconds, arrivalSocBp; null until the scenario is planned.
`scenario.headline`	object \| null
`scenario.headline.energyWhDelta`	integer
`scenario.headline.energyPercentDelta`	number \| null
`scenario.headline.totalSecondsDelta`	integer
`scenario.headline.chargingStopDelta`	integer
`scenario.headline.arrivalSocBpDelta`	integer
`createdAt`	string (date-time)
`plannedAt`	string (date-time) \| null
`approvedAt`	string (date-time) \| null
`links`	object
`links.self`	string

PointList

PointList
Field	Type	Description
`id`	string (uuid)
`status`	string
`sourceKind`	string
`sourceRef`	string \| null
`rows`	object
`rows.total`	integer
`rows.ready`	integer
`rows.review`	integer
`rows.rejected`	integer
`routeCount`	integer
`errorCode`	string \| null
`createdAt`	string (date-time)
`completedAt`	string (date-time) \| null
`items`	array of object	Rows (first 1000) with their check result.

Place

Place
Field	Type	Description
`id`	string (uuid)
`name`	string
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null	Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc	Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null	Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

Vehicle

Vehicle
Field	Type	Description
`id`	string (uuid)
`name`	string
`registrationNumber`	string	Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer	0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

Export

Export
Field	Type	Required	Description
`id`	string (uuid)
`kind`	string
`format`	string
`status`	string: pending \| processing \| ready \| failed \| expired
`errorCode`	string \| null
`fileName`	string \| null
`byteSize`	integer
`createdAt`	string (date-time)
`expiresAt`	string (date-time) \| null
`links`	object
`links.self`	string
`links.file`	string \| null

Capabilities

Capabilities
Field	Type	Required	Description
`organization`	object
`key`	object
`plan`	object
`limits`	object
`webhookEvents`	array of string

Error

Error
Field	Type	Description
`status`	string = error
`messages`	array of object
`messages[].type`	string
`messages[].text`	string
`meta`	object
`meta.code`	string	Stable error code, e.g. invalid_api_key, insufficient_scope, test_key_not_allowed, validation_failed, idempotency_key_reused, rate_limited, fleet_plan_limit, fleet_queue_full, fleet_usage_unavailable.
`meta.statusCode`	integer
`meta.errors`	array of object
`meta.errors[].field`	string
`meta.errors[].code`	string
`meta.errors[].message`	string

RouteResponse

RouteResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.route`	Route

RouteListResponse

RouteListResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.routes`	array of Route

PointListResponse

PointListResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.pointList`	PointList

PlaceResponse

PlaceResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.place`	Place

PlaceListResponse

PlaceListResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.places`	array of Place

VehicleResponse

VehicleResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.vehicle`	Vehicle

VehicleListResponse

VehicleListResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.vehicles`	array of Vehicle

ExportResponse

ExportResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.export`	Export

CustomerLinkResponse

CustomerLinkResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.customerLink`	CustomerLink

CapabilitiesResponse

CapabilitiesResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.capabilities`	Capabilities

ChargingSessionInput

ChargingSessionInput
Field	Type	Required	Description
`sessionId`	string	yes	Transaction number of the provider; a session sent again with the same number updates it (corrected invoice lines).
`cardNumber`	string		Charging card number; only its last four characters are stored (the card is found by them).
`vehicleRegistration`	string		Registration number when the provider knows it; it wins over the card.
`startedAt`	string (date-time)	yes	ISO 8601 with Z or an offset; without an offset the time zone of the request (or of the organization) applies.
`endedAt`	string (date-time)
`energyKwh`	number	yes
`costNet`	number		Net amount in the currency (major units, e.g. 68.70).
`costGross`	number		Gross amount; a missing one is derived from the VAT rate of the charging policy in the reports.
`currency`	string
`operatorName`	string
`stationName`	string
`address`	string
`city`	string
`evseId`	string
`latitude`	number		Station position for the match with the planned stops (never returned).
`longitude`	number

ChargingSessionImportCreate

ChargingSessionImportCreate
Field	Type	Required	Description
`programId`	string (uuid)		Card program of the sessions; narrows the card search.
`timezone`	string		IANA time zone of the times without an offset; default: the organization's.
`currency`	string		Currency of the sessions without one; default: the organization's.
`sessions`	array of ChargingSessionInput	yes

ChargingSessionImport

ChargingSessionImport
Field	Type	Description
`id`	string (uuid)
`source`	string: file \| api \| rematch	api, or file / rematch for the imports of the panel.
`status`	string: pending \| processing \| processed \| failed \| cancelled
`errorCode`	string \| null
`sessions`	object
`sessions.total`	integer
`sessions.imported`	integer
`sessions.updated`	integer
`sessions.unchanged`	integer
`sessions.rejected`	integer
`match`	object \| null	Present once the import is processed.
`match.matched`	integer
`match.unmatched`	integer
`match.suspicious`	integer
`rejected`	array of object	Sessions that were not stored: position in the request (from 0) and the reason, e.g. invalid_start, end_before_start, missing_energy, invalid_currency, duplicate_in_file.
`rejected[].index`	integer
`rejected[].code`	string
`createdAt`	string (date-time)
`processedAt`	string (date-time) \| null
`links`	object
`links.self`	string

ChargingSessionImportResponse

ChargingSessionImportResponse
Field	Type	Required	Description
`status`	string = ok
`data`	object
`data.import`	ChargingSessionImport

WebhookRouteEvent

WebhookRouteEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.route.ready \| fleet.route.needs_attention \| fleet.route.failed \| fleet.route.replanned \| fleet.route.approved	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.route`	WebhookRoute

WebhookPointListEvent

WebhookPointListEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.import.ready \| fleet.import.failed	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.pointList`	WebhookPointList

WebhookExportEvent

WebhookExportEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.report.ready	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.export`	WebhookExport

WebhookAssignmentEvent

WebhookAssignmentEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.assignment.created	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.assignment`	WebhookAssignment

WebhookExecutionEvent

WebhookExecutionEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.execution.updated \| fleet.stop.updated	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	WebhookExecution	yes

WebhookReadinessEvent

WebhookReadinessEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.readiness.risk \| fleet.readiness.resolved	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.readiness`	WebhookReadiness

WebhookAlertEvent

WebhookAlertEvent
Field	Type	Required	Description
`id`	string	yes	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.alert.raised \| fleet.alert.resolved	yes
`apiVersion`	string = v1	yes
`createdAt`	string (date-time)	yes
`test`	boolean	yes	A test route, or a test event sent from the panel.
`data`	object	yes
`data.alert`	WebhookAlert

WebhookRoute

WebhookRoute
Field	Type	Description
`id`	string (uuid)
`name`	string
`status`	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`revision`	integer
`isTest`	boolean
`serviceDate`	string (date)
`departureAt`	string (date-time) \| null
`vehicleId`	string (uuid) \| null
`costCenter`	string \| null
`pointCount`	integer
`errorCode`	string \| null
`plan`	object \| null	Plan totals; null before planning and after a failure.
`plan.distanceMeters`	integer
`plan.drivingSeconds`	integer
`plan.totalSeconds`	integer
`plan.chargingStopCount`	integer
`plan.gridEnergyWh`	integer
`plan.arrivalAt`	string (date-time) \| null
`plan.arrivalSocPercent`	number \| null
`plan.warningCodes`	array of string
`links`	object	API address of the route (GET for the points and the full plan).
`links.self`	string

WebhookPointList

WebhookPointList
Field	Type	Description
`id`	string (uuid)
`status`	string: pending \| processing \| awaiting_mapping \| ready \| needs_review \| committed \| superseded \| failed \| cancelled
`sourceRef`	string \| null
`rows`	object
`rows.total`	integer
`rows.ready`	integer
`rows.review`	integer
`rows.rejected`	integer
`errorCode`	string \| null
`links`	object	API address of the point list.
`links.self`	string

WebhookExport

WebhookExport
Field	Type	Description
`id`	string (uuid)
`kind`	string: route_schedule \| day_schedule \| route_gpx \| monthly \| route_card \| delivery_proofs
`format`	string
`fileName`	string	Empty for the files of the panel only.
`byteSize`	integer
`expiresAt`	string (date-time) \| null
`links`	object	API addresses of the export and its file; empty for the files of the panel only.
`links.self`	string
`links.file`	string

WebhookAssignment

WebhookAssignment
Field	Type	Description
`id`	string (uuid)
`status`	string
`assignedAt`	string (date-time) \| null
`routeId`	string (uuid)
`routeRevision`	integer
`serviceDate`	string (date)
`driverId`	string (uuid)
`previousDriverId`	string (uuid) \| null
`links`	object	API address of the route.
`links.route`	string

WebhookExecution

WebhookExecution
Field	Type	Description
`executionId`	string (uuid)
`assignmentId`	string (uuid)
`routeId`	string (uuid)
`status`	string	State of the execution, e.g. accepted, checked_in, started, completed, declined, abandoned.
`stateVersion`	integer	Grows with every change of the execution: ignore an event older than the one you have.
`replanRequired`	boolean	Check-in only: the vehicle or the battery level differs from the plan, so the route is planned again.
`stop`	object	fleet.stop.updated only.
`stop.id`	string (uuid)
`stop.status`	string: arrived \| completed \| skipped \| failed
`stop.reason`	string: other \| customer_unavailable \| recipient_refused \| access_closed \| vehicle_fault \| charger_fault \| safety \| dispatch_cancelled \| null

WebhookReadiness

WebhookReadiness
Field	Type	Description
`serviceDate`	string (date)
`status`	string: risk \| ok \| unknown \| none	risk for fleet.readiness.risk; ok, unknown or none (no route that day any more) for fleet.readiness.resolved.
`reasonCode`	string \| null
`vehicleId`	string (uuid) \| null
`routeId`	string (uuid) \| null
`placeId`	string (uuid) \| null
`departureAt`	string (date-time) \| null
`predictedSocPercent`	number \| null
`requiredSocPercent`	number
`energyNeededKwh`	number
`shortfallKwh`	number
`chargingStartAt`	string (date-time) \| null
`socSource`	string: driver_report \| plan \| vehicle_profile \| none
`socObservedAt`	string (date-time) \| null
`returnToBaseConfirmed`	boolean \| null
`chargingAssumption`	string \| null
`previousExecutionStatus`	string \| null
`previousReasonCode`	string	fleet.readiness.resolved only: the announced reason.
`previousShortfallKwh`	number	fleet.readiness.resolved only: the announced shortfall.
`links`	object	API address of the route (empty without a route).
`links.route`	string

WebhookAlert

WebhookAlert
Field	Type	Description
`id`	string (uuid)
`type`	string: driver_check_in \| driver_pin_locked \| window_missed \| plan_partial \| plan_missing \| replan_failed \| charging_warning \| no_driver \| driver_unavailable \| vehicle_unavailable \| readiness_risk \| station_unavailable
`severity`	string: critical \| warning
`status`	string: open \| acknowledged \| resolved
`serviceDate`	string (date) \| null
`routeId`	string (uuid) \| null
`vehicleId`	string (uuid) \| null
`raisedAt`	string (date-time) \| null
`resolvedAt`	string (date-time) \| null
`resolution`	string: manual \| condition_cleared \| route_closed \| expired \| swapped \| null
`details`	object	Codes and counts only; a key is present when it applies to the alert type.
`details.errorCode`	string
`details.revision`	integer
`details.unplannedPointCount`	integer
`details.lateStopCount`	integer
`details.maxLateSeconds`	integer
`details.sequences`	array of integer
`details.stopCount`	integer
`details.codes`	array of string
`details.stops`	array of object
`details.stops[].index`	integer
`details.stops[].codes`	array of string
`details.reason`	string
`details.untilAt`	string (date-time)
`details.reasonCode`	string
`details.shortfallWh`	integer
`details.stopIndex`	integer
`details.locationPublicId`	string (uuid)
`details.hasBackup`	boolean
`links`	object	API address of the route (empty without a route).
`links.route`	string

EV+MAP Fleet API

Keys, limits and rules

Operations

Account

GET /fleet/openapi

GET /fleet/capabilities

Routes

POST /fleet/routes

GET /fleet/routes

POST /fleet/routes/batch

GET /fleet/routes/{routeId}

POST /fleet/routes/{routeId}/cancel

POST /fleet/routes/{routeId}/replan

POST /fleet/routes/{routeId}/approve

POST /fleet/routes/{routeId}/customer-links