Every API here is available over the APIs.io API and to AI agents over MCP.
{
"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": {
# --- truncated at 32 KB (351 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/plugsurfing/refs/heads/main/openapi/_original/plugsurfing-reference-openapi.json