Getting started

Learn how to integrate with the Plugsurfing Drive API to offer EV charging in your applications. This guide covers authentication, searching for charging stations, managing users, and handling charging sessions. This guide will walk you through the essential steps to integrate Plugsurfing’s Drive API into your application, enabling you to provide comprehensive EV charging services to your users.

Integration Overview

Here’s what a typical integration journey usually starts like:

Get API credentials and understand authentication
Search for charging locations using geosearch
Create users
Start and stop charging sessions

Using AI? Start with the AI Integration Playbook for the recommended workflow across the Drive API docs, openapi.json, and /mcp. For the live MCP surface, supported tool categories, and security limitations, see MCP for AI Agents.

1. Authentication

All requests to the Drive API require an API key for authentication. The API key must be included in the HTTP header of every request.

X-API-Key: your-api-key-here

URLs for our different environments

Staging: https://drive-api-stage.plugsurfing.com/drive
Production: https://drive-api.plugsurfing.com/drive

The examples in this guide use full Drive API URLs. If you copy paths from openapi.json, note that OpenAPI paths already include the product prefix, such as /drive or /emp. Do not append an OpenAPI path that starts with /drive to a base URL that already ends with /drive. For example, the OpenAPI path /drive/v1/geosearch/radius maps to https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius on stage. EMP paths use their own /emp/v1/... prefix, for example https://{environment}.plugsurfing.com/emp/v1/charging-keys. Example request:

curl --request POST \
     --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.52&longitude=13.41' \
     --header 'X-API-Key: your-api-key'

For your security: Never expose your API key in client-side code or public repositories. Store it securely and use it only in server-to-server communications.

📘 Learn More For detailed information about authentication and authorization, check API Key Access & Permissions

2. Searching for Charging Locations

One of the first features you’ll likely implement is helping users find charging stations.
Here is how to find available charging stations within a specified distance from a point:

curl --request POST \
     --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=52.52&longitude=13.41&distance=3000' \
     --header 'X-API-Key: your-api-key' \
     --data '
{
  "filters": {
    "locationStatuses": [
      "AVAILABLE"
    ],
    "powerType": "DC"
  }
}
'

This searches for available DC chargers within 3km of the specified coordinates.
The response contains a list of locations data (address, opening hours, chargers, connectors, availability)

📘 Learn More For more ways to find charging locations and detailed information about the data and filtering options, see the our dedicated guide.

3. Managing Users

Before users can start charging, you need to sync your users with out system. The most common approach is to send us the user identifier you use in your system. That way, you can easily use the same identifier later on to identify the user on other endpoints. You can also pass the user’s email.

Creating a User

curl --request POST \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users \
     --header 'X-API-Key: your-api-key' \
     --data '
{
  "id": "9064b366-80cf-47f2-a6d0-e9960c06fc1f",
  "email": "user@example.com"
}
'

Getting User Information

Let’s try to retrieve information from the user we just created:

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f \
     --header 'X-API-Key: your-api-key'

📘 Learn More For more details on User Management, checkout our dedicated guide.

4. Managing Charging Keys

Charging keys authorize users to start charging sessions. There are two types:

Physical cards (RFID cards/tags), used for local charging
Virtual keys, used for remote charging

Listing a User’s Charging Keys

When a user is created, a Virtual key is automatically created. Let’s confirm that:

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/charging-keys \
     --header 'X-API-Key: your-api-key'

The response should look like this:

{
  "keys": [
    {
      "name": "App Charging Key",
      "enabled": true,
      "keyId": "80c5f015582cb2",
      "contractId": "DE-8PS-C8Z1CAHJM-U",
      "type": "virtual",
      "validFrom": "2025-03-07T10:18:02.000Z",
      "validTo": "2035-03-07T10:18:02.000Z",
      "created": "2025-03-07T10:18:02.000Z",
      "updated": "2025-03-07T10:18:02.000Z"
    }
  ]
}

📘 Learn More For more details on Charging Keys, checkout our dedicated guide.

5. Managing Charging Sessions

Now that our user is created, they can start and stop remote charging sessions.

Starting a Remote Charging Session

To start a remote session, you need to provide two things:

user id (to identify who requests the charging session)
connector id (to identify which connector should be requested to start delivering energy)

curl --request POST \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/start \
     --header 'X-API-Key: your-api-key' \
     --data '{"connectorId":"QsxRV9B8qSa8dV/U+/lOCQ=="}'

The response will include a sessionId that you’ll need for checking status or stopping the session:

{
  "sessionId": "Nx5NomJyaMD"
}

Checking Session Status

curl --request GET \
     --url https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/Nx5NomJyaMD \
     --header 'X-API-Key: your-api-key'

Stopping a Charging Session

curl -X POST \
  "https://drive-api-stage.plugsurfing.com/drive/v1/users/9064b366-80cf-47f2-a6d0-e9960c06fc1f/sessions/Nx5NomJyaMD/stop" \
     --header 'X-API-Key: your-api-key'

📘 Learn More For detailed information about Remote Charging and Sessions, checkout our dedicated guide

Error Handling

Errors are returned with the appropriate HTTP status codes and error messages. The timeout for all API endpoints is 10 seconds unless otherwise specified. Detailed error documentation is available. For more information, please refer to the API Reference.

Next Steps

Now that you understand the basics of the Drive API, you might want to explore:

If you have any questions or need assistance with your integration, please contact us.

Guides

API reference

Integration Overview

1. Authentication

URLs for our different environments

2. Searching for Charging Locations

3. Managing Users

Creating a User

Getting User Information

4. Managing Charging Keys

Listing a User’s Charging Keys

5. Managing Charging Sessions

Starting a Remote Charging Session

Checking Session Status

Stopping a Charging Session

Error Handling

Next Steps

​Integration Overview

​1. Authentication

​URLs for our different environments

​2. Searching for Charging Locations

​3. Managing Users

​Creating a User

​Getting User Information

​4. Managing Charging Keys

​Listing a User’s Charging Keys

​5. Managing Charging Sessions

​Starting a Remote Charging Session

​Checking Session Status

​Stopping a Charging Session

​Error Handling

​Next Steps

Integration Overview

1. Authentication

URLs for our different environments

2. Searching for Charging Locations

3. Managing Users

Creating a User

Getting User Information

4. Managing Charging Keys

Listing a User’s Charging Keys

5. Managing Charging Sessions

Starting a Remote Charging Session

Checking Session Status

Stopping a Charging Session

Error Handling

Next Steps