> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

1. Get API credentials and understand authentication
2. Search for charging locations using geosearch
3. Create users
4. Start and stop charging sessions

> **Using AI?**
>
> Start with the [AI Integration Playbook](/docs/drive-api/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](/docs/drive-api/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.

```text theme={null}
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:

```bash theme={null}
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'
```

<Info>
  **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.
</Info>

> 📘 **Learn More**
>
> For detailed information about authentication and authorization, check [API Key Access & Permissions](/docs/drive-api/authorization)

## 2. Searching for Charging Locations

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

```bash theme={null}
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.<br />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](/docs/drive-api/geosearch).

## 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

```bash theme={null}
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:

```bash theme={null}
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](/docs/drive-api/user).

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/docs/drive-api/charging-keys).

## 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)

```bash theme={null}
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:

```json theme={null}
{
  "sessionId": "Nx5NomJyaMD"
}
```

### Checking Session Status

```bash theme={null}
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

```bash theme={null}
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](/docs/drive-api/sessions)

## 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](/reference).

## Next Steps

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

* [In-depth Geosearch capabilities](/docs/drive-api/geosearch)
* [User management](/docs/drive-api/user)
* [Charging key management](/docs/drive-api/charging-keys)
* [Sessions](/docs/drive-api/sessions)
* [Payment options and configurations](/docs/drive-api/payments)

If you have any questions or need assistance with your integration, please [contact us](/contact-and-support).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.