Skip to main content
POST

Authorizations

Authorization
string
header
required

Your integration's client credentials (test or live). The token acts as your integration's team and lasts 1 hour; request a new one when it expires. Send client_id, client_secret and grant_type=client_credentials. No OAuth scopes are needed.

Headers

Plugchoice-Version
enum<string>

The API version to answer with (400 unknown-version for one this API does not know). Every response carries the version that answered in the same header.

Available options:
2026-10-07

Body

application/json
scope
object
required

Everything the client session's link sessions may reach. At least one of them (422 scope-required); every id must be one you may use (404 not-found).

external_user_id
string

Integrations only. For this user of yours; turns on the consent screen. Without it, your own chargers.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9._:@-]+$
device_type
enum<string>
default:charger

The kind of device. A link session is about one kind; another type is 422 unsupported-device-type.

Available options:
charger,
meter
language
string
default:en

BCP 47 tag for the hosted flow. Unsupported languages fall back to English.

Example:

"nl"

color_scheme
enum<string>
default:system
Available options:
light,
dark,
system
vendor
string

A catalog vendor id (for example peblar). Skips the brand picker.

methods
enum<string>[]

Limit the onboarding methods offered. Default all.

How a charger gets connected:

  • local_hotspot: the SDK joins the charger's own Wi-Fi and configures it (Charge Amps, Enovates, go-e, Peblar, Webasto).
  • local_lan: the SDK finds the charger on the home network, or joins its setup hotspot, signs in to it over the brand's pinned HTTPS and configures it (Alfen). The identity is read from the charger.
  • local_ble: the SDK (or Web Bluetooth in a browser) configures the charger over Bluetooth, with the identity from its sticker (SolarEdge), or the one it has (Ratio, Teltonika, Wallbox).
  • manual_ocpp: the user types the identity and configures the charger themselves; any OCPP charger, works in a browser.
  • vendor_cloud: Plugchoice switches the charger over in its brand's cloud after the user signs in there with the charger owner's account (Zaptec, Easee), or after the user did it in the brand's app (Easee); works in a browser.

More may be added.

Available options:
local_hotspot,
local_lan,
local_ble,
manual_ocpp,
vendor_cloud
charger_reference
string

Integrations only. Your own label for the charger being added; returned as reference.

Maximum string length: 255
email
string<email>

Integrations only, for a user of yours whose chargers stay in their own Plugchoice account: their email address, prefilled when they sign in. They can change it; it never finds or links an account by itself.

Maximum string length: 255

Integrations only, for a user of yours whose chargers stay in their own Plugchoice account: what the consent screen asks for, and what your grant on each charger gets. Some of the scopes Plugchoice allowed your integration (another one is a field error); charger:read is always included. Default: all of them.

Minimum array length: 1

What your user lets your integration do with a charger in their own account:

  • charger:read: status, connectors, model, firmware and settings. Always asked.
  • sessions:read: charging sessions (times, energy and the card used).
  • charger:control: start and stop, current limit, smart charging. One integration per charger.
  • site:read: the site's address.
Available options:
charger:read,
sessions:read,
charger:control,
site:read
redirect_uri
string<uri>

Browser only. Where the hosted flow sends your user when a link session is done; it must be one of your integration's Return URLs on its SDK page (for a Plugchoice user, a Plugchoice or custom domain of theirs). The SDK ignores it and returns to your app.

Response

Created

id
string<uuid>
required
client_secret
string
required

Hand it to the SDK (your fetchClientSecret returns it). cs_test_ for a test integration, cs_live_ otherwise, then 32 random bytes base64url. Opaque; never log it.

Example:

"cs_live_Hq3k9d0mR2xYw7pLf8sVb1nC4eTgJ6aZuQ5iKoXyM0w"

expires_at
string<date-time>
required

Link can open link sessions with it until then (60 minutes).

web_url
string<uri>
required

Link in a browser, with the client secret in the fragment (never sent to a server). Append &action=…&charger_id=… for an action other than add.

Example:

"https://connect.plugchoice.com/#cs=cs_live_Hq3k9d0mR2xYw7pLf8sVb1nC4eTgJ6aZuQ5iKoXyM0w"