{ "openapi": "3.1.0", "info": { "title": "Drive API", "version": "1.0.0", "description": "The Drive API provides comprehensive access to Plugsurfing's charging infrastructure network. It enables you to manage users, charging keys, search for charging locations, handle payments, and control charging sessions." }, "servers": [ { "url": "https://{environment}.plugsurfing.com", "variables": { "environment": { "enum": [ "drive-api-stage" ], "default": "drive-api-stage", "description": "API environment - use drive-api-stage for testing and drive-api for production" } } } ], "tags": [ { "name": "Geosearch", "description": "Search and retrieve detailed information about charging locations and stations" }, { "name": "Users", "description": "Manage user accounts including creation, retrieval, updates, and deletion. Handles user-specific data and preferences." }, { "name": "Charging Keys", "description": "Manage physical and virtual charging keys including creation, activation, updates, and status management. Essential for user access to charging stations." }, { "name": "Sessions", "description": "Access and manage charging session data including history, status, and detailed session information" }, { "name": "Remote Charging", "description": "Control charging sessions remotely including starting and stopping sessions, and monitoring session status" }, { "name": "Payment Options", "description": "Manage payment methods and handle transaction processing for charging services" }, { "name": "User Groups", "description": "Manage user group memberships" }, { "name": "Vouchers", "description": "Redeem vouchers" }, { "name": "Charging Key Orders", "description": "Handle the ordering and fulfillment process for physical charging keys" }, { "name": "EMP Charging Keys", "description": "E-Mobility Provider specific endpoints for managing charging keys" }, { "name": "EMP Geosearch", "description": "E-Mobility Provider specific endpoints for location search and information" }, { "name": "EMP Orders", "description": "E-Mobility Provider specific endpoints for managing orders" }, { "name": "EMP Sessions", "description": "E-Mobility Provider specific endpoints for managing charging sessions" }, { "name": "EMP Fleets", "description": "E-Mobility Provider specific endpoints for managing fleets" } ], "paths": { "/drive/v1/users/{userId}/charging-keys/{referenceId}/activate": { "post": { "tags": [ "Charging Keys" ], "summary": "Activate a charging key", "description": "Activates a charging key for a specific user. The key must exist and be unassigned. Once activated, the key can be used to start charging sessions.", "operationId": "activateUserChargingKey", "parameters": [ { "name": "referenceId", "in": "path", "description": "Human-readable identifier written on the rfid card or tag, visualNumber from the charging key reservation.", "example": "DE*8PS*FR1RFK*4", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "The unique identifier of the user who will own this charging key. Must be a valid user ID in your system.", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyActivateRequest" }, "example": { "whitelist": "NEVER" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKey" }, "example": { "keyId": "0eb7732d-eb7a-418c", "referenceId": "DE*8PS*AD21B1*3", "contractId": "DE-8PS-C0AD21B13-Q", "name": "My RFID key", "validFrom": "2022-01-24T11:25:54.210Z", "validTo": "2032-01-24T11:25:54.210Z", "type": "card", "enabled": true, "whitelist": "NEVER", "created": "2025-01-15T10:30:00Z", "updated": "2025-01-15T10:30:00Z" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User or charging key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Key already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/charging-keys/{identifier}": { "patch": { "tags": [ "Charging Keys" ], "summary": "Edit a charging key", "description": "Modify a charging key's properties. You can change the key's name and enable/disable it. Disabling a key immediately prevents it from being used for charging. Important notes:\n- Only non-null fields in the request are applied\n- Disabling a key takes effect immediately across all charging stations\n- Some CPOs cache key status, so in rare cases it may take a few minutes for the disable action to propagate\n- Name changes are purely cosmetic and don't affect the key's functionality", "operationId": "updateUserChargingKey", "parameters": [ { "name": "identifier", "in": "path", "description": "The unique identifier for the charging key - can be either the keyId (internal identifier) or contractId (roaming identifier)", "example": "0eb7732d-eb7a-418c", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "description": "The unique identifier of the user who owns the charging key", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyPatchRequest" }, "example": { "name": "My RFID key updated", "enabled": true, "whitelist": "ALLOWED_OFFLINE" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKey" }, "example": { "keyId": "0eb7732d-eb7a-418c", "referenceId": "DE*8PS*AD21B1*3", "contractId": "DE-8PS-C0AD21B13-Q", "name": "My RFID key", "validFrom": "2022-01-24T11:25:54.210Z", "validTo": "2032-01-24T11:25:54.210Z", "type": "card", "enabled": true, "whitelist": "ALLOWED_OFFLINE", "created": "2025-01-15T10:30:00Z", "updated": "2025-01-15T10:30:00Z" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User or charging key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict — can happen when making two requests to update the same charging key in a short period of time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/charging-keys": { "get": { "tags": [ "Charging Keys" ], "summary": "Get user's charging keys", "description": "Retrieves all charging keys associated with a specific user. This includes both active and inactive keys, physical and virtual keys. The response contains detailed information about each key including its status, type, and validity period.", "operationId": "listUserChargingKeys", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user whose charging keys should be retrieved", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ChargingKey" } } } }, "example": { "keys": [ { "keyId": "0eb7732d-eb7a-418c", "referenceId": "DE*8PS*AD21B1*3", "contractId": "DE-8PS-C0AD21B13-Q", "name": "My RFID key", "validFrom": "2022-01-24T11:25:54.210Z", "validTo": "2032-01-24T11:25:54.210Z", "type": "card", "enabled": true, "whitelist": "NEVER", "created": "2025-01-15T10:30:00Z", "updated": "2025-01-15T10:30:00Z" } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Charging Keys" ], "summary": "Create a charging key", "description": "Creates a new charging key for a specified user. Important notes:\n- The key will be created in an enabled state by default\n- Contract id, keyIdentifier and visualNumber must be provided.", "operationId": "createUserChargingKey", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user who will own the new charging key", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyPostRequest" }, "example": { "name": "My RFID key", "keyIdentifier": "04A224B7C89280", "contractId": "DE-8PS-C0AD21B13-Q", "visualNumber": "DE*8PS*FR1RFK*4", "enabled": true, "whitelist": "NEVER" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKey" }, "example": { "keyId": "0eb7732d-eb7a-418c", "referenceId": "DE*8PS*AD21B1*3", "contractId": "DE-8PS-C0AD21B13-Q", "name": "My RFID key", "validFrom": "2022-01-24T11:25:54.210Z", "validTo": "2032-01-24T11:25:54.210Z", "type": "card", "enabled": true, "whitelist": "NEVER", "created": "2025-01-15T10:30:00Z", "updated": "2025-01-15T10:30:00Z" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/charging-keys/plug-and-charge": { "post": { "tags": [ "Charging Keys" ], "summary": "Create a Plug&Charge key", "description": "Creates a Plug&Charge charging key for a user. The key enables\nroaming authorization at PnC-capable charging stations.", "operationId": "createPncChargingKey", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user who will own the new Plug&Charge key", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Plug&Charge key creation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyPlugAndChargePostRequest" }, "example": { "pcid": "WDBRF61J21F123456", "contractId": "DE-8PS-C0AD21B13-Q" } } }, "required": true }, "responses": { "200": { "description": "Plug&Charge key created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyPlugAndChargePostResponse" }, "example": { "contractId": "DE-8PS-C0AD21B13-Q", "pcid": "WDBRF61J21F123456", "keyId": "DE-8PS-C0AD21B13-Q" } } } }, "400": { "description": "Invalid request. Possible causes: PCID or contractId syntactically incorrect, contractId prefix not allowed for organization or Plug&Charge feature not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "fields": [ { "name": "pcid", "message": "PCID must be 17-18 alphanumeric characters", "rejectedValue": "invalid" } ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "A charging key for this EMAID already exists (if EMAID-sharing is not allowed for the organization).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "A charging key for this EMAID already exists" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Internal server error" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/charging-keys/orders": { "post": { "tags": [ "Charging Key Orders" ], "summary": "Create charging key order", "description": "Orders a charging key for the given user. Requires the product to be configured on Plugsurfing side. Therefore, we ask you to reach out to us before using it.", "operationId": "createChargingKeyOrder", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyOrderRequest" }, "example": { "productId": "physical-rfid-key", "quantity": 1, "address": { "line1": "Kungsgatan 1", "line2": "Floor 2", "city": "Stockholm", "postalCode": "11143", "countryCode": "SE", "firstName": "Olivier", "lastName": "Payen", "company": "Plugsurfing" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyOrderResponse" }, "example": { "id": "9aE20Rmj0v", "state": "ORDER_PLACED", "clientSecret": "pi_1J5J9v3sZvKYlo2C5J9v2eZv" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "429": { "description": "Too many requests — a given user can't order more than 1 card every 5 minutes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Charging Key Orders" ], "summary": "Get list of charging key orders", "description": "Returns the list of ordered charging keys by a given user.", "operationId": "listChargingKeyOrders", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyOrdersListResponse" }, "example": [ { "id": "vrj82A9EpJ", "created": "2022-04-07T11:30:57.000Z", "updated": "2022-04-07T11:30:57.000Z", "address": { "companyName": "Plusurfing", "firstName": "Luck", "lastName": "Thomson", "addressLine1": "Rättarvägen 3", "addressLine2": "Rättarvägen 3", "postalCode": 12345, "city": "Solna", "country": "Sweden" }, "quantity": 1, "currency": "SEK", "priceMinorInclVat": 1010, "state": "ORDER_PLACED", "hasReceipt": false } ] } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/charging-keys/orders/{orderId}/receipt": { "get": { "tags": [ "Charging Key Orders" ], "summary": "Get order receipt URL", "description": "Returns an absolute URL to the order's receipt. The receipt will be in PDF format.", "operationId": "getChargingKeyOrderReceiptUrl", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyOrderReceiptResponse" }, "example": { "url": "string" } } } }, "400": { "description": "Provided path parameter, is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "Receipt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/charging-keys/orders/configuration": { "get": { "tags": [ "Charging Key Orders" ], "summary": "Get pricing information per country", "description": "Returns the pricing information for ordering charging keys per country. Each country has to be set up manually for your organization in order for it to show up here.", "operationId": "getChargingKeyOrderConfiguration", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyConfigurationResponse" }, "example": { "countries": [ { "country": "SE", "currency": "SEK", "priceMinorInclVat": 1, "vat": 1 } ] } } } }, "404": { "description": "No pricing found for organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/charging-keys/reservations": { "post": { "tags": [ "Charging Keys" ], "summary": "Reserve a charging key", "description": "Create connection between uid (physical chip id) and visualNumber (called later 'referenceId'), so that the latter can be used for activation.", "operationId": "createChargingKeyReservation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargingKeyReservationsRequest" }, "example": { "amount": 5, "countryCode": "DE", "products": [ "RFID_CARD" ], "userId": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "language": "en" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "deprecated": false, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/geosearch/radius": { "post": { "summary": "Radius search", "description": "Find charging locations within a specified radius around a geographic point. The center point, distance, limit, and aggregation settings are passed via query parameters; the request body contains only filters. Use an empty JSON body (`{}`) when no filters are needed. Returns up to 300 locations sorted by proximity to the search center (nearest first). Prices are not included. To get prices for a given location, use Get location by id.", "operationId": "searchLocationsByRadius", "tags": [ "Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusRequest" }, "examples": { "remoteStartFilter": { "summary": "Filter by remote start capability", "value": { "filters": { "connectorStandards": [ "Type2" ], "capabilities": [ "REMOTE_START_STOP_CAPABLE" ] } } }, "plugAndChargeFilter": { "summary": "Filter by Plug&Charge capability", "value": { "filters": { "connectorStandards": [ "Combo" ], "capabilities": [ "PLUG_AND_CHARGE_CAPABLE" ] } } } } } } }, "parameters": [ { "name": "latitude", "in": "query", "required": true, "description": "Latitude of the center point in decimal degrees (e.g. N58°30' is represented as 58.5)", "example": 52.354551, "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "longitude", "in": "query", "required": true, "description": "Longitude of the center point in decimal degrees (e.g. E014°45' is represented as 14.75)", "example": 4.7391593, "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "distance", "in": "query", "description": "Search radius in meters", "schema": { "type": "integer", "default": 3000 } }, { "name": "limit", "in": "query", "description": "Maximum number of individual locations to return. Not applicable when aggregation is enabled. Use a lower limit for faster response times.", "schema": { "type": "integer", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "Enable result aggregation. Recommended for large search radii to improve response time.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Controls the size of aggregation grid cells. Values range from 2 (largest cells) to 9 (smallest cells). Higher precision means smaller clusters but more data. If not specified, an appropriate value based on the search radius is used.", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 9 } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/geosearch/rectangle": { "post": { "summary": "Rectangle search", "description": "Find charging locations within a specified rectangle defined by two diagonal points. The rectangle coordinates are passed via the `topLatitude`, `bottomLatitude`, `leftLongitude`, and `rightLongitude` query parameters; the request body contains only filters. Returns up to 300 locations. Prices are not included. To get prices for a given location, use Get location by id", "operationId": "searchLocationsByRectangle", "tags": [ "Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RectangleRequest" }, "examples": { "chargingProfileFilter": { "summary": "Filter by charging profile capability", "value": { "filters": { "connectorStandards": [ "Combo" ], "capabilities": [ "CHARGING_PROFILE_CAPABLE" ] } } }, "plugAndChargeFilter": { "summary": "Filter by Plug&Charge capability", "value": { "filters": { "connectorStandards": [ "Combo" ], "capabilities": [ "PLUG_AND_CHARGE_CAPABLE" ] } } } } } } }, "parameters": [ { "name": "topLatitude", "in": "query", "required": true, "description": "Latitude of the top edge of the rectangle in decimal degrees (e.g. N58°30' is represented as 58.5). Must be greater than bottomLatitude.", "example": 52.354551, "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "bottomLatitude", "in": "query", "required": true, "description": "Latitude of the bottom edge of the rectangle in decimal degrees (e.g. S58°30' is represented as -58.5)", "example": 52.354551, "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "leftLongitude", "in": "query", "required": true, "description": "Longitude of the left edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75). Must be less than rightLongitude.", "example": 4.7391593, "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "rightLongitude", "in": "query", "required": true, "description": "Longitude of the right edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75)", "example": 4.7391593, "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "limit", "in": "query", "description": "Maximum number of individual locations to return. Not applicable when aggregation is enabled. Use a lower limit for faster response times.", "required": false, "schema": { "type": "integer", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "Enable result aggregation. Recommended for large search radii to improve response time.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Controls the size of aggregation grid cells. Values range from 2 (largest cells) to 9 (smallest cells). Higher precision means smaller clusters but more data. If not specified, an appropriate value based on the search radius is used.", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 9 } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/geosearch/route": { "post": { "summary": "Route search", "description": "Search for charging locations along a route. The max number of points in a route is 300. Prices are not included. To get prices for a given location, use Get location by id", "operationId": "searchLocationsByRoute", "tags": [ "Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlongRouteRequest" }, "examples": { "routeSearch": { "summary": "Search along a route", "value": { "points": [ { "latitude": 52.52, "longitude": 13.405 }, { "latitude": 52.37, "longitude": 4.9 } ], "filters": { "connectorStandards": [ "Combo" ] } } }, "routeSearchWithPnC": { "summary": "Search along a route for PnC-capable stations", "value": { "points": [ { "latitude": 52.52, "longitude": 13.405 }, { "latitude": 52.37, "longitude": 4.9 } ], "filters": { "connectorStandards": [ "Combo" ], "capabilities": [ "PLUG_AND_CHARGE_CAPABLE" ] } } } } } } }, "parameters": [ { "name": "width", "in": "query", "description": "Distance to search from the center of the route, in meters (will be split equally on both sides of the route)", "schema": { "type": "number", "default": 3000 } }, { "name": "limit", "in": "query", "description": "Number of locations returned in the response (doesn't apply when aggregation is enabled)", "schema": { "type": "number", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "If true, the results will be aggregated. For large radius it makes the response much faster.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.", "required": false, "schema": { "type": "number", "minimum": 2, "maximum": 9 } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/locations/{locationId}": { "get": { "tags": [ "Geosearch" ], "summary": "Get location by id", "operationId": "getLocationById", "description": "Get location details, including prices. Only one of userId or keyIdentifier can be provided in a single request. If none are provided, default prices are returned. For more information on prices, check https://developer.plugsurfing.com/docs/geosearch#explanation", "parameters": [ { "name": "locationId", "in": "path", "description": "Location id.", "example": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "description": "The id of a user, will be used to look up specific prices for this user", "required": false, "schema": { "type": "string" } }, { "name": "keyIdentifier", "in": "query", "description": "The keyIdentifier of a chargingKey, will be used to look up specific prices for this chargingKey", "required": false, "schema": { "type": "string" } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, ru, sv." } ], "responses": { "200": { "description": "Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U=", "standard": "Type2", "power": 22000, "power_type": "AC_3_PHASE", "price": { "id": "4370769f30bd7927", "description": "€ 0.56/kWh, € 0.10/min (> 2 h)", "currency": "EUR", "priceIncludesVat": "true", "vatRate": "22", "elements": [ {} ] }, "max_amperage": 32, "max_voltage": 400 } ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } } } }, "404": { "description": "Location not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/locations/{locationId}/live-data": { "get": { "tags": [ "Geosearch" ], "summary": "Get location live data", "operationId": "getLocationLiveData", "description": "Returns live charging data for the EVSEs of a location that are in use, including since when each EVSE has had its current live status. The `charge_point_statuses` keys match the EVSE `uid` values returned by Get location by id. EVSEs without live data are omitted. Returns `404` when the location is not found or live data is not enabled for your organization. For details, check https://developer.plugsurfing.com/docs/geosearch#location-live-data", "parameters": [ { "name": "locationId", "in": "path", "description": "Location id.", "example": "el00cee2f58f4cef4decacb32601ff563a97", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Live data of the location EVSEs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationLiveData" }, "example": { "charge_point_statuses": { "ee006b89511e81534e019ca0d9a780b351e9": { "status": "CHARGING", "status_since": "2025-01-15T08:12:00Z" } } } } } }, "404": { "description": "Location not found or live data not enabled for your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Internal server error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/locations/batch": { "get": { "tags": [ "Geosearch" ], "summary": "Batch locations", "operationId": "getLocationsBatch", "description": "Retrieve locations in batches. Locations are returned sorted by last_updated timestamp in ascending order. Prices are not included, to get prices for a given location, use Get location by id. Best practices:\n1. Perform initial FULL PULL by paginating through all locations\n2. Perform regular DELTA PULLS using last_updated parameter to get only updated locations\n3. Use the last_updated value of the last location in the last page as the starting point for next DELTA PULL\n4. Perform periodic FULL PULLS to detect removed locations\n5. Use cursor to resume interrupted pulls", "parameters": [ { "name": "page_size", "in": "query", "description": "Optional - used to set page size value", "required": false, "schema": { "type": "number", "minimum": 10, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Optional - pass cursor from previous response body to get next page.", "required": false, "schema": { "type": "string" } }, { "name": "last_updated", "in": "query", "description": "Optional - when set, only locations updated after this date are returned. example `2024-05-27T10:44:48Z`.", "required": false, "schema": { "type": "string" } }, { "name": "countries", "in": "query", "description": "Optional - when set, only locations in these countries are returned. example `DEU` or `DEU,FRA`.", "required": false, "schema": { "type": "string" } }, { "name": "power_type", "in": "query", "description": "Optional - when set, only locations having at least one connector with this power_type are returned. possible values: `AC` or `DC`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchLocationsResponse" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "cursor": "string" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/locations/operators": { "get": { "tags": [ "Geosearch" ], "summary": "Get list of operators", "operationId": "listOperators", "description": "Returns the list of Charging Point Operators (CPOs) whose chargers are available through the geosearch endpoints. Can be used to let users filter on specific operators", "parameters": [ { "name": "cursor", "in": "query", "description": "Cursor used to get next page. Returned from previous response from this endpoint. Should be URL encoded.", "example": "H6Zb4Z8p+4/vhPl9JKVHM+9/XWoF02I4EIKblAd3nMk=", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorsListResponse" }, "example": { "operators": [ { "id": 1547830, "name": "string", "externalId": "id_12345" } ], "cursor": "H6Zb4Z8p+4/vhPl9JKVHM+9/XWoF02I4EIKblAd3nMk=" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/payment-options": { "get": { "tags": [ "Payment Options" ], "summary": "Get user's payment methods", "description": "Retrieves all payment methods associated with a user.", "operationId": "listPaymentOptions", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user whose payment methods should be retrieved", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CreditCardPaymentOption" } ] } }, "example": [ { "id": "STRIPE-7844364278189399", "paymentMethod": "CREDIT_CARD", "brand": "visa", "displayBrand": "visa", "countryCode": "DE", "expMonth": 12, "expYear": 2025, "last4": "1234" } ] } } }, "400": { "description": "Bad Request - returned when payment method does not exist or it's already attached to any user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Payment Options" ], "summary": "Add a new payment method", "description": "Adds a new payment method to a user's account. Important notes:\n- A user can only have one payment method at a time.", "operationId": "createPaymentOption", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user to add the payment method for", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateStripeCreditCardRequest" } ] }, "example": { "paymentMethodId": "pm_1N9KPP2eZvKYlo2CY8E0x92p" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreditCardPaymentOption" } ] }, "example": { "id": "STRIPE-7844364278189399", "paymentMethod": "CREDIT_CARD", "brand": "visa", "displayBrand": "visa", "countryCode": "DE", "expMonth": 12, "expYear": 2025, "last4": "1234" } } } }, "400": { "description": "Bad Request - returned when payment method does not exist or it's already attached to any user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict - returned if a payment option is already assigned to the user, and can be resolved by deleting the existing payment option first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/payment-options/stripe-setup-intent": { "get": { "tags": [ "Payment Options" ], "summary": "Get Stripe SetupIntent to confirm a payment method", "description": "Creates and returns a Stripe SetupIntent client secret so the user can securely attach a new payment method.", "operationId": "createStripeSetupIntent", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntent" }, "example": { "id": "seti_3N9KQw2eZvKYlo2C1Wm0R8AB", "clientSecret": "seti_3N9KQw2eZvKYlo2C1Wm0R8AB_secret_example" } } } }, "400": { "description": "Bad Request - returned when payment method does not exist or it's already attached to any user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/payment-options/{id}": { "delete": { "tags": [ "Payment Options" ], "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Payment option id", "example": "STRIPE-7844364278189399", "required": true, "schema": { "type": "string" } } ], "summary": "Delete user's payment option", "description": "Removes a stored payment option from the specified user when the payment method is eligible for deletion.", "operationId": "deletePaymentOption", "responses": { "204": { "description": "Payment option was deleted successfully" }, "400": { "description": "Bad Request - returned when payment method does not exist on this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "403": { "description": "Specified payment option cannot be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "User or payment option not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/prepaid": { "get": { "tags": [ "Payment Options" ], "summary": "Get user's prepaid balance", "description": "Retrieves the current prepaid balance for a specific user. Returns a breakdown of balances with their sources (e.g. Credit, Voucher) and expiry dates, as well as a total balance.", "operationId": "listPrepaid", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepaidBalance" }, "example": { "balanceTotal": { "amountMinorUnits": 1000, "currency": "EUR" }, "balances": [ { "expiryDate": "2024-12-31T23:59:59Z", "amountMinorUnits": 1000, "currency": "EUR", "source": "Credit", "initialAmountMinorUnits": 1000 } ] } } } }, "404": { "description": "User not found or user has no prepaid balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/history": { "post": { "tags": [ "Sessions" ], "summary": "Get charging session history", "description": "Retrieves the charging session history for a specific user. The response includes detailed information about each session including:\n- Session status and duration\n- Energy consumption\n- Cost and payment details\n- Charging location information\n\nThe results can be filtered by:\n- Session status\n- Specific charging key\n- Date range\n\nPagination is supported through the cursor parameter.", "operationId": "listSessions", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user whose session history should be retrieved", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsHistoryRequest" }, "example": { "fromDate": "2025-01-01", "toDate": "2025-01-31", "limit": 20, "page": 1, "sortBy": "startTime", "sortDirection": "DESC" } } }, "required": false }, "responses": { "200": { "description": "Save the cursor to access next pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsHistoryResponse" }, "example": { "sessions": [], "total": 0, "hasMore": false } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/{sessionId}": { "get": { "tags": [ "Sessions" ], "summary": "Get details of a specific charging session", "description": "Retrieves detailed information about a specific charging session. This includes:\n- Session status (completed or in-progress)\n- Energy consumption and duration\n- Cost and payment status\n- Charging location details\n- Charging key used\n\nThis endpoint can be used to track both completed sessions and monitor ongoing ones.", "operationId": "getSessionById", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user who owns the charging session", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "description": "The unique identifier of the charging session", "required": true, "example": "AAdmD55q8Vz", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "example": { "balanceStatus": "PROCESSING", "sessionStatus": "CREATED", "charger": { "chargingStationName": "Drive_API_Test1_Station1", "city": "Solna", "connectorLabel": "1", "evseId": "SE*CND*EC1*1", "streetName": "Rättarvägen" }, "balanceAmountMinor": "-2160", "chargingKeyType": "virtual", "connectorId": "O9UXK+YI5Q6i0FoI4qHwcA==", "duration": "PT28.913S", "energy": { "unit": "WH", "value": 57 }, "paymentMethod": "CREDIT_CARD", "price": { "currencyCode": "EUR", "minorExclVat": 2785, "minorInclVat": 1, "vat": "17.5" }, "receiptAvailable": true, "sessionId": "AAdmD55q8Vz", "site": "Drive_API_Test1", "startTime": "2021-01-30T10:00:00.111111111Z", "transactions": [ { "paymentMethod": "CREDIT_CARD", "paymentOutcome": "CHARGE", "amount": { "currencyCode": "EUR", "minorExclVat": 2785, "minorInclVat": 1, "vat": "17.5" }, "time": "2021-01-30T10:00:00.111111111Z" } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/{sessionId}/receipt": { "get": { "tags": [ "Sessions" ], "operationId": "getSessionReceipt", "summary": "Get a session receipt by session id", "description": "Get session receipt. The response includes a time-limited URL to access the receipt. A new URL is required after expiration. Receipts are not available for sessions with a price of 0, and a 404 error will be returned if requested. The receipt will be in PDF format.", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "example": "AAdmD55q8Vz", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "url": "string" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "Receipt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/start": { "post": { "tags": [ "Remote Charging" ], "summary": "Start a remote charging session", "operationId": "startRemoteSession", "description": "Start a remote charging session. Important implementation details:\n1. Only chargers with REMOTE_START_STOP_CAPABLE capability can be used\n2. Allow up to 2 minutes for session to transition from WAITING_TO_START to STARTED\n3. Wait at least 1 minute before retrying failed starts\n4. Multiple ongoing sessions are possible\n5. Subsequent start requests within 60 seconds on same connector are blocked\n6. Session events will notify about session status changes\n7. If a user has `CREDIT_CARD` payment method, and 3DS challenge mode is set to `CHALLENGE`, then `threeDSClientSecret` might be present instead of `sessionId`, which your frontend needs to prompt the user to sign. After the user successfully signs the challenge, do a second start request!", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user who will own the charging session", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartRequest" }, "example": { "connectorId": "O9UXK+YI5Q6i0FoI4qHwcA==" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartResponse" }, "example": { "sessionId": "AAdmD55q8Vz", "threeDSClientSecret": "pi_3MtwBwLkdIwHu8ix28v3tqPa_secret_YrKJUkribcBjcG7HVhfZluoGH" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "403": { "description": "Forbidden. The user is not allowed to charge, or the connector won't allow remote charging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/{sessionId}/stop": { "post": { "tags": [ "Remote Charging" ], "summary": "Stop a remote charging session", "operationId": "stopRemoteSession", "description": "Stop a remote charging session. Only sessions started remotely (chargingKeyType=virtual) can be stopped remotely. Important implementation details:\n1. Session may be stopped locally even if started remotely\n2. Events like SESSION_STOPPED or SESSION_COMPLETED may be received without calling stop\n3. If stop request fails, allow retrying after a few minutes\n4. If session stays in STOP_FAILED, allow starting new session", "parameters": [ { "name": "userId", "in": "path", "description": "The unique identifier of the user who owns the charging session", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "description": "The unique identifier of the charging session to stop", "required": true, "example": "AAdmD55q8Vz", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/sessions/{sessionId}/payments/retry": { "post": { "tags": [ "Sessions" ], "summary": "Retry session payment", "operationId": "retrySessionPayment", "description": "Use this endpoint to retry an unsuccessful session payment", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "example": "AAdmD55q8Vz", "schema": { "type": "string" } } ], "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "example": { "paymentMethodId": "STRIPE-7844364278189399", "idempotencyKey": "retry-payment-001" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" }, "example": { "paymentStatus": "SUCCEEDED", "statusDetails": "Payment retried successfully" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "403": { "description": "Forbidden. You have no access to this session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict. The current state of the session does not allow a payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/user-groups/{groupId}": { "post": { "tags": [ "User Groups" ], "summary": "Add user to user group", "description": "Creates a membership link between the user and the specified user group.", "operationId": "createUserGroupMembership", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "User Group id", "example": "aGnOerO87e", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Adding user to user group was successful" }, "400": { "description": "Bad Request - returned when user group id is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User or user group not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "User Groups" ], "summary": "Remove user from user group", "description": "Deletes the membership link between the user and the specified user group.", "operationId": "deleteUserGroupMembership", "parameters": [ { "name": "userId", "in": "path", "example": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "User Group id", "example": "aGnOerO87e", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removing user from user group was successful" }, "400": { "description": "Bad Request - returned when user group id is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}/vouchers/{code}/redeem": { "post": { "tags": [ "Vouchers" ], "summary": "Redeem a voucher code", "description": "Redeems a voucher for the user and returns the product granted by the voucher campaign.", "operationId": "redeem", "parameters": [ { "name": "userId", "in": "path", "description": "userId", "example": "driveUser1", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "path", "description": "Voucher Code", "example": "AABBCC11", "required": true, "schema": { "type": "string", "pattern": "([a-zA-Z0-9_]+)" } } ], "responses": { "200": { "description": "default response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "type": "PREPAID", "amountMinorUnits": 1050, "currencyCode": "EUR" } } } }, "400": { "description": "The campaign voucher code is expired, not started yet or exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User or voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "The payment setup is not compatible with vouchers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users": { "post": { "tags": [ "Users" ], "summary": "Create user", "operationId": "createUser", "description": "Only the `id` field is required (any string is accepted) when you are the Merchant on Record. If Plugsurfing is the Merchant on Record the `email` field is mandatory as well. Use the same user ID from your system for consistency", "requestBody": { "description": "request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUser" }, "example": { "email": "driver@example.com", "language": "en" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": {} }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "409": { "description": "Conflict - a user with this id or email already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/drive/v1/users/{userId}": { "get": { "tags": [ "Users" ], "summary": "Read user details", "operationId": "getUser", "description": "Getting user data based on passed userId", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfo" }, "example": { "id": "6f36dc9b-446f-462b-aae0-95c7636d5c6c", "email": "driver@example.com", "language": "en", "vatNumber": "SE123456789001", "billingAddress": { "line1": "Kungsgatan 1", "city": "Stockholm", "postalCode": "11143", "countryCode": "SE" }, "userGroups": [] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "Users" ], "summary": "Update user details", "operationId": "updateUser", "description": "This endpoints lets you update a given user's email, VAT number and billing address.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Email address must be unique", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUser" }, "example": { "email": "driver.updated@example.com", "vatNumber": "SE123456789001", "billingAddress": { "line1": "Kungsgatan 1", "city": "Stockholm", "postalCode": "11143", "countryCode": "SE" } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict - this email is already taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Remove user", "operationId": "deleteUser", "description": "Disables all charging keys of the user immediately and schedules the user's deletion for 30 days later. This delay ensures that late-arriving Charging Detail Records (CDRs) can still be linked to the user. Note: If Plugsurfing handles payments, users with outstanding debt cannot be deleted.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "OK" }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict - user has debt or another reason blocks deleting it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/charging-keys": { "get": { "tags": [ "EMP Charging Keys" ], "summary": "Get charging keys", "description": "Fetches charging keys belonging to a given fleet, or all charging keys if not fleet is specified.", "operationId": "listEmpChargingKeys", "parameters": [ { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet you want to filter charging keys on. If not id is specified, it will return all charging keys", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Optional - pass cursor from previous response body to get the next page.", "required": false, "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "description": "Optional - used to set page size value", "required": false, "schema": { "type": "number", "minimum": 10, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/EmpChargingKeyResponse" } }, "cursor": { "type": "string" } } }, "example": { "keys": [ { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "y1nNLJqb7m", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } ], "cursor": "string" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "EMP Charging Keys" ], "summary": "Create a charging key", "description": "Creates a charging key with given key identifier, contract id and visual number.", "operationId": "createEmpChargingKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyPostRequest" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "e0e03336", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "DE-9FS-C045DS363-E", "enabled": true, "whitelist": "NEVER" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyResponse" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "y1nNLJqb7m", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } } } }, "400": { "description": "Provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "409": { "description": "Charging key already activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/charging-keys/{keyIdentifier}/rename": { "put": { "tags": [ "EMP Charging Keys" ], "summary": "Rename a charging key", "description": "Renames a charging key given its key identifier", "operationId": "renameEmpChargingKey", "parameters": [ { "name": "keyIdentifier", "in": "path", "description": "keyIdentifier provided when creating the charging key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyRenameRequest" }, "example": { "newName": "SE6F1K2C3" } } }, "required": true }, "responses": { "200": { "description": "Succeed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyResponse" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "y1nNLJqb7m", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } } } }, "400": { "description": "Provided body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/charging-keys/{keyIdentifier}/enable": { "put": { "tags": [ "EMP Charging Keys" ], "summary": "Enable charging key", "description": "Enables a charging key given its key identifier. The charging key needs to exist, otherwise a 404 HTTP error is returned", "operationId": "enableEmpChargingKey", "parameters": [ { "name": "keyIdentifier", "in": "path", "description": "keyIdentifier provided when creating the charging key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyResponse" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "y1nNLJqb7m", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } } } }, "403": { "description": "Forbidden. You have no access to this charging key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "Charging key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/charging-keys/{keyIdentifier}/disable": { "put": { "tags": [ "EMP Charging Keys" ], "summary": "Disable charging key", "description": "Disables a charging key given its keyIdentifier. It will immediately make Plugsurfing reject all charging session requests made with this key. The charging key needs to exist, otherwise a 404 HTTP error is returned. Note: Some CPOs store whitelisted keys, so in some rare cases it might take a bit longer time until charging is rejected.", "operationId": "disableEmpChargingKey", "parameters": [ { "name": "keyIdentifier", "in": "path", "description": "keyIdentifier provided when creating charging key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyResponse" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "y1nNLJqb7m", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } } } }, "403": { "description": "Forbidden. You have no access to this charging key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "Charging key not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/charging-keys/{keyIdentifier}/transfer": { "put": { "tags": [ "EMP Charging Keys" ], "summary": "Transfer a charging key", "description": "Transfers a charging key from its current fleet to another existing fleet.\n\n**Business rules:**\n- Only charging keys that currently belong to a fleet can be transferred.\n- The target fleet must belong to the same EMP parent as the source fleet.\n- The target fleet must already have an external payment option configured.\n- Transferring to the same fleet is idempotent and returns `200 OK`.", "operationId": "transferEmpChargingKey", "parameters": [ { "name": "keyIdentifier", "in": "path", "description": "keyIdentifier provided when creating the charging key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyTransferRequest" }, "example": { "targetFleetId": "a2mPQRst8x" } } }, "required": true }, "responses": { "200": { "description": "Charging key transferred successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyResponse" }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "3633e0e0", "validTo": "2022-01-24T11:25:54.210Z", "fleetId": "a2mPQRst8x", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "6285629402937", "enabled": true, "whitelist": "NEVER" } } } }, "400": { "description": "Bad request. Possible causes:\n- Missing or invalid request body.\n- Charging key does not belong to a fleet (`Charging key must belong to a fleet`).\n- Target fleet has no external payment option (`Target fleet must have an external payment option`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Charging key must belong to a fleet" } } } }, "403": { "description": "Forbidden. The target fleet belongs to a different EMP parent than the source fleet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Target fleet belongs to a different EMP" } } } }, "404": { "description": "Source charging key or target fleet not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/geosearch/radius": { "post": { "summary": "Search locations around a point", "description": "Search for charging locations within a specified radius around a geographic point. The center point is passed via the `latitude` and `longitude` query parameters; the request body contains only filters. Returns up to 300 locations sorted by proximity to the search center (nearest first).", "operationId": "searchEmpLocationsByRadius", "tags": [ "EMP Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadiusRequest" }, "example": { "filters": { "connectorStandards": [ "Type2" ], "capabilities": [ "REMOTE_START_STOP_CAPABLE" ] } } } } }, "parameters": [ { "name": "latitude", "in": "query", "required": true, "example": "52.331142", "schema": { "type": "string" } }, { "name": "longitude", "in": "query", "required": true, "example": "13.145221", "schema": { "type": "string" } }, { "name": "distance", "in": "query", "description": "Distance in m", "schema": { "type": "number", "default": 30000 } }, { "name": "limit", "in": "query", "description": "Number of locations returned in the response (doesn't apply when aggregation is enabled)", "schema": { "type": "number", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "If true, the results will be aggregated. For large radius it makes the response much faster.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 9 } }, { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet organization, will be used to look up locations available for this fleet. If fleet id is not provided, the locations available to the EMP will be provided", "required": false, "schema": { "type": "string" } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/geosearch/rectangle": { "post": { "summary": "Search locations within a rectangle", "description": "Search for charging locations within a specified rectangle defined by two diagonal points. The rectangle coordinates are passed via the `topLatitude`, `bottomLatitude`, `leftLongitude`, and `rightLongitude` query parameters; the request body contains only filters. Returns up to 300 locations.", "operationId": "searchEmpLocationsByRectangle", "tags": [ "EMP Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RectangleRequest" }, "example": { "filters": { "connectorStandards": [ "Combo" ], "capabilities": [ "CHARGING_PROFILE_CAPABLE" ] } } } } }, "parameters": [ { "name": "topLatitude", "in": "query", "required": true, "description": "Latitude of the top edge of the rectangle in decimal degrees (e.g. N58°30' is represented as 58.5). Must be greater than bottomLatitude.", "example": 52.354551, "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "bottomLatitude", "in": "query", "required": true, "description": "Latitude of the bottom edge of the rectangle in decimal degrees (e.g. S58°30' is represented as -58.5)", "example": 52.354551, "schema": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 } }, { "name": "leftLongitude", "in": "query", "required": true, "description": "Longitude of the left edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75). Must be less than rightLongitude.", "example": 4.7391593, "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "rightLongitude", "in": "query", "required": true, "description": "Longitude of the right edge of the rectangle in decimal degrees (e.g. E014°45' is represented as 14.75)", "example": 4.7391593, "schema": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } }, { "name": "limit", "in": "query", "description": "Number of locations returned in the response (doesn't apply when aggregation is enabled)", "schema": { "type": "number", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "If true, the results will be aggregated. For large radius it makes the response much faster.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.", "required": false, "schema": { "type": "integer", "minimum": 2, "maximum": 9 } }, { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet organization, will be used to look up locations available for this fleet. If fleet id is not provided, the locations available to the EMP will be provided", "required": false, "schema": { "type": "string" } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/geosearch/route": { "post": { "summary": "Search for locations along a route", "description": "Search for locations along a route. The max number of points in a route is 300.", "operationId": "searchEmpLocationsByRoute", "tags": [ "EMP Geosearch" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlongRouteRequest" }, "example": { "points": [ { "latitude": 52.52, "longitude": 13.405 }, { "latitude": 52.37, "longitude": 4.9 } ], "filters": { "connectorStandards": [ "Combo" ] } } } } }, "parameters": [ { "name": "width", "in": "query", "description": "Width of the searching path in meters. 0.5 of the width on each side.", "schema": { "type": "number", "default": 3000 } }, { "name": "limit", "in": "query", "description": "Number of locations returned in the response (doesn't apply when aggregation is enabled)", "schema": { "type": "number", "maximum": 300, "default": 300 } }, { "name": "aggregate", "in": "query", "description": "If true, the results will be aggregated. For large radius it makes the response much faster.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "aggregationPrecision", "in": "query", "description": "Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed. Grid sizes: 2=1252.3km x 624.1km, 3=156.5km x 156km, 4=39.1km x 19.5km, 5=4.9km x 4.9km, 6=1.2km x 609.4m, 7=152.9m x 152.4m, 8=38.2m x 19m, 9=4.8m x 4.8m", "required": false, "schema": { "type": "number", "minimum": 2, "maximum": 9 } }, { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet organization, will be used to look up locations available for this fleet. If fleet id is not provided, the locations available to the EMP will be provided", "required": false, "schema": { "type": "string" } }, { "name": "language", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "in": "query", "required": false, "example": "en", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseResponseListLocation" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "aggregates": [ { "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "count": 1 } ] } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/locations/{locationId}": { "get": { "tags": [ "EMP Geosearch" ], "summary": "Get location by id", "description": "Returns detailed location data for a single charging location, with optional pricing context. Only one of keyIdentifier or fleetId can be provided in a single request. If none are provided, default prices are returned.", "operationId": "getEmpLocationById", "parameters": [ { "name": "locationId", "in": "path", "description": "Location id.", "required": true, "schema": { "type": "string" } }, { "name": "keyIdentifier", "in": "query", "description": "The keyIdentifier of a charging key, will be used to look up specific prices for this charging key.", "required": false, "schema": { "type": "string" } }, { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet organization, will be used for fleet-specific location context. If fleet id is not provided, the EMP location context will be used", "required": false, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Supported languages: en, bg, cy, de, es, fi, fr, hu, is, it, lt, nb, nl, pl, pt, ro, sv.", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "en" } ], "responses": { "200": { "description": "Location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" }, "example": { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U=", "standard": "Type2", "power": 22000, "power_type": "AC_3_PHASE", "price": { "id": "4370769f30bd7927", "description": "€ 0.56/kWh, € 0.10/min (> 2 h)", "currency": "EUR", "priceIncludesVat": "true", "vatRate": "22", "elements": [ {} ] }, "max_amperage": 32, "max_voltage": 400 } ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } } } }, "404": { "description": "Location not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/locations/{locationId}/live-data": { "get": { "tags": [ "EMP Geosearch" ], "summary": "Get location live data", "operationId": "getEmpLocationLiveData", "description": "Returns live charging data for the EVSEs of a location that are in use, including since when each EVSE has had its current live status. The `charge_point_statuses` keys match the EVSE `uid` values returned by Get location by id. EVSEs without live data are omitted. Returns `404` when the location is not found or live data is not enabled for your organization. For details, check https://developer.plugsurfing.com/docs/geosearch#location-live-data", "parameters": [ { "name": "locationId", "in": "path", "description": "Location id.", "required": true, "schema": { "type": "string" } }, { "name": "fleetId", "in": "query", "description": "Optional - the id of the fleet organization, will be used for fleet-specific location context. If fleet id is not provided, the EMP location context will be used", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Live data of the location EVSEs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationLiveData" }, "example": { "charge_point_statuses": { "ee006b89511e81534e019ca0d9a780b351e9": { "status": "CHARGING", "status_since": "2025-01-15T08:12:00Z" } } } } } }, "404": { "description": "Location not found or live data not enabled for your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Internal server error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/locations/batch": { "get": { "tags": [ "EMP Geosearch" ], "summary": "Get batch of locations", "description": "Returns a paginated batch of charging locations for EMP integrations using cursor-based pagination.", "operationId": "getEmpLocationsBatch", "parameters": [ { "name": "page_size", "in": "query", "description": "Optional - used to set page size value", "required": false, "schema": { "type": "number", "minimum": 10, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Optional - pass cursor from previous response body to get next page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchLocationsResponse" }, "example": { "locations": [ { "id": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=", "name": "Ebee Smart Technologies", "coordinates": { "latitude": "52.475911", "longitude": "13.350794" }, "evses": [ { "uid": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE", "evse_id": "+49*839*030*000074", "physical_reference": "4", "status": "AVAILABLE", "connectors": [ {} ], "capabilities": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ], "last_updated": "2025-01-15T10:30:00Z" } ], "operator": { "id": "881941", "name": "Ebee Smart Technologies", "hotline": "+498944255071", "external_id": "DE*ABC" }, "operator_display_name": "Sub-operator X", "opening_times": { "twentyfourseven": false, "regular_hours": [ { "weekday": 1, "period_begin": "00:10", "period_end": "29:59" } ], "exceptional_openings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ], "exceptional_closings": [ { "period_begin": "2025-01-15T10:30:00Z", "period_end": "2025-01-15T10:30:00Z" } ] }, "directions": [ { "language": "DE", "text": "example" } ], "country": "DEU", "state": "Bayern", "city": "Berlin", "postal_code": 10829, "address": "EUREF CAMPUS 4-5", "openNow": false, "is_green_energy": false, "last_updated": "2024-03-15T14:30:00Z" } ], "cursor": "string" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/orders": { "get": { "summary": "Fetch charging key orders", "description": "Returns a list of charging key orders belonging to supported organizations.", "operationId": "listEmpChargingKeyOrders", "tags": [ "EMP Orders" ], "parameters": [ { "name": "fromDate", "in": "query", "description": "Created orders from date", "schema": { "type": "string", "format": "date", "pattern": "YYYY-MM-DD" } }, { "name": "toDate", "in": "query", "description": "Created orders to date", "schema": { "type": "string", "format": "date", "pattern": "YYYY-MM-DD" } }, { "name": "status", "in": "query", "description": "Order status", "schema": { "$ref": "#/components/schemas/ChargingKeyOrderStatus" } }, { "name": "pageSize", "in": "query", "description": "Orders per page", "schema": { "type": "integer", "example": 100 } }, { "name": "cursor", "in": "query", "description": "Cursor for pagination", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyOrdersResponse" }, "example": { "products": [ { "id": "aYnky297eG", "address": { "country": "Austria", "additionalInformation": "test test", "firstName": "Frans", "lastName": "Anderson", "city": "Wistful Vista", "postalCode": "85960", "companyName": "Low area Corp.", "addressLine1": "First Way 261b", "addressLine2": "Suite 9" }, "quantity": 1, "language": "en", "product": { "id": "Am07b6Q7JZ" }, "created": "2023-06-26T10:00:00Z", "organizationId": "JoEl1xoP7r", "status": "ORDER_PAID", "updated": "2023-06-26T12:00:00Z", "printing": { "variables": { "driverName": "Frans Anderson" }, "color": "WHITE" } } ], "cursor": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAACz-bFmYwRDVpbkhzUzNxaXMxU3JZV0dFNGcAAAAAAAs" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Create a fleet charging key order", "description": "Creates a charging key order for a fleet organization. One request creates one card order. The `printing` payload requirements come from product discovery and are validated by the fulfilment system.", "operationId": "createEmpChargingKeyOrder", "tags": [ "EMP Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpCreateChargingKeyOrderRequest" }, "example": { "fleetId": "fleet-123", "productId": "Nk375yz7Gw", "address": { "firstName": "Jane", "lastName": "Doe", "addressLine1": "Example Street 1", "addressLine2": "Floor 2", "postalCode": "00100", "city": "Helsinki", "country": "FI", "companyName": "Example Ltd" }, "printing": { "driverName": "Jane Doe", "licensePlate": "FI000AA" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyOrdersProduct" }, "example": { "id": "aYnky297eG", "address": { "country": "FI", "firstName": "Jane", "lastName": "Doe", "city": "Helsinki", "postalCode": "00100", "companyName": "Example Ltd", "addressLine1": "Example Street 1", "addressLine2": "Floor 2" }, "quantity": 1, "language": "en", "product": { "id": "Nk375yz7Gw" }, "created": "2024-01-15T10:00:00Z", "organizationId": "JoEl1xoP7r", "status": "ORDER_PAID", "updated": "2024-01-15T10:00:00Z", "printing": { "variables": { "driverName": "Jane Doe", "licensePlate": "FI000AA" } } } } } }, "400": { "description": "Bad Request. Returned when required fields are missing, the request body is malformed JSON, or the printing payload fails product validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Missing required field: productId" } } } }, "404": { "description": "Not Found. Returned when the fleetId does not exist or the productId is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/orders/{orderId}/assign": { "post": { "summary": "Mark an order as 'Assigned'", "description": "Marks an order as assigned. The request body is optional. Some orders require physical card details during assignment; for those orders, `keyIdentifier` and `referenceId` must be provided in the request body.", "operationId": "assignEmpChargingKeyOrder", "tags": [ "EMP Orders" ], "parameters": [ { "name": "orderId", "in": "path", "description": "orderId to be assigned", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyOrdersProduct" }, "example": { "id": "aYnky297eG", "address": { "country": "Austria", "additionalInformation": "test test", "firstName": "Frans", "lastName": "Anderson", "city": "Wistful Vista", "postalCode": "85960", "companyName": "Low area Corp.", "addressLine1": "First Way 261b", "addressLine2": "Suite 9" }, "quantity": 1, "language": "en", "product": { "id": "Am07b6Q7JZ" }, "created": "2023-06-26T10:00:00Z", "organizationId": "JoEl1xoP7r", "status": "ORDER_PAID", "updated": "2023-06-26T12:00:00Z" } } } }, "400": { "description": "Bad Request. Returned when required card details are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Missing or invalid card details." } } } }, "404": { "description": "Order is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict. Returned when the provided card details conflict with an existing card assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Card details conflict with an existing assignment." } } } }, "500": { "description": "Internal Server Error. Returned for unexpected failures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpChargingKeyOrderAssignRequest" }, "example": { "keyIdentifier": "0462D53C8ABAC0", "referenceId": "1234567890123456" } } } } } }, "/emp/v1/products": { "get": { "summary": "List available products", "description": "Returns the products available. Each product may include a `printing.schema` field - a JSON Schema (Draft 2020-12) object that describes the printing payload your customers must supply when placing an order for that product. Use this schema to build dynamic forms, validate inputs client-side, or auto-generate UI components.", "operationId": "getEmpProducts", "tags": [ "EMP Orders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpProductsResponse" }, "example": { "products": [ { "id": "Am07b6Q7JZ", "name": "Standard EV Card", "description": "Physical charging card for fleet drivers.", "printing": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "driverName", "licensePlate" ], "additionalProperties": false, "properties": { "driverName": { "type": "string", "description": "Full name of the card holder to be printed on the card.", "minLength": 5, "maxLength": 50 }, "licensePlate": { "type": "string", "description": "Vehicle license plate to be printed on the card.", "minLength": 4, "maxLength": 6 } } } } }, { "id": "Bx19dR2mKL", "name": "Fleet Access Card", "description": "Charging card for shared fleet access." } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred." } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/payment-options/stripe/publishable-api-key": { "get": { "summary": "Get Stripe publishable API key", "description": "Returns the Stripe publishable API key to be used with your Stripe client-side code, when confirming `SetupIntent` or creating a `PaymentMethod`.", "tags": [ "Payment Options" ], "operationId": "getStripePublishableApiKey", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePublishableApiKeyResponse" }, "example": { "stripePublishableApiKey": "pk_test_F6rIsWTYKDnk2YQcGzw4foMvSVqwPqP7e7oZkgqSipPUNfio7aSei2fv2UMq8uaCS3ULDAn8djODcruhLVYXCPab6yczpPa9" } } } }, "404": { "description": "Publishable API key is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/sessions/start": { "post": { "tags": [ "EMP Sessions" ], "summary": "Start a remote session", "operationId": "startRemoteSessionEmp", "description": "Starts a remote charging session with the given charging key on the given connector.\n\nIf a user has `CREDIT_CARD` payment method, and 3DS challenge mode is set to `CHALLENGE`, then `threeDSClientSecret` might be present instead of `sessionId`, which your frontend needs to prompt the user to sign. After the user successfully signs the challenge, do a second start request!", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpSessionStartRequest" }, "example": { "connectorId": "aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==", "keyIdentifier": "BnZd3qp87z" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartResponse" }, "example": { "sessionId": "AAdmD55q8Vz", "threeDSClientSecret": "pi_3MtwBwLkdIwHu8ix28v3tqPa_secret_YrKJUkribcBjcG7HVhfZluoGH" } } } }, "400": { "description": "The provided query parameters, route parameters or body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "403": { "description": "Forbidden. The charging key is not allowed to charge, or the connector won't allow remote charging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "Charging key or connector is not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/sessions/{sessionId}/stop": { "post": { "tags": [ "EMP Sessions" ], "summary": "Stop a remote session", "operationId": "stopRemoteSessionEmp", "description": "Stops the given remote charging session. Only sessions started remotely can be remotely stopped.", "parameters": [ { "name": "sessionId", "in": "path", "description": "session id", "example": "AAdmD55q8Vz", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/sessions/{sessionId}/receipt": { "get": { "tags": [ "EMP Sessions" ], "summary": "Get a session receipt by session id", "operationId": "getSessionReceiptEmp", "description": "Get session receipt. The response includes a time-limited URL to access the receipt. A new URL is required after expiration. Receipts are not available for sessions with a price of 0, and a 404 error will be returned if requested. The receipt will be in PDF format.", "parameters": [ { "name": "sessionId", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "url": "string" } } } }, "404": { "description": "Receipt not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/sessions/{sessionId}": { "get": { "tags": [ "EMP Sessions" ], "summary": "Get session by id", "operationId": "getSessionByIdEmp", "description": "Returns charging session details", "parameters": [ { "name": "sessionId", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "example": { "balanceStatus": "PROCESSING", "sessionStatus": "CREATED", "charger": { "chargingStationName": "Drive_API_Test1_Station1", "city": "Solna", "connectorLabel": "1", "evseId": "SE*CND*EC1*1", "streetName": "Rättarvägen" }, "balanceAmountMinor": "-2160", "chargingKeyType": "virtual", "connectorId": "O9UXK+YI5Q6i0FoI4qHwcA==", "duration": "PT28.913S", "energy": { "unit": "WH", "value": 57 }, "paymentMethod": "CREDIT_CARD", "price": { "currencyCode": "EUR", "minorExclVat": 2785, "minorInclVat": 1, "vat": "17.5" }, "receiptAvailable": true, "sessionId": "AAdmD55q8Vz", "site": "Drive_API_Test1", "startTime": "2021-01-30T10:00:00.111111111Z", "transactions": [ { "paymentMethod": "CREDIT_CARD", "paymentOutcome": "CHARGE", "amount": { "currencyCode": "EUR", "minorExclVat": 2785, "minorInclVat": 1, "vat": "17.5" }, "time": "2021-01-30T10:00:00.111111111Z" } ] } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/fleets": { "post": { "tags": [ "EMP Fleets" ], "summary": "Create a fleet", "description": "Creates a new fleet organization. The fleetId must be unique and is required. An optional fleetName can be provided to give the fleet a human-readable name.", "operationId": "createFleet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpFleetCreationRequest" }, "example": { "fleetId": "y1nNLJqb7m", "fleetName": "Fleet Inc." } } }, "required": true }, "responses": { "200": { "description": "Fleet created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpFleetCreationResponse" }, "example": { "fleetId": "y1nNLJqb7m", "fleetName": "Fleet Inc." } } } }, "400": { "description": "Invalid request (missing/invalid fleetId or fleetName)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "409": { "description": "Conflict - fleetId already exists with a different fleetName than the one provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/fleets/{fleetId}/rename": { "put": { "tags": [ "EMP Fleets" ], "summary": "Rename a fleet", "description": "Renames an existing fleet. The fleet must exist, the caller must have access to that fleet, and a valid non-empty newName must be provided in the request body.", "operationId": "renameFleet", "parameters": [ { "name": "fleetId", "in": "path", "description": "The unique identifier of the fleet to rename", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpFleetRenameRequest" }, "example": { "newName": "Fleet Inc" } } }, "required": true }, "responses": { "200": { "description": "Fleet renamed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpFleetCreationResponse" }, "example": { "fleetId": "y1nNLJqb7m", "fleetName": "Fleet Inc." } } } }, "400": { "description": "Invalid request (missing/invalid newName)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequestErrorResponse" }, "example": { "message": "Invalid request payload", "details": [ "field X is required" ] } } } }, "403": { "description": "Access denied (caller does not have access to the fleet organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "Fleet not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "409": { "description": "Conflict - the requested newName cannot be applied (for example, a fleet with that name already exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/emp/v1/fleets/{fleetId}/invitation": { "get": { "tags": [ "EMP Fleets" ], "summary": "Get fleet invitation codes", "description": "Retrieves all active invitation codes for a fleet. These codes allow users to join the fleet.", "operationId": "getFleetInvitationCodes", "parameters": [ { "name": "fleetId", "in": "path", "description": "The unique identifier of the fleet", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active invitation codes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmpFleetInvitationCodeResponse" }, "example": [ { "code": "string" } ] } } }, "403": { "description": "Access denied (caller doesn't have access to the organization)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "404": { "description": "Fleet not found or no active invitation codes available for this fleet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Resource not found" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "DriveApiChargingKeyWhitelistType": { "type": "string", "enum": [ "ALLOWED_OFFLINE", "NEVER" ], "description": "Defines when authorization of a charging key by the CPO is allowed.\nALLOWED_OFFLINE: CPO should use realtime authorization. But when the CPO cannot get a response from the eMSP, the CPO shall allow the charging key to be used.\nNEVER: Only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this charging key to the MSP." }, "ChargingKey": { "type": "object", "required": [ "keyId", "validFrom", "validTo", "type", "enabled", "created", "updated" ], "properties": { "keyId": { "type": "string", "example": "0eb7732d-eb7a-418c", "description": "Identifier used for this charging key (`uid` in the case of a physical charging key)" }, "referenceId": { "type": "string", "example": "DE*8PS*AD21B1*3", "description": "Visual number for RFID and virtual keys, Plug and Charge identifier (PCID )for plug_and_charge keys" }, "contractId": { "type": "string", "example": "DE-8PS-C0AD21B13-Q", "description": "Identifier used in the context of roaming" }, "name": { "type": "string", "example": "My RFID key", "description": "Key name (usually set by end-users to name their keys when they have multiple ones)." }, "validFrom": { "type": "string", "format": "date-time", "example": "2022-01-24T11:25:54.210Z", "description": "UTC timestamp when the charging key becomes valid." }, "validTo": { "type": "string", "format": "date-time", "example": "2032-01-24T11:25:54.210Z", "description": "UTC timestamp when the charging key expires." }, "type": { "type": "string", "example": "card", "description": "Possible values include, but aren't limited to: 'tag', 'card', 'virtual', 'plug_and_charge'." }, "enabled": { "type": "boolean", "description": "Indicates if the key can start a session or not" }, "created": { "type": "string", "format": "date-time", "description": "UTC timestamp when the charging key was created." }, "updated": { "type": "string", "format": "date-time", "description": "UTC timestamp when the charging key was last updated." }, "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "NEVER" } }, "description": "Represents a charging key assigned to a user account." }, "ChargingKeyPostRequest": { "type": "object", "required": [ "keyIdentifier", "contractId", "visualNumber" ], "properties": { "name": { "type": "string", "example": "SE6F1K2C3", "description": "Name of the Charging key" }, "keyIdentifier": { "type": "string", "example": "e0e03336", "description": "Charging key identifier in hexadecimal, little-endian format with usually 8 or 14 characters." }, "contractId": { "type": "string", "example": "DE-9FS-C045DS363-E", "description": "Charging key contract id" }, "visualNumber": { "type": "string", "example": "DE-9FS-C045DS363-E", "description": "Identifier printed on the physical key" }, "enabled": { "type": "boolean", "example": true, "description": "Indicates if the new charging key should be enabled or disabled.", "default": true }, "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "NEVER" } }, "description": "Request payload to create a new charging key for a user." }, "ChargingKeyActivateRequest": { "type": "object", "properties": { "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "NEVER" } }, "description": "Optional request payload to activate a charging key." }, "ChargingKeyPatchRequest": { "title": "ChargingKeyPatchRequest", "type": "object", "properties": { "name": { "type": "string", "description": "Display name assigned to the charging key." }, "enabled": { "type": "boolean", "description": "Changing to the value that the key already has will result in OK response." }, "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "ALLOWED_OFFLINE" } }, "description": "Request payload to update mutable charging key attributes." }, "ChargingKeyOrderRequest": { "title": "ChargingKeyOrderRequest", "description": "This endpoint allows you to order a charging key for a specific user. To prevent duplicate orders, ordering charging keys for a single user is throttled to 1 order every 5 minutes. This is a safety measure to avoid accidental double-clicks on the order button, preventing the user from being charged twice. If the user exceeds this limit, a `429 - Too Many Requests` HTTP response will be returned.", "type": "object", "required": [ "address", "taxationCountry" ], "properties": { "address": { "$ref": "#/components/schemas/ChargingKeyOrderAddressRequest", "description": "Shipping address for the ordered charging key." }, "taxationCountry": { "type": "string", "maxLength": 2, "example": "SE", "description": "Two-letter taxation country code" }, "paymentOptionId": { "type": "string", "example": "STRIPE-6738556949187507", "description": "Stripe payment option id. If not passed, a default one is used." } }, "example": { "taxationCountry": "SE", "paymentOptionId": "STRIPE-6738556949187507", "address": { "addressLine1": "Test, don't send", "postalCode": "01-111", "city": "Test", "country": "PL", "firstName": "Will", "lastName": "Smith", "companyName": "Plugsurfing" } } }, "ChargingKeyOrderAddressRequest": { "title": "ChargingKeyOrderAddressRequest", "type": "object", "required": [ "addressLine1", "postalCode", "city", "country" ], "properties": { "companyName": { "type": "string", "maxLength": 130, "example": "Plugsurfing", "description": "Company name for business delivery addresses." }, "firstName": { "type": "string", "maxLength": 130, "example": "John", "description": "Recipient first name." }, "lastName": { "type": "string", "maxLength": 130, "example": "Drive", "description": "Recipient last name." }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Automation road 1", "description": "Primary street address line." }, "addressLine2": { "type": "string", "example": "Park spot 1", "description": "Secondary address line such as apartment or suite." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 10, "example": "EV1234", "description": "Postal or ZIP code." }, "city": { "type": "string", "minLength": 1, "maxLength": 50, "example": "Spark City", "description": "City name." }, "country": { "type": "string", "minLength": 1, "maxLength": 41, "example": "SE", "description": "Country code in ISO 3166-1 alpha-2 format." } }, "description": "Shipping address used when placing a charging key order." }, "ChargingKeyOrderResponse": { "title": "ChargingKeyOrderResponse", "type": "object", "required": [ "id", "state" ], "properties": { "id": { "type": "string", "example": "9aE20Rmj0v", "description": "Unique identifier of the created charging key order." }, "state": { "$ref": "#/components/schemas/OrderState", "description": "Current lifecycle state of the charging key order." }, "clientSecret": { "type": "string", "example": "pi_1J5J9v3sZvKYlo2C5J9v2eZv", "description": "If Stripe payment requires a 3DS authentication, this field will be populated with the clientSecret from Stripe, which should be sent back to client side Stripe SDK for user authentication." } }, "description": "Result returned after creating a charging key order." }, "ChargingKeyOrdersListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/ChargingKeyOrdersListItem" }, "description": "Response containing charging key orders for a user." }, "ChargingKeyConfigurationResponse": { "type": "object", "properties": { "countries": { "type": "array", "items": { "properties": { "country": { "type": "string", "example": "SE", "description": "The two-letter code of the country" }, "currency": { "type": "string", "example": "SEK", "description": "The three-letter currency code" }, "priceMinorInclVat": { "type": "integer", "format": "int32", "description": "Price in minor units (example: in Swedish Kronor, a value of 1010 means 10.10 SEK)" }, "vat": { "type": "integer", "format": "int32", "description": "VAT in percent (example: 25 means 25% VAT)" } } }, "description": "Countries where charging key ordering is supported." } }, "description": "Available configuration values for charging key ordering." }, "ChargingKeyOrdersListItem": { "type": "object", "required": [ "id", "created", "updated", "state", "quantity" ], "properties": { "id": { "type": "string", "example": "vrj82A9EpJ", "description": "Unique identifier of the order." }, "created": { "type": "string", "format": "date-time", "example": "2022-04-07T11:30:57.000Z", "description": "UTC timestamp when this order was created." }, "updated": { "type": "string", "format": "date-time", "example": "2022-04-07T11:30:57.000Z", "description": "UTC timestamp when this order was last updated." }, "address": { "$ref": "#/components/schemas/ChargingKeyAddress", "description": "Shipping address associated with this order." }, "quantity": { "type": "number", "example": 1, "description": "Number of charging keys included in the order." }, "currency": { "type": "string", "example": "SEK", "description": "3-letter currency code" }, "priceMinorInclVat": { "type": "integer", "format": "int32", "example": 1010, "description": "price in minor units (example value is 10.10 SEK)" }, "state": { "$ref": "#/components/schemas/OrderState", "description": "Current order state." }, "hasReceipt": { "type": "boolean", "example": false, "description": "Indicates whether a receipt is available for this order." } }, "description": "A single charging key order entry in a list response." }, "ChargingKeyAddress": { "type": "object", "properties": { "companyName": { "type": "string", "example": "Plusurfing", "description": "Company name for business delivery addresses." }, "firstName": { "type": "string", "example": "Luck", "description": "Recipient first name." }, "lastName": { "type": "string", "example": "Thomson", "description": "Recipient last name." }, "addressLine1": { "type": "string", "example": "Rättarvägen 3", "description": "Primary street address line." }, "addressLine2": { "type": "string", "example": "Rättarvägen 3", "description": "Secondary address line such as apartment or suite." }, "postalCode": { "type": "string", "example": 12345, "description": "Postal or ZIP code." }, "city": { "type": "string", "example": "Solna", "description": "City name." }, "country": { "type": "string", "example": "Sweden", "description": "Country code in ISO 3166-1 alpha-2 format." } }, "description": "Postal address associated with a charging key order." }, "OrderState": { "type": "string", "enum": [ "ORDER_FILLED", "ORDER_CANCELLED", "ORDER_PROCESSING", "ORDER_WAITING_3DS", "ORDER_PAYMENT_FAILED", "ORDER_REFUND_FAILED", "ORDER_REFUNDED", "ORDER_PLACED", "ORDER_PAID" ], "example": "ORDER_PLACED" }, "ChargingKeyReservationsRequest": { "type": "object", "required": [ "uid", "visualNumber" ], "properties": { "uid": { "type": "string", "example": "e0e03306", "description": "Physical chip id. Must be in hexadecimal, little endian format" }, "visualNumber": { "type": "string", "description": "Human-readable identifier written on the rfid card or tag", "example": "DE*8PS*FR1RFK*4" }, "validFrom": { "type": "string", "format": "date-time", "example": "2022-01-24T11:25:54.210Z", "description": "default - current date" }, "validTo": { "type": "string", "format": "date-time", "example": "2032-01-24T11:25:54.210Z", "description": "default - 10 years from 'validFrom' date" }, "type": { "type": "string", "enum": [ "CARD", "TAG" ], "default": "CARD", "description": "this value is just for reference, it has no practical implications", "example": "CARD" } }, "description": "Request payload to reserve charging key identifiers before activation." }, "ChargingKeyOrderReceiptResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL where the charging key order receipt can be downloaded." } }, "description": "Response containing the receipt URL for a charging key order." }, "ChargingKeyPlugAndChargePostRequest": { "title": "ChargingKeyPlugAndChargePostRequest", "type": "object", "required": [ "pcid" ], "properties": { "pcid": { "type": "string", "example": "VW123456789ABCDEFG", "description": "identifies the vehicle and must correspond to the provisioning certificate" }, "contractId": { "type": "string", "example": "DE-8PS-CT4UN7OZ3-2", "description": "Identifies the charging contract and is only accepted in EMA-ID format. Must correspond to the Plug and Charge contract certificate." } }, "description": "Request payload to register a plug-and-charge contract identifier." }, "ChargingKeyPlugAndChargePostResponse": { "type": "object", "required": [ "contractId", "pcid", "keyId" ], "properties": { "contractId": { "type": "string", "description": "in EMA-ID format, must correspond to the Plug&Charge contract certificate." }, "pcid": { "type": "string", "description": "Plug&Charge vehicle identifier (PCID). Is also used as referenceId of the charging key." }, "keyId": { "type": "string", "example": "DE-8PS-CT4UN7OZ3-2", "description": "Plug&Charge keys use the contractId (in EMA-ID format) as the keyIdentifier used for referencing in other endpoints" } }, "description": "Result payload after registering a Plug&Charge contract." }, "EmpChargingKeyPostRequest": { "type": "object", "required": [ "keyIdentifier", "contractId", "visualNumber" ], "properties": { "name": { "type": "string", "example": "SE6F1K2C3", "description": "Name of the Charging key" }, "keyIdentifier": { "type": "string", "example": "e0e03336", "description": "Charging key identifier in hexadecimal, little-endian format with usually 8 or 14 characters." }, "fleetId": { "type": "string", "example": "y1nNLJqb7m", "description": "Fleet id" }, "fleetName": { "type": "string", "example": "Fleet Inc.", "description": "The name associated to the fleetId" }, "contractId": { "type": "string", "example": "DE-9FS-C045DS363-E", "description": "Charging key contract id" }, "visualNumber": { "type": "string", "example": "DE-9FS-C045DS363-E", "description": "Identifier printed on the physical key" }, "enabled": { "type": "boolean", "example": true, "description": "Indicates if the new charging key should be enabled or disabled.", "default": true }, "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "NEVER" } }, "example": { "name": "SE6F1K2C3", "keyIdentifier": "e0e03336", "contractId": "DE-9FS-C045DS363-E", "visualNumber": "DE-9FS-C045DS363-E", "enabled": true, "whitelist": "NEVER" }, "description": "Request payload to create an EMP charging key." }, "EmpChargingKeyRenameRequest": { "type": "object", "required": [ "newName" ], "properties": { "newName": { "type": "string", "example": "SE6F1K2C3", "description": "New name of the Charging key" } }, "description": "Request payload to rename an EMP charging key." }, "EmpChargingKeyResponse": { "properties": { "name": { "type": "string", "example": "SE6F1K2C3", "description": "Name of the Charging key" }, "keyIdentifier": { "type": "string", "example": "3633e0e0", "description": "Charging key identifier in hexadecimal, little-endian format with usually 8 or 14 characters." }, "validTo": { "type": "string", "format": "date-time", "example": "2022-01-24T11:25:54.210Z", "description": "UTC timestamp when the charging key expires." }, "fleetId": { "type": "string", "example": "y1nNLJqb7m", "description": "Fleet id" }, "contractId": { "type": "string", "example": "DE-9FS-C045DS363-E", "description": "Charging key contract id" }, "visualNumber": { "type": "string", "example": "6285629402937", "description": "Identifier printed on the physical key" }, "enabled": { "type": "boolean", "example": true, "description": "Charging key is enabled or disabled" }, "whitelist": { "$ref": "#/components/schemas/DriveApiChargingKeyWhitelistType", "description": "Defines whether the CPO may allow a session for this charging key when it cannot get a response from the EMP, or must always rely on realtime authorization from the EMP. Possible values: ALLOWED_OFFLINE, NEVER.", "example": "NEVER" } }, "description": "EMP charging key details returned by key management endpoints." }, "EmpCreateChargingKeyOrderRequest": { "type": "object", "required": [ "fleetId", "productId", "address" ], "properties": { "fleetId": { "type": "string", "example": "fleet-123", "description": "Customer-provided fleet identifier. Must match the value used when the fleet was created via `POST /emp/v1/fleets`." }, "productId": { "type": "string", "example": "Nk375yz7Gw", "description": "Encoded public product ID as returned by `GET /emp/v1/products`." }, "address": { "$ref": "#/components/schemas/ChargingKeyOrderAddressRequest", "description": "Delivery address for the order." }, "printing": { "type": "object", "additionalProperties": true, "description": "Optional printing payload. Requirements are product-specific — use the `printing.schema` from product discovery to build and validate this object before submitting. Drive API forwards this payload unchanged to the fulfilment system.", "example": { "driverName": "Jane Doe", "licensePlate": "FI000AA" } } }, "description": "Request body for creating a fleet charging key order." }, "EmpChargingKeyOrdersProductAddress": { "type": "object", "properties": { "country": { "type": "string", "example": "Austria", "description": "Country code in ISO 3166-1 alpha-2 format." }, "additionalInformation": { "type": "string", "example": "test test", "description": "Additional delivery instructions." }, "firstName": { "type": "string", "example": "Frans", "description": "Recipient first name." }, "lastName": { "type": "string", "example": "Anderson", "description": "Recipient last name." }, "city": { "type": "string", "example": "Wistful Vista", "description": "City name." }, "postalCode": { "type": "string", "example": "85960", "description": "Postal or ZIP code." }, "companyName": { "type": "string", "example": "Low area Corp.", "description": "Company name for business delivery addresses." }, "addressLine1": { "type": "string", "example": "First Way 261b", "description": "Primary street address line." }, "addressLine2": { "type": "string", "example": "Suite 9", "description": "Secondary address line such as apartment or suite." } }, "description": "Delivery address for an EMP charging key order product." }, "EmpChargingKeyOrdersProduct": { "required": [ "id", "address", "quantity", "language", "product", "created", "organizationId", "status", "updated" ], "type": "object", "properties": { "id": { "type": "string", "example": "aYnky297eG", "description": "Unique identifier of the order product." }, "address": { "$ref": "#/components/schemas/EmpChargingKeyOrdersProductAddress", "description": "Delivery address for this order product." }, "quantity": { "type": "number", "example": 1, "description": "Number of product units ordered." }, "language": { "type": "string", "example": "en", "description": "Language used for order communication." }, "product": { "type": "object", "properties": { "id": { "type": "string", "example": "Am07b6Q7JZ" } }, "description": "Ordered product code or type." }, "created": { "type": "string", "format": "date-time", "example": "2023-06-26T10:00:00Z", "description": "UTC timestamp when this product order was created." }, "organizationId": { "type": "string", "example": "JoEl1xoP7r", "description": "Identifier of the organization that placed the order." }, "status": { "$ref": "#/components/schemas/ChargingKeyOrderStatus", "description": "Current processing status of the order product." }, "updated": { "type": "string", "format": "date-time", "example": "2023-06-26T12:00:00Z", "description": "UTC timestamp when this product order was last updated." }, "printing": { "type": "object", "description": "Printing details associated with the order product. Present only for orders that include physical card customization.", "required": [ "variables" ], "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Print-specific values associated with the order, for example values used on a customized physical card." }, "color": { "type": [ "string", "null" ], "enum": [ "BLACK", "WHITE", null ], "description": "Card template color agreed for the product/order. It is not selected by the end customer while placing the order." } } } }, "description": "EMP charging key order product details." }, "EmpChargingKeyOrdersResponse": { "required": [ "products" ], "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/EmpChargingKeyOrdersProduct" }, "description": "Products returned for the current page." }, "cursor": { "type": "string", "example": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAACz-bFmYwRDVpbkhzUzNxaXMxU3JZV0dFNGcAAAAAAAs", "description": "Cursor to request the next page of results." } }, "description": "Paginated list of EMP charging key order products." }, "ChargingKeyOrderStatus": { "type": "string", "description": "ORDER_PAID -> orders ready to be fulfilled", "enum": [ "WAITING_FOR_ORDER", "ORDER_PLACED", "ORDER_PROCESSING", "ORDER_ASSIGNED", "ORDER_PAID", "ORDER_CANCELLED", "ORDER_CANCELLING", "ORDER_PAYMENT_FAILED", "ORDER_REFUND_FAILED", "ORDER_WAITING_REFUND", "ORDER_REFUNDED", "PAYMENT_ONGOING", "ORDER_FILLED", "ORDER_PAYED", "PREPARE_RECEIPT", "ORDER_PAYED_WITHOUT_RECEIPT" ], "example": "ORDER_PAID" }, "EmpSessionStartRequest": { "required": [ "connectorId", "keyIdentifier" ], "type": "object", "properties": { "connectorId": { "type": "string", "example": "aHeS4zN1UjzJf/HVDH66SbaItXqHvfLxexulktxTqJavgcbozuV9KJGqNYjmaQPwTb4Ck9wTZcWeEdfeco1srw==", "description": "Connector identifier to start charging on." }, "keyIdentifier": { "type": "string", "example": "BnZd3qp87z", "description": "Charging key identifier used for authorization." } }, "description": "EMP session start request identifying connector and charging key." }, "EmpFleetCreationRequest": { "required": [ "fleetId" ], "type": "object", "properties": { "fleetId": { "type": "string", "example": "y1nNLJqb7m", "maxLength": 100 }, "fleetName": { "type": "string", "example": "Fleet Inc.", "maxLength": 100 } } }, "EmpFleetCreationResponse": { "required": [ "fleetId" ], "type": "object", "properties": { "fleetId": { "type": "string", "example": "y1nNLJqb7m" }, "fleetName": { "type": "string", "example": "Fleet Inc." } } }, "EmpFleetRenameRequest": { "type": "object", "required": [ "newName" ], "properties": { "newName": { "type": "string", "example": "Fleet Inc", "description": "New name of the fleet", "maxLength": 100 } } }, "EmpFleetInvitationCodeResponse": { "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The fleet invitation code" } } } }, "BaseResponseListLocation": { "type": "object", "required": [ "locations" ], "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" }, "description": "Locations matching the geosearch criteria." }, "aggregates": { "type": "array", "description": "Present only if 'aggregate' request param = true. Contains only aggregates of 2 or more locations. Single locations are returned in 'locations' array.", "items": { "$ref": "#/components/schemas/Aggregate" } } }, "description": "Response payload containing matching locations and aggregate metadata for a geosearch query." }, "BatchLocationsResponse": { "type": "object", "required": [ "locations" ], "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" }, "description": "Locations returned in the current page." }, "cursor": { "type": "string", "description": "The cursor pointing to the next page, when missing it means there are no more pages to fetch." } }, "description": "Paginated response containing a batch of charging locations." }, "Location": { "required": [ "id", "name", "coordinates", "address", "evses", "country", "city", "last_updated" ], "type": "object", "properties": { "id": { "minLength": 0, "type": "string", "example": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo=" }, "name": { "maxLength": 255, "minLength": 0, "type": "string", "description": "Human-readable name of the charging location", "example": "Ebee Smart Technologies" }, "coordinates": { "$ref": "#/components/schemas/Coordinates", "description": "Geographic coordinates of the charging location. These values are returned as strings." }, "evses": { "type": "array", "description": "List of Electric Vehicle Supply Equipment (EVSE) at this location. Each EVSE may have multiple connectors.", "items": { "$ref": "#/components/schemas/Evse" } }, "parking_type": { "description": "Parking type for the charging location.", "allOf": [ { "$ref": "#/components/schemas/ParkingType" } ] }, "operator": { "$ref": "#/components/schemas/BusinessDetails", "description": "Information about the Charging Point Operator (CPO) managing this location" }, "operator_display_name": { "description": "An enhanced display name of the operator. This may be the operator name as found in the operator object, or the sub-operator of the location. When showing the location to end users, this is the operator name that should be shown.", "type": "string", "example": "Sub-operator X" }, "opening_times": { "$ref": "#/components/schemas/OpeningTimes", "description": "Operating hours of the charging location" }, "directions": { "type": "array", "description": "Navigation instructions to help locate the charging points, available in multiple languages", "items": { "$ref": "#/components/schemas/DisplayText" } }, "country": { "maxLength": 3, "minLength": 3, "description": "Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated", "type": "string", "example": "DEU" }, "state": { "description": "State, region, or province where the charging location is situated. Format varies by country.", "type": "string", "example": "Bayern" }, "city": { "type": "string", "description": "City where the charging location is situated", "example": "Berlin" }, "postal_code": { "type": "string", "description": "Postal code of the charging location", "example": 10829 }, "address": { "type": "string", "description": "Street address of the charging location", "example": "EUREF CAMPUS 4-5" }, "openNow": { "type": "boolean", "description": "Indicates if the location is currently open based on opening_hours and local timezone. Use this for quick filtering of available locations.", "example": false }, "is_green_energy": { "type": "boolean", "description": "Indicates if the location uses renewable energy sources for charging, based on CPO-provided data", "example": false }, "last_updated": { "type": "string", "description": "ISO 8601 timestamp of when this location's data was last updated. Use this to track changes and implement efficient polling.", "example": "2024-03-15T14:30:00Z" } } }, "Coordinates": { "type": "object", "description": "Latitude and longitude values serialized as strings with fixed decimal precision. This schema is used in response payloads and in route-search points.", "properties": { "latitude": { "pattern": "-?[0-9]{1,2}\\.[0-9]{6}", "type": "string", "description": "Latitude serialized as a string, for example `52.475911`.", "example": "52.475911" }, "longitude": { "pattern": "-?[0-9]{1,3}\\.[0-9]{6}", "type": "string", "description": "Longitude serialized as a string, for example `13.350794`.", "example": "13.350794" } } }, "Evse": { "required": [ "uid", "status", "connectors", "capabilities", "last_updated" ], "type": "object", "description": "Electric Vehicle Supply Equipment (EVSE) represents a charging station unit that may have multiple connectors. Only one connector can be active at a time.", "properties": { "uid": { "minLength": 0, "type": "string", "example": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE" }, "evse_id": { "minLength": 1, "type": "string", "example": "+49*839*030*000074" }, "physical_reference": { "type": "string", "description": "The 'physical reference' is used by some CPOs to represent the label printed on the charging station itself. For example, in a charging location, the physical references could be '1', '2', '3', '4', for the four different charging stations", "example": "4" }, "status": { "$ref": "#/components/schemas/ConnectorStatus" }, "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } }, "capabilities": { "type": "array", "description": "Values: `PLUG_AND_CHARGE_CAPABLE`, `REMOTE_START_STOP_CAPABLE`. New values in this array might be added without notice, so unknown values should be handled gracefully.", "items": { "type": "string" }, "example": [ "RESERVABLE", "PLUG_AND_CHARGE_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ] }, "parking_restrictions": { "type": "array", "description": "Parking restrictions for this EVSE.", "items": { "$ref": "#/components/schemas/ParkingRestriction" }, "example": [ "EV_ONLY", "CUSTOMERS" ] }, "last_updated": { "type": "string", "format": "date-time", "description": "Time the EVSE data was last updated by the operator. Any EVSE data update changes it, so it does not show when the current `status` started. Use `status_since` from Get location live data for charging timing." } } }, "LocationLiveData": { "required": [ "charge_point_statuses" ], "type": "object", "description": "Live charging data of the EVSEs of a location.", "properties": { "charge_point_statuses": { "type": "object", "description": "Live data by EVSE `uid`. The keys match the EVSE `uid` values returned by Get location by id. Contains only EVSEs that are in use and have a known live status start time. Empty when no live data is available.", "additionalProperties": { "$ref": "#/components/schemas/ChargePointLiveData" } } } }, "ChargePointLiveData": { "required": [ "status", "status_since" ], "type": "object", "description": "Live status of an EVSE, tracked by Plugsurfing from the charger status updates.", "properties": { "status": { "type": "string", "enum": [ "CHARGING", "OCCUPIED", "RESERVED" ], "description": "Live status of the EVSE. It is tracked separately from the EVSE `status` returned by Get location by id, so the two can differ." }, "status_since": { "type": "string", "format": "date-time", "description": "Time since which Plugsurfing has continuously tracked the live `status` of the EVSE. For `CHARGING`, it is the start of the current charging occupation. It is based on status updates, so it can differ from the actual session start. It is not the EVSE `last_updated`.", "example": "2025-01-15T08:12:00Z" } } }, "Connector": { "required": [ "id", "standard", "power_type" ], "type": "object", "properties": { "id": { "minLength": 0, "type": "string", "description": "Unique identifier for this connector. Use this ID when starting charging sessions.", "example": "8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U=" }, "standard": { "$ref": "#/components/schemas/ConnectorStandard", "description": "Physical connector type/standard (e.g., Type2, Combo, CHADEMO). Use `Combo` for CCS connectors." }, "power": { "type": "integer", "description": "Maximum power output in Watts. For AC chargers, this is typically between 3.7kW and 43kW. For DC chargers, typically between 50kW and 350kW.", "example": 22000 }, "power_type": { "type": "string", "enum": [ "AC_1_PHASE", "AC_3_PHASE", "DC", "AC" ], "example": "AC_3_PHASE" }, "price": { "description": "Pricing information for this connector. Only available when retrieving a specific location.", "type": "object", "properties": { "id": { "type": "string", "example": "4370769f30bd7927" }, "description": { "type": "string", "example": "€ 0.56/kWh, € 0.10/min (> 2 h)", "description": "Human-readable description of the pricing structure" }, "currency": { "type": "string", "description": "Three-letter currency code ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format)", "example": "EUR" }, "priceIncludesVat": { "type": "boolean", "description": "Indicates whether the price includes VAT or not (same meaning as for the CDR object)", "example": "true" }, "vatRate": { "type": "string", "description": "The VAT rate that is applied to the price (in case priceIncludesVat=true) or the VAT rate that should be applied to the price (in case priceIncludesVat=false)", "example": "22" }, "elements": { "type": "array", "description": "Possible prices for that connector, depending on restrictions", "items": { "$ref": "#/components/schemas/PriceElement" } } } }, "max_amperage": { "description": "Maximum current in Amperes that this connector can provide", "type": "number", "example": 32 }, "max_voltage": { "description": "Maximum voltage in Volts that this connector can provide", "type": "number", "example": 400 } } }, "BusinessDetails": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "example": "881941" }, "name": { "maxLength": 100, "minLength": 0, "type": "string", "example": "Ebee Smart Technologies" }, "hotline": { "type": "string", "example": "+498944255071" }, "external_id": { "type": "string", "example": "DE*ABC" } } }, "OpeningTimes": { "required": [ "twentyfourseven" ], "type": "object", "properties": { "twentyfourseven": { "type": "boolean", "example": false }, "regular_hours": { "type": "array", "items": { "$ref": "#/components/schemas/RegularHours" } }, "exceptional_openings": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionalPeriod" } }, "exceptional_closings": { "type": "array", "items": { "$ref": "#/components/schemas/ExceptionalPeriod" } } } }, "RegularHours": { "description": "Only to be used if twentyfourseven = false", "required": [ "weekday", "period_begin", "period_end" ], "properties": { "weekday": { "type": "integer", "description": "Number of day in the week, from Monday (1) till Sunday (7)", "example": 1 }, "period_begin": { "type": "string", "format": "([0-1][0-9]|2[0-3]):[0-5][0-9]", "example": "00:10" }, "period_end": { "type": "string", "format": "([0-1][0-9]|2[0-3]):[0-5][0-9]", "example": "29:59" } } }, "ExceptionalPeriod": { "required": [ "period_begin", "period_end" ], "properties": { "period_begin": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" } } }, "DisplayText": { "type": "object", "required": [ "language", "text" ], "properties": { "language": { "type": "string", "maxLength": 2, "minLength": 2, "example": "DE" }, "text": { "type": "string", "maxLength": 512, "example": "example" } } }, "ConnectorStandard": { "type": "string", "description": "Connector standard accepted by the API. Use `Combo` for CCS connectors. `CHADEMO` is the preferred token; `Chademo` is a legacy alias.", "enum": [ "3PinSquare", "Cee2Poles", "CeeBlue", "CeePlus", "CeeRed", "Combo", "Marechal", "Nema5", "Scame", "CHADEMO", "Chademo", "Type1", "Type2", "Type3", "TypeE", "Schuko", "UNKNOWN", "T23", "T13", "T15", "Tesla", "DOMESTIC_A", "DOMESTIC_B", "DOMESTIC_C", "DOMESTIC_D", "DOMESTIC_E", "DOMESTIC_F", "DOMESTIC_G", "DOMESTIC_H", "DOMESTIC_I", "DOMESTIC_J", "DOMESTIC_K", "DOMESTIC_L", "IEC_60309_2_single_16", "IEC_60309_2_three_16", "IEC_60309_2_three_32", "IEC_60309_2_three_64", "IEC_62196_T1", "IEC_62196_T1_COMBO", "IEC_62196_T2", "IEC_62196_T2_COMBO", "IEC_62196_T3A", "IEC_62196_T3C", "TESLA_R", "TESLA_S" ], "example": "Type2" }, "ConnectorStatus": { "type": "string", "enum": [ "AVAILABLE", "CHARGING", "BLOCKED", "INOPERATIVE", "OCCUPIED", "OFFLINE", "OUTOFORDER", "PLANNED", "REMOVED", "RESERVED", "UNKNOWN", "UNAVAILABLE" ], "example": "AVAILABLE" }, "ParkingType": { "type": "string", "enum": [ "ALONG_MOTORWAY", "PARKING_GARAGE", "PARKING_LOT", "ON_DRIVEWAY", "ON_STREET", "UNDERGROUND_GARAGE" ], "example": "PARKING_LOT" }, "ParkingRestriction": { "type": "string", "enum": [ "EV_ONLY", "PLUGGED", "DISABLED", "CUSTOMERS", "MOTORCYCLES" ], "example": "EV_ONLY" }, "Capabilities": { "type": "string", "enum": [ "REMOTE_START_STOP_CAPABLE", "PLUG_AND_CHARGE_CAPABLE" ] }, "Aggregate": { "type": "object", "required": [ "coordinates", "count" ], "properties": { "coordinates": { "$ref": "#/components/schemas/Coordinates", "description": "Aggregate center coordinates returned as strings." }, "count": { "type": "integer", "description": "Number of locations around this point.", "minimum": 2 } } }, "RadiusRequest": { "type": "object", "example": { "filters": { "locationStatuses": [ "AVAILABLE", "CHARGING", "OCCUPIED", "RESERVED", "UNKNOWN", "OUTOFORDER" ], "powerType": "AC" } }, "properties": { "filters": { "$ref": "#/components/schemas/GeoFilters", "description": "Filtering criteria for location selection." } }, "description": "Geosearch request centered on a point with radius-based criteria. The body is optional filter data only; use `{}` for a search without filters." }, "RectangleRequest": { "type": "object", "example": { "filters": { "locationStatuses": [ "AVAILABLE", "CHARGING", "OCCUPIED", "RESERVED", "UNKNOWN", "OUTOFORDER" ], "powerType": "AC" } }, "properties": { "filters": { "$ref": "#/components/schemas/GeoFilters", "description": "Filtering criteria for location selection." } }, "description": "Geosearch request constrained to a rectangular area." }, "AlongRouteRequest": { "type": "object", "description": "The request takes up to 300 points for the route", "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinates" }, "description": "Ordered route points (latitude/longitude) used to search along the route. The latitude and longitude values are string fields in this request body." }, "filters": { "$ref": "#/components/schemas/GeoFilters", "description": "Filtering criteria applied to candidate charging locations." } }, "example": { "points": [ { "latitude": "52.331142", "longitude": "13.145221" }, { "latitude": "53.331142", "longitude": "14.145221" } ], "filters": { "locationStatuses": [ "AVAILABLE", "CHARGING", "OCCUPIED", "RESERVED", "UNKNOWN", "OUTOFORDER" ], "connectorStandards": [ "Type2" ] } } }, "GeoFilters": { "type": "object", "properties": { "connectorStandards": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorStandard" }, "description": "Accepted connector standards." }, "locationStatuses": { "type": "array", "example": [ "AVAILABLE", "CHARGING", "OCCUPIED", "RESERVED", "UNKNOWN", "OUTOFORDER" ], "items": { "$ref": "#/components/schemas/ConnectorStatus" }, "description": "Only return locations whose status is included in this list. A common default is `[AVAILABLE, CHARGING, OCCUPIED, RESERVED, UNKNOWN, OUTOFORDER]`, which excludes statuses such as `BLOCKED`, `INOPERATIVE`, `OFFLINE`, and `REMOVED`." }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capabilities" }, "description": "Required EVSE capabilities." }, "power": { "type": "integer", "example": 30000, "description": "Minimum power in W" }, "powerType": { "type": "string", "enum": [ "AC", "DC" ], "description": "AC filter will contain both AC 1-phase and 3-phase." }, "operatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Get stations only from these operators. (When provided, excludedOperatorIds will be ignored.)" }, "excludedOperatorIds": { "type": "array", "items": { "type": "integer" }, "description": "Exclude stations from these operators. (This parameter will be ignored when operatorIds are provided.)" }, "open247": { "type": "boolean", "description": "Return only stations open 24/7." }, "openNow": { "type": "boolean", "description": "Returns only stations now opened (based on data provided by CPOs). This parameter is not supported with aggregations." }, "evseIds": { "type": "array", "items": { "type": "string" }, "example": [ "+49*839", "*075*000075" ], "description": "Return only stations with evses id match a pattern" }, "countries": { "type": "array", "items": { "type": "string", "example": [ "NOR", "SWE", "DEU" ] }, "description": "Array of 3-letter country codes" } }, "description": "Filtering criteria applied to geosearch requests." }, "PriceComponent": { "type": "object", "description": "Defines a single component of a charging price. A price can have multiple components (e.g., energy cost + time cost).", "properties": { "price": { "type": "number", "example": 0, "description": "Cost in the currency stated above. VAT is included. Decimal number. For example, if currency is EUR and price is 1.10, the cost is €1.10. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation" }, "type": { "type": "string", "example": "FLAT", "description": "More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation", "enum": [ "TIME", "ENERGY", "FLAT", "CAPPED", "PARKING_TIME", "CONGESTION_TIME" ] }, "step_size": { "type": "number", "example": 1, "description": "The smallest unit of usage that will be billed. Unit: seconds for `TIME`, `PARKING_TIME`, and `CONGESTION_TIME`; watt-hours (Wh) for `ENERGY`; ignored for `FLAT` and `CAPPED`. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation" } } }, "PriceElement": { "type": "object", "required": [ "price_components" ], "description": "Defines a complete pricing structure that may apply under certain conditions. Multiple price elements may exist for different times or usage patterns.", "properties": { "price_components": { "type": "array", "description": "List of individual price components that make up this pricing structure", "items": { "$ref": "#/components/schemas/PriceComponent" } }, "restrictions": { "type": "object", "description": "Conditions under which this price element applies. Multiple restrictions can be combined.", "properties": { "start_time": { "type": "string", "example": "08:30", "description": "Time of day when this price starts applying (local time at the charging location)" }, "end_time": { "type": "string", "example": "22:30", "description": "Time of day when this price stops applying (local time at the charging location)" }, "day_of_week": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "description": "Days of the week when this price applies", "example": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY" ] }, "min_duration": { "type": "number", "example": 7200, "description": "Minimum charging duration in seconds before this price applies (e.g., 7200 means this price applies after 2 hours)" }, "max_duration": { "type": "number", "example": 10000, "description": "Maximum charging duration in seconds for this price to apply" }, "min_kwh": { "type": "number", "example": 2, "description": "Minimum energy consumption in kWh before this price applies" }, "max_kwh": { "type": "number", "example": 5, "description": "Maximum energy consumption in kWh for this price to apply" }, "min_vehicle_soc": { "type": "number", "example": 80, "description": "Minimum vehicle state of charge percentage for which this price element is valid" }, "max_vehicle_soc": { "type": "number", "example": 95, "description": "Maximum vehicle state of charge percentage for which this price element is valid" }, "min_congestion_threshold": { "type": "number", "example": 70, "description": "Minimum location utilization percentage for which this price element is valid" }, "max_congestion_threshold": { "type": "number", "example": 90, "description": "Maximum location utilization percentage for which this price element is valid" } } } } }, "OperatorsListResponse": { "type": "object", "required": [ "operators" ], "properties": { "operators": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } }, "cursor": { "type": "string", "description": "The cursor pointing to the next page. Omit when fetching the first page. When missing, it means there are no more pages to fetch.", "example": "H6Zb4Z8p+4/vhPl9JKVHM+9/XWoF02I4EIKblAd3nMk=" } } }, "Operator": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "description": "This operator id can be used in the 'operatorIds' geosearch filter", "type": "integer", "example": 1547830 }, "name": { "description": "User friendly operator name. Note: some operators can have multiple ids (for example, one per country).", "type": "string", "maxLength": 64 }, "externalId": { "description": "the operator's external id (e.g. \"DE*ABC\")", "type": "string", "maxLength": 64 } } }, "PaymentOption": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the stored payment option." }, "paymentMethod": { "type": "string", "example": "SOME_PAYMENT_METHOD_TYPE", "description": "Payment method provider/type." } }, "discriminator": { "propertyName": "paymentMethod", "mapping": { "CREDIT_CARD": "#/components/schemas/CreditCardPaymentOption" } }, "description": "Stored payment option metadata for a user." }, "CreditCardPaymentOption": { "type": "object", "required": [ "id", "paymentMethod", "brand", "countryCode", "expMonth", "expYear", "last4" ], "properties": { "id": { "type": "string", "example": "STRIPE-7844364278189399", "description": "Unique identifier for this payment method in our system" }, "paymentMethod": { "type": "string", "enum": [ "CREDIT_CARD" ], "example": "CREDIT_CARD", "description": "Payment method provider/type." }, "brand": { "type": "string", "example": "visa", "description": "Card network brand." }, "displayBrand": { "type": "string", "description": "The brand to use when displaying the card, this accounts for customer's brand choice on dual-branded cards. Stripe documentation: [EU regulation: Co-badged cards compliance](https://docs.stripe.com/co-badged-cards-compliance) & [Stripe PaymentMethod.card.display_brand](https://docs.stripe.com/api/payment_methods/object#payment_method_object-card-display_brand)", "example": "visa" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2", "example": "DE" }, "expMonth": { "type": "integer", "format": "int32", "example": 12, "description": "Card expiration month (1-12)." }, "expYear": { "type": "integer", "format": "int32", "example": 2025, "description": "Card expiration year (YYYY)." }, "last4": { "type": "string", "example": "1234", "description": "Last four digits of the card number." } }, "description": "Stored credit card payment option details." }, "PrepaidBalance": { "type": "object", "required": [ "balanceTotal", "balances" ], "properties": { "balanceTotal": { "type": "object", "required": [ "amountMinorUnits", "currency" ], "description": "The total prepaid balance across all sources and validity periods", "properties": { "amountMinorUnits": { "type": "integer", "description": "Total balance in minor currency units (e.g., cents for EUR/USD). For example, 1000 represents 10.00 in the specified currency.", "example": 1000 }, "currency": { "type": "string", "description": "Three-letter currency code (ISO 4217)", "example": "EUR" } } }, "balances": { "type": "array", "description": "Detailed breakdown of prepaid balance by source and validity period", "items": { "type": "object", "properties": { "expiryDate": { "type": "string", "format": "date-time", "description": "When this balance portion will expire. After this date, the amount will no longer be available for use.", "example": "2024-12-31T23:59:59Z" }, "amountMinorUnits": { "type": "integer", "description": "Current balance amount in minor currency units", "example": 1000 }, "currency": { "type": "string", "description": "Three-letter currency code (ISO 4217)", "example": "EUR" }, "source": { "type": "string", "description": "Origin of this balance portion (e.g., 'Credit' for topped-up amounts, 'Voucher' for promotional credits)", "example": "Credit" }, "initialAmountMinorUnits": { "type": "integer", "description": "Original amount when this balance portion was added, in minor currency units", "example": 1000 } } } } }, "description": "Current prepaid balance information for a user." }, "SetupIntent": { "type": "object", "properties": { "id": { "type": "string", "example": "seti_123Abc456dEf789gHIjKLmNO", "description": "Stripe SetupIntent identifier." }, "clientSecret": { "type": "string", "example": "seti_123Abc456dEf789gHIjKLmNO_secret_ABC123DEF456ghi789JklMNopQRStUV", "description": "Client secret used to complete SetupIntent confirmation on the client." } }, "description": "Stripe SetupIntent data used to confirm and attach a payment method." }, "CreatePaymentOptionRequest": { "type": "object", "description": "Request payload to create a new payment option for a user." }, "CreateStripeCreditCardRequest": { "allOf": [ { "$ref": "#/components/schemas/CreatePaymentOptionRequest" }, { "type": "object", "required": [ "paymentMethodId" ], "properties": { "paymentMethodId": { "type": "string", "description": "Stripe provided payment method id", "example": "pm_321aSdF567gHij" } } } ], "description": "Stripe-specific payload to register a credit card payment method." }, "SessionsHistoryRequest": { "type": "object", "properties": { "sessionStatus": { "type": "array", "description": "If not passed, only COMPLETE sessions are returned.", "items": { "$ref": "#/components/schemas/SessionStatus" } }, "chargingKeyId": { "type": "string", "example": "kjG86L3wn5", "description": "Filter sessions by charging key identifier." }, "startTime": { "type": "string", "format": "date-time", "description": "Lower bound for session start time (inclusive) in UTC." }, "endTime": { "type": "string", "format": "date-time", "description": "Upper bound for session start time (inclusive) in UTC." }, "cursor": { "type": "string", "description": "Cursor string - pass cursor from previous response body to get next page.", "example": 50 }, "limit": { "type": "integer", "description": "Number of entries", "default": 50 } }, "description": "Filtering and pagination options for retrieving session history." }, "SessionsHistoryResponse": { "required": [ "sessions" ], "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" }, "description": "Sessions matching the requested filters." }, "cursor": { "type": "string", "description": "Use this exact string to get next page. If absent, it means no next page is available.", "example": 50 }, "count": { "type": "integer", "description": "The total amount of sessions taking into account the filters sessionStatus, chargingKeyId, startTime and endTime, if provided.", "example": 946 } }, "description": "Paginated list of sessions returned by history queries." }, "SessionEnergy": { "required": [ "unit", "value" ], "type": "object", "properties": { "unit": { "type": "string", "example": "WH", "description": "Energy unit, typically kWh." }, "value": { "type": "number", "example": 57, "description": "Measured energy value for the session." } }, "description": "Energy measurement data for a charging session." }, "SessionCharger": { "type": "object", "properties": { "chargingStationName": { "type": "string", "example": "Drive_API_Test1_Station1", "description": "Display name of the charging station." }, "city": { "type": "string", "example": "Solna", "description": "City where the charger is located." }, "connectorLabel": { "type": "string", "example": "1", "description": "Connector label reported by the charge point operator." }, "evseId": { "type": "string", "example": "SE*CND*EC1*1", "description": "EVSE identifier for the charging point." }, "streetName": { "type": "string", "example": "Rättarvägen", "description": "Street address of the charger." } }, "description": "Location and connector information for the charger used in a session." }, "Transaction": { "type": "object", "description": "Represents a transaction with payment details and time.", "properties": { "paymentMethod": { "type": "string", "enum": [ "CREDIT_CARD", "EXTERNAL", "PREPAID", "NONE" ], "description": "The payment method used for the transaction. Can be `NONE` for outcome `WRITE_OFF`" }, "paymentOutcome": { "type": "string", "enum": [ "CHARGE", "WRITE_OFF", "REFUND" ], "description": "The outcome of the payment process." }, "amount": { "$ref": "#/components/schemas/SessionAmount" }, "time": { "$ref": "#/components/schemas/Time" } }, "required": [ "paymentMethod", "paymentOutcome", "amount", "time" ] }, "SessionAmount": { "required": [ "currencyCode", "minorExclVat", "minorInclVat", "vat" ], "type": "object", "properties": { "currencyCode": { "type": "string", "description": "3-letter currency code", "example": "EUR" }, "minorExclVat": { "type": "integer", "description": "Minor units amount. Example: 2785 = 27.85€.", "example": 2785 }, "minorInclVat": { "type": "integer", "description": "Minor units amount" }, "vat": { "type": "string", "description": "VAT percentage", "example": "17.5" } }, "description": "Monetary amount with currency and VAT breakdown." }, "SessionStartRequest": { "type": "object", "required": [ "connectorId" ], "properties": { "connectorId": { "type": "string", "example": "O9UXK+YI5Q6i0FoI4qHwcA==", "description": "Connector identifier to start charging on." } }, "description": "Request payload to start a charging session remotely." }, "SessionStartResponse": { "type": "object", "description": "SessionId will always be present, unless CREDIT_CARD reservation for a user is required during authentication, then either sessionId or threeDSClientSecret will be present.", "properties": { "sessionId": { "type": "string", "description": "This session id should be stored and used in other endpoints.", "example": "AAdmD55q8Vz" }, "threeDSClientSecret": { "type": "string", "description": "Will only be available for users with CREDIT_CARD payment methods, when CHALLENGE mode has been enabled for 3DS challenges. The 3DS client secret can be used to complete a payment from your frontend. If not present, no user authentication is required to start the session.", "example": "pi_3MtwBwLkdIwHu8ix28v3tqPa_secret_YrKJUkribcBjcG7HVhfZluoGH" } } }, "Receipt": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string" } } }, "PaymentRequest": { "type": "object", "required": [ "paymentOptionId, returnUrl" ], "properties": { "paymentOptionId": { "type": "string", "description": "The id of the payment option", "example": "STRIPE-2059519182987632" }, "returnUrl": { "type": "string", "description": "The URL to which your customer will be redirected after they complete or cancel their payment authentication. If you prefer to redirect them to a mobile application, you can alternatively provide an application URI scheme.", "example": "https://landing.page.after.3ds.authentication" } }, "description": "Request payload to retry or initiate a session payment." }, "PaymentResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Status of the payment attempt." }, "clientSecret": { "type": "string", "description": "The client secret to be used when user authentication is required for the payment to be accepted. E.g. When the payment `status` have a value of `REQUIRES_3DS_AUTHENTICATION`. Ignore otherwise.", "example": "pi_1DtBRR2eZvKYlo2CmCVxxvd7_secret_cWsUkvyTOjhLKh5Wxu61nYc0i" } }, "description": "Response payload describing the payment attempt result." }, "PaymentStatus": { "type": "string", "description": "The status `REQUIRES_3DS_AUTHENTICATION` means you must authenticate the user using the client secret before the payment is accepted.", "enum": [ "SUCCEEDED", "FAILED", "REQUIRES_3DS_AUTHENTICATION" ] }, "Session": { "required": [ "sessionStatus", "connectorId", "sessionId", "transactions" ], "type": "object", "properties": { "balanceStatus": { "$ref": "#/components/schemas/SessionBalanceStatus", "description": "Balance state after applying session costs." }, "sessionStatus": { "$ref": "#/components/schemas/SessionStatus", "description": "Current lifecycle status of the session." }, "charger": { "$ref": "#/components/schemas/SessionCharger", "description": "Charger location and connector metadata." }, "balanceAmountMinor": { "type": "number", "example": "-2160", "description": "Type \"Long\". This field is not relevant for External Clearing (only used when using Plugsurfing's Payment Service Provider). Represents the remaining amount to be paid, expressed as a negative number. A value of 0 indicates the balance is fully paid. -2160 means there is an outstanding amount of 21.60 in the currency of the session." }, "chargingKeyType": { "type": "string", "example": "virtual", "description": "Only available after a session has successfully started. Possible values are \"tag\", \"card\", \"virtual\" or \"plug_and_charge\"." }, "connectorId": { "type": "string", "example": "O9UXK+YI5Q6i0FoI4qHwcA==", "description": "Only available after a session has successfully started." }, "duration": { "type": "string", "format": "duration", "description": "The value is in ISO 8601 duration format", "example": "PT28.913S" }, "energy": { "$ref": "#/components/schemas/SessionEnergy", "description": "Energy consumed during the session." }, "paymentMethod": { "type": "string", "enum": [ "CREDIT_CARD", "EXTERNAL", "PREPAID", "WRITE_OFF" ], "deprecated": true, "description": "Returns the `paymentMethod` of the transaction with the earliest timestamp. This field is `DEPRECATED` and will be removed in future versions. Use `session.transactions[].paymentMethod` instead. Migration note: `WRITE_OFF` was renamed to `NONE`, where `session.transactions[].paymentOutcome=WRITE_OFF` is the replacement" }, "price": { "$ref": "#/components/schemas/SessionAmount", "description": "Total session price." }, "receiptAvailable": { "type": "boolean", "description": "Indicates whether a receipt can be downloaded." }, "sessionId": { "type": "string", "example": "AAdmD55q8Vz", "description": "Unique identifier of the charging session." }, "site": { "type": "string", "example": "Drive_API_Test1", "description": "Human-readable charging site name." }, "startTime": { "$ref": "#/components/schemas/Time", "description": "UTC timestamp when the session started." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" }, "description": "Transactions linked to this charging session." } }, "description": "Detailed charging session information." }, "Time": { "type": "string", "format": "date-time", "description": "Timestamp in ISO 8601 UTC format with up to nanosecond precision.", "example": "2021-01-30T10:00:00.111111111Z" }, "SessionStatus": { "type": "string", "description": "IMPORTANT - when handling this enum other unknown values should be handled.", "enum": [ "CREATED", "WAITING_TO_START", "STARTED", "WAITING_TO_STOP", "STOPPED", "COMPLETE", "FAILED", "UNKNOWN", "STOP_FAILED" ] }, "SessionBalanceStatus": { "type": "string", "enum": [ "PROCESSING", "PAID", "DEBT", "REFUND" ], "description": "Note: this field is not relevant when using External Clearing." }, "UserGroup": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "aGnOerO87e", "description": "Unique identifier of the user group." }, "memberSince": { "type": "string", "format": "date-time", "example": "2023-01-30T10:00:00.111Z", "description": "UTC timestamp when the user joined the group." } }, "description": "Membership information for a user group." }, "CreateUser": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "User id, used later to access user info. Max. length is 255. Allowed characters are ASCII letters, numbers and '-', '.', '_', '~'", "example": "b5d00e95-b998-4a33-9210-84777f4cb4f9" }, "email": { "type": "string", "description": "The email format is validated, but it is not verified by sending an email. This field is mandatory when Plugsurfing is the Merchant on Record." } }, "description": "Request payload to create a drive user." }, "UpdateUser": { "type": "object", "properties": { "email": { "type": "string", "description": "This email format is validated, but it is not verified by sending an email." }, "vatNumber": { "type": "string", "description": "12 character VAT number.", "example": "SE123456789012" }, "billingAddress": { "type": "object", "properties": { "companyName": { "type": "string", "example": "My Company Inc." }, "firstName": { "type": "string", "example": "Anders" }, "lastName": { "type": "string", "example": "Andersson" }, "addressLine1": { "type": "string", "example": "Charging road 1" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string", "example": "12345" }, "city": { "type": "string", "example": "Berlin" }, "country": { "type": "string", "example": "Germany" }, "billingEmail": { "type": "string", "example": "invoice@mycompany.com" }, "additionalInformation": { "type": "string" } }, "description": "Billing address associated with the user account." } }, "description": "Request payload to update user profile and billing details." }, "UserInfo": { "type": "object", "required": [ "id", "hasDebt" ], "properties": { "id": { "type": "string", "description": "User identifier", "example": "b5d00e95-b998-4a33-9210-84777f4cb4f9" }, "email": { "type": "string", "example": "john.smith@plugsurfing.com", "description": "User email address." }, "vatNumber": { "type": "string", "description": "VAT number associated with the user." }, "billingAddress": { "type": "object", "properties": { "name": { "type": "string", "example": "John Smith" }, "companyName": { "type": "string", "example": "MyCompany" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Smith" }, "addressLine1": { "type": "string", "example": "Charger road 1" }, "addressLine2": { "type": "string", "example": "Door 1" }, "postalCode": { "type": "string", "example": "12345" }, "city": { "type": "string", "example": "Berlin" }, "country": { "type": "string", "example": "Germany" }, "billingEmail": { "type": "string", "example": "invoice@mycompany.com" }, "additionalInformation": { "type": "string" } }, "description": "Billing address associated with the user." }, "hasDebt": { "type": "boolean", "description": "true if any of the sessions payments failed. (Relevant only if clearing is done by Plugsurfing)", "example": false }, "userGroups": { "type": "array", "items": { "$ref": "#/components/schemas/UserGroup" }, "description": "User groups the user currently belongs to." } }, "description": "User profile details returned by user management endpoints." }, "StripePublishableApiKeyResponse": { "type": "object", "properties": { "stripePublishableApiKey": { "type": "string", "description": "This publishable API key will be used to integrate with Stripe from client-side code.", "example": "pk_test_F6rIsWTYKDnk2YQcGzw4foMvSVqwPqP7e7oZkgqSipPUNfio7aSei2fv2UMq8uaCS3ULDAn8djODcruhLVYXCPab6yczpPa9" } } }, "Product": { "oneOf": [ { "$ref": "#/components/schemas/PrepaidProduct" }, { "$ref": "#/components/schemas/UserGroupProduct" } ], "discriminator": { "propertyName": "type" } }, "PrepaidProduct": { "type": "object", "required": [ "type", "amountMinorUnits", "currencyCode" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID" ] }, "amountMinorUnits": { "type": "integer", "format": "int64", "description": "Amount in currency minor units. In the example 10.5 Euro is represented as 1050.", "example": 1050 }, "currencyCode": { "type": "string", "description": "ISO 4217", "example": "EUR" } } }, "UserGroupProduct": { "type": "object", "required": [ "type", "groupId" ], "properties": { "type": { "type": "string", "enum": [ "USER_GROUP" ], "description": "Type of user-group product." }, "customerGroupId": { "type": "integer", "description": "Identifier of the customer group granted by the product." } }, "description": "Voucher product that grants access to a user group." }, "ErrorResponse": { "title": "ErrorResponse", "type": "object", "properties": { "message": { "type": "string" } } }, "InvalidRequestErrorResponse": { "title": "InvalidRequestErrorResponse", "type": "object", "required": [ "message", "fields" ], "properties": { "message": { "type": "string" }, "fields": { "type": "array", "items": { "title": "InvalidField", "type": "object", "required": [ "name", "message", "rejectedValue" ], "properties": { "name": { "type": "string" }, "message": { "type": "string", "example": "UserId is not correct" }, "rejectedValue": { "type": "string" } } } } } }, "SessionEventWebhookEnvelope": { "type": "object", "required": [ "event", "payload" ], "properties": { "event": { "type": "string", "description": "Event name. Known values: SESSION_STARTED, SESSION_STOPPED, SESSION_COMPLETE, SESSION_START_FAILED, SESSION_STOP_FAILED, SESSION_FEE_INCURRING. New values may be introduced without prior notice." }, "payload": { "$ref": "#/components/schemas/SessionEventWebhookPayload" } }, "example": { "event": "SESSION_STARTED", "payload": { "userId": "user1", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T10:56:51Z" } } }, "SessionEventWebhookPayload": { "description": "Session event payload. Exactly one identity variant is present: user session payload or fleet session payload.", "oneOf": [ { "$ref": "#/components/schemas/UserSessionEventWebhookPayload" }, { "$ref": "#/components/schemas/FleetSessionEventWebhookPayload" } ] }, "UserSessionEventWebhookPayload": { "type": "object", "required": [ "userId", "sessionId", "timestamp" ], "properties": { "userId": { "type": "string", "description": "External user id." }, "sessionId": { "type": "string", "description": "Plugsurfing encoded session identifier." }, "timestamp": { "type": "string", "format": "date-time", "description": "Event timestamp in UTC." }, "feeWillApplyFrom": { "type": "string", "format": "date-time", "description": "Present for SESSION_FEE_INCURRING." }, "feeType": { "type": "string", "enum": [ "BLOCKING", "CONGESTING", "PARKING" ], "description": "Present for SESSION_FEE_INCURRING when applicable." } } }, "FleetSessionEventWebhookPayload": { "type": "object", "required": [ "keyIdentifier", "sessionId", "timestamp" ], "properties": { "keyIdentifier": { "type": "string", "description": "Charging key identifier used for the fleet session." }, "fleetId": { "type": "string", "description": "External fleet id (usually present for fleet sessions)." }, "visualNumber": { "type": "string", "description": "Visual number from the charging key when available." }, "contractId": { "type": "string", "description": "Contract id from the charging key when available." }, "sessionId": { "type": "string", "description": "Plugsurfing encoded session identifier." }, "timestamp": { "type": "string", "format": "date-time", "description": "Event timestamp in UTC." }, "feeWillApplyFrom": { "type": "string", "format": "date-time", "description": "Present for SESSION_FEE_INCURRING." }, "feeType": { "type": "string", "enum": [ "BLOCKING", "CONGESTING", "PARKING" ], "description": "Present for SESSION_FEE_INCURRING when applicable." } } }, "CdrWebhookRequest": { "type": "object", "required": [ "requestId", "timestamp", "payer", "type", "item" ], "properties": { "requestId": { "type": "string", "description": "Unique identifier for the webhook delivery. The same requestId is reused on retries." }, "timestamp": { "type": "string", "format": "date-time", "description": "Webhook creation timestamp in UTC." }, "payer": { "$ref": "#/components/schemas/CdrWebhookPayer" }, "type": { "type": "string", "enum": [ "SESSION" ] }, "item": { "$ref": "#/components/schemas/CdrWebhookSessionItem" } } }, "CdrWebhookPayer": { "oneOf": [ { "$ref": "#/components/schemas/CdrWebhookUserPayer" }, { "$ref": "#/components/schemas/CdrWebhookChargingKeyPayer" } ], "discriminator": { "propertyName": "type" } }, "CdrWebhookUserPayer": { "type": "object", "required": [ "type", "id", "chargingKey" ], "properties": { "type": { "type": "string", "enum": [ "USER" ] }, "id": { "type": "string" }, "chargingKey": { "$ref": "#/components/schemas/CdrWebhookUserChargingKey" } } }, "CdrWebhookUserChargingKey": { "type": "object", "required": [ "uid", "contractId", "identificationType" ], "properties": { "uid": { "type": "string" }, "visualNumber": { "type": "string" }, "contractId": { "type": "string" }, "identificationType": { "$ref": "#/components/schemas/CdrWebhookIdentificationType" }, "type": { "type": "string", "enum": [ "CHARGING_KEY" ] } } }, "CdrWebhookChargingKeyPayer": { "type": "object", "required": [ "type", "uid", "contractId", "identificationType" ], "properties": { "type": { "type": "string", "enum": [ "CHARGING_KEY" ] }, "uid": { "type": "string" }, "visualNumber": { "type": "string" }, "contractId": { "type": "string" }, "identificationType": { "$ref": "#/components/schemas/CdrWebhookIdentificationType" } } }, "CdrWebhookIdentificationType": { "type": "string", "enum": [ "rfid", "virtual", "plug_and_charge" ] }, "CdrWebhookSessionItem": { "type": "object", "required": [ "sessionId", "startTime", "stopTime", "energyConsumedInWh", "empCost", "cpoClaimedCost", "location", "startMethod" ], "properties": { "sessionId": { "type": "string" }, "externalSessionId": { "type": "string" }, "startMethod": { "type": "string", "enum": [ "REMOTE", "LOCAL" ], "description": "Indicates how the charging session was started. REMOTE: initiated by a backend/app command. LOCAL: initiated directly at the charge point (e.g. RFID or Plug&Charge).", "example": "REMOTE" }, "startTime": { "type": "string", "format": "date-time" }, "stopTime": { "type": "string", "format": "date-time" }, "energyConsumedInWh": { "type": "integer", "format": "int64" }, "totalParkingTimeInSeconds": { "type": "integer", "format": "int64" }, "empCost": { "$ref": "#/components/schemas/CdrWebhookCost" }, "cpoClaimedCost": { "$ref": "#/components/schemas/CdrWebhookCost" }, "location": { "$ref": "#/components/schemas/CdrWebhookLocation" }, "homeCharging": { "$ref": "#/components/schemas/CdrWebhookHomeCharging" } } }, "CdrWebhookCost": { "type": "object", "required": [ "totalCostMinorUnitsInclVat", "totalCostMinorUnitsExclVat", "currency", "priceIncludesVat", "costSegments" ], "properties": { "totalCostMinorUnitsInclVat": { "type": "integer", "format": "int64" }, "totalCostMinorUnitsExclVat": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "EUR" }, "priceIncludesVat": { "type": "boolean" }, "costSegments": { "type": "array", "items": { "$ref": "#/components/schemas/CdrWebhookCostSegment" } } } }, "CdrWebhookCostSegment": { "type": "object", "required": [ "type", "quantity", "vatRate", "pricePerUnit", "pricePerUnitMinorUnitsInclVat", "segmentCostMinorUnitsExclVat", "segmentCostMinorUnitsInclVat", "unit" ], "properties": { "type": { "type": "string", "enum": [ "TIME", "ENERGY", "FLAT", "CAPPED", "PARKING_TIME", "CONGESTION_TIME" ] }, "quantity": { "type": "number", "format": "double" }, "vatRate": { "type": "number", "format": "double" }, "pricePerUnit": { "type": "number", "format": "double" }, "pricePerUnitMinorUnitsInclVat": { "type": "integer", "format": "int64" }, "segmentCostMinorUnitsExclVat": { "type": "integer", "format": "int64" }, "segmentCostMinorUnitsInclVat": { "type": "integer", "format": "int64" }, "unit": { "$ref": "#/components/schemas/CdrWebhookUnit" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "CdrWebhookUnit": { "type": "object", "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "session", "kWh", "Wh", "min", "h" ] }, "amount": { "type": "integer" } } }, "CdrWebhookLocation": { "type": "object", "required": [ "id", "evseId", "cpoId", "cpoName", "address", "city", "country", "powerType", "private", "coordinates" ], "properties": { "id": { "type": "string" }, "evseId": { "type": "string" }, "cpoId": { "type": "string" }, "cpoName": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code." }, "powerType": { "type": "string", "enum": [ "AC", "DC", "AC_1_PHASE", "AC_3_PHASE" ] }, "private": { "type": "boolean" }, "coordinates": { "$ref": "#/components/schemas/CdrWebhookGeoCoordinates" } } }, "CdrWebhookGeoCoordinates": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } } }, "CdrWebhookHomeCharging": { "type": "object", "required": [ "exemptVat" ], "properties": { "exemptVat": { "type": "boolean" } } }, "EmpChargingKeyTransferRequest": { "type": "object", "required": [ "targetFleetId" ], "properties": { "targetFleetId": { "type": "string", "example": "y1nNLJqb7m", "description": "Customer-facing external ID of the fleet to transfer the charging key into. The target fleet must exist, belong to the same EMP parent as the source fleet, and already have an external payment option configured." } }, "description": "Request payload to transfer an EMP charging key to another fleet." }, "EmpChargingKeyOrderAssignRequest": { "type": "object", "required": [ "keyIdentifier", "referenceId" ], "properties": { "keyIdentifier": { "type": "string", "description": "RFID UID of the physical card, in the same format that a charging station would read from the card." }, "referenceId": { "type": "string", "description": "Number printed on the physical card itself, also known as the visual number." } }, "description": "Optional request body for assigning an order. Required only when the order requires printing." }, "EmpProductPrinting": { "type": "object", "description": "Printing requirements for this product. Use the `schema` field to understand which variables must be provided in the `printing` payload when placing an order for this product.", "required": [ "schema" ], "properties": { "schema": { "type": "object", "additionalProperties": true, "description": "A JSON Schema (Draft 2020-12) object that describes the shape and validation rules of the `printing` payload expected when ordering this product. Use this schema to build, validate, and auto-generate forms for the printing data your customers must supply.", "example": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "driverName", "licensePlate" ], "additionalProperties": false, "properties": { "driverName": { "type": "string", "description": "Full name of the card holder to be printed on the card.", "minLength": 5, "maxLength": 50 }, "licensePlate": { "type": "string", "description": "Vehicle license plate to be printed on the card.", "minLength": 4, "maxLength": 6 } } } } } }, "EmpProduct": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "Am07b6Q7JZ", "description": "Unique identifier of the product." }, "name": { "type": "string", "example": "Standard EV Card", "description": "Human-readable name of the product." }, "description": { "type": "string", "example": "Physical charging card for fleet drivers.", "description": "Human-readable product description, when available." }, "printing": { "$ref": "#/components/schemas/EmpProductPrinting", "description": "Present when the product requires printing details when placing an order. Omitted for products that do not require a `printing` payload." } }, "description": "A product available to order." }, "EmpProductsResponse": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/EmpProduct" }, "description": "List of products available." } }, "description": "Response containing the list of products available for ordering." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication" } } }, "webhooks": { "Session Events": { "post": { "summary": "Receive Session Event", "description": "Plugsurfing sends session event notifications to the configured webhook URL. Known event names are SESSION_STARTED, SESSION_STOPPED, SESSION_COMPLETE, SESSION_START_FAILED, SESSION_STOP_FAILED, and SESSION_FEE_INCURRING. New event names may be introduced without prior notice. Events are sent once and the receiver response is not used for retries.", "operationId": "sessionEventsWebhook", "parameters": [ { "name": "X-HMAC-SHA512-Signature", "in": "header", "required": false, "description": "Base64 encoded HMAC SHA-512 signature of the raw request body. Present when HMAC signing is configured.", "schema": { "type": "string" } }, { "name": "X-HMAC-SHA512-SignedAt", "in": "header", "required": false, "description": "RFC 3339 timestamp for when the payload was signed. Present when HMAC signing is configured.", "schema": { "type": "string", "format": "date-time" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionEventWebhookEnvelope" }, "examples": { "sessionStarted": { "summary": "SESSION_STARTED (user session)", "value": { "event": "SESSION_STARTED", "payload": { "userId": "usr_123", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T10:56:51Z" } } }, "sessionStopped": { "summary": "SESSION_STOPPED (fleet session)", "value": { "event": "SESSION_STOPPED", "payload": { "fleetId": "fleet_42", "keyIdentifier": "e0e03336", "visualNumber": "DE*8PS*FR1RFK*4", "contractId": "DE-8PS-C0AD21B13-Q", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T11:31:02Z" } } }, "sessionComplete": { "summary": "SESSION_COMPLETE (user session)", "value": { "event": "SESSION_COMPLETE", "payload": { "userId": "usr_123", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T11:41:22Z" } } }, "sessionStartFailed": { "summary": "SESSION_START_FAILED (user session)", "value": { "event": "SESSION_START_FAILED", "payload": { "userId": "usr_123", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T10:56:57Z" } } }, "sessionStopFailed": { "summary": "SESSION_STOP_FAILED (fleet session)", "value": { "event": "SESSION_STOP_FAILED", "payload": { "fleetId": "fleet_42", "keyIdentifier": "e0e03336", "contractId": "DE-8PS-C0AD21B13-Q", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T11:29:10Z" } } }, "sessionFeeIncurring": { "summary": "SESSION_FEE_INCURRING", "value": { "event": "SESSION_FEE_INCURRING", "payload": { "userId": "usr_123", "sessionId": "L60XMxWy0oP", "timestamp": "2025-06-12T11:12:48Z", "feeWillApplyFrom": "2025-06-12T11:22:48Z", "feeType": "BLOCKING" } } } } } } }, "responses": { "200": { "description": "Webhook received." }, "400": { "description": "Invalid payload." }, "500": { "description": "Receiver failed to process the webhook." } } } }, "CDR Forwarding": { "post": { "summary": "Receive Forwarded CDR", "description": "Plugsurfing sends Charging Detail Records (CDRs) when you are set to clear the sessions. If a request does not receive a 200 response (or times out), Plugsurfing retries nightly for up to 7 days using the same requestId for idempotency.", "operationId": "cdrForwardingWebhook", "parameters": [ { "name": "X-HMAC-SHA512-Signature", "in": "header", "required": false, "description": "Base64 encoded HMAC SHA-512 signature of the raw request body. Present when HMAC signing is configured.", "schema": { "type": "string" } }, { "name": "X-HMAC-SHA512-SignedAt", "in": "header", "required": false, "description": "RFC 3339 timestamp for when the payload was signed. Present when HMAC signing is configured.", "schema": { "type": "string", "format": "date-time" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdrWebhookRequest" }, "examples": { "cdrUserPayer": { "summary": "CDR with user payer", "value": { "requestId": "req_9f8ca42f", "timestamp": "2025-06-12T12:00:00Z", "payer": { "type": "USER", "id": "usr_123", "chargingKey": { "uid": "NR9348593", "contractId": "DE-8PS-C1Z3R5KZI-8", "visualNumber": "2340-1254-6543-5655", "identificationType": "rfid", "type": "CHARGING_KEY" } }, "type": "SESSION", "item": { "sessionId": "BpK64y1z1QA", "externalSessionId": "89111162", "startMethod": "REMOTE", "startTime": "2025-06-12T10:30:00Z", "stopTime": "2025-06-12T11:20:00Z", "energyConsumedInWh": 18500, "totalParkingTimeInSeconds": 600, "empCost": { "totalCostMinorUnitsInclVat": 2128, "totalCostMinorUnitsExclVat": 1702, "currency": "NOK", "priceIncludesVat": true, "costSegments": [ { "type": "ENERGY", "quantity": 18.5, "vatRate": 25, "pricePerUnit": 1.15, "pricePerUnitMinorUnitsInclVat": 115, "segmentCostMinorUnitsExclVat": 1702, "segmentCostMinorUnitsInclVat": 2128, "unit": { "type": "kWh", "amount": 1 }, "from": "2025-06-12T10:30:00Z", "to": "2025-06-12T11:20:00Z" } ] }, "cpoClaimedCost": { "totalCostMinorUnitsInclVat": 2000, "totalCostMinorUnitsExclVat": 1600, "currency": "NOK", "priceIncludesVat": true, "costSegments": [ { "type": "ENERGY", "quantity": 18.5, "vatRate": 25, "pricePerUnit": 1.08, "pricePerUnitMinorUnitsInclVat": 108, "segmentCostMinorUnitsExclVat": 1600, "segmentCostMinorUnitsInclVat": 2000, "unit": { "type": "kWh", "amount": 1 }, "from": "2025-06-12T10:30:00Z", "to": "2025-06-12T11:20:00Z" } ] }, "location": { "id": "LOC-1001", "evseId": "IT_TSL_EMIL*0001", "cpoId": "DE*ABC", "cpoName": "Example CPO", "address": "Charging Road 1", "city": "Berlin", "postalCode": "10115", "country": "DEU", "powerType": "DC", "private": false, "coordinates": { "latitude": 52.520008, "longitude": 13.404954 } } } } }, "cdrChargingKeyPayer": { "summary": "CDR with charging key payer", "value": { "requestId": "req_7a22be9d", "timestamp": "2025-06-12T12:15:00Z", "payer": { "type": "CHARGING_KEY", "uid": "NR9348593", "visualNumber": "2340-1254-6543-5655", "contractId": "DE-8PS-C1Z3R5KZI-8", "identificationType": "virtual" }, "type": "SESSION", "item": { "sessionId": "ApK11r8u9Qa", "startMethod": "LOCAL", "startTime": "2025-06-12T09:00:00Z", "stopTime": "2025-06-12T09:45:00Z", "energyConsumedInWh": 12200, "empCost": { "totalCostMinorUnitsInclVat": 1800, "totalCostMinorUnitsExclVat": 1440, "currency": "EUR", "priceIncludesVat": true, "costSegments": [ { "type": "FLAT", "quantity": 1, "vatRate": 25, "pricePerUnit": 18, "pricePerUnitMinorUnitsInclVat": 1800, "segmentCostMinorUnitsExclVat": 1440, "segmentCostMinorUnitsInclVat": 1800, "unit": { "type": "session", "amount": 1 } } ] }, "cpoClaimedCost": { "totalCostMinorUnitsInclVat": 1700, "totalCostMinorUnitsExclVat": 1360, "currency": "EUR", "priceIncludesVat": true, "costSegments": [ { "type": "FLAT", "quantity": 1, "vatRate": 25, "pricePerUnit": 17, "pricePerUnitMinorUnitsInclVat": 1700, "segmentCostMinorUnitsExclVat": 1360, "segmentCostMinorUnitsInclVat": 1700, "unit": { "type": "session", "amount": 1 } } ] }, "location": { "id": "LOC-2020", "evseId": "SE_ABC_001", "cpoId": "SE*ABC", "cpoName": "Nordic CPO", "address": "Sveavagen 10", "city": "Stockholm", "country": "SWE", "powerType": "AC_3_PHASE", "private": false, "coordinates": { "latitude": 59.334591, "longitude": 18.06324 } }, "homeCharging": { "exemptVat": false } } } } } } } }, "responses": { "200": { "description": "CDR accepted." }, "400": { "description": "Invalid CDR payload." }, "403": { "description": "Authorization failed." }, "500": { "description": "Receiver failed to process the CDR." } } } } } }