# Add Card Source: https://developer.plugchoice.com/api-reference/cards/add-card POST /v3/sites/{site}/cards Adds a new RFID card to the specified location. The UUID of the location. The display name of the card. Maximum 255 characters. The RFID token identifier. Maximum 20 characters. An optional array of charger UUIDs to restrict the card to. Each UUID must belong to the location. Omit or pass an empty array to allow the card on all chargers at the location. ## Response The numeric ID of the card. The display name of the card. The RFID token identifier of the card. The UUIDs of the chargers this card is restricted to. An empty array means the card is allowed on all chargers at the location. ISO 8601 timestamp of when the card was created. ISO 8601 timestamp of when the card was last updated. # Delete Card Source: https://developer.plugchoice.com/api-reference/cards/delete-card DELETE /v3/sites/{site}/cards/{card} Deletes an RFID card from the specified location. Returns a `204 No Content` response on success. The UUID of the location. The ID of the card. # List Cards Source: https://developer.plugchoice.com/api-reference/cards/list-cards GET /v3/sites/{site}/cards Returns a paginated list of RFID cards for the specified location. Results are paginated with 25 items per page. The UUID of the location. ## Response The numeric ID of the card. The display name of the card. The RFID token identifier of the card. The UUIDs of the chargers this card is restricted to. An empty array means the card is allowed on all chargers at the location. ISO 8601 timestamp of when the card was created. ISO 8601 timestamp of when the card was last updated. # List Seen Cards Source: https://developer.plugchoice.com/api-reference/cards/list-seen-cards GET /v3/sites/{site}/seen-cards Returns a paginated list of cards that have been seen via OCPP Authorize logs at chargers belonging to the specified location. These are cards that have attempted to authenticate but may not yet be registered. The UUID of the location. The page number. Defaults to `1`. The number of items per page. Defaults to `10`, maximum `100`. ## Response Each item in the paginated list represents a distinct card token seen at the location's chargers. The RFID token identifier (`idTag`) extracted from the OCPP Authorize log. Timestamp of the most recent time this token was seen at the location's chargers. # Update Card Source: https://developer.plugchoice.com/api-reference/cards/update-card PUT /v3/sites/{site}/cards/{card} Updates an existing RFID card for the specified location. The UUID of the location. The ID of the card. The display name of the card. Maximum 255 characters. The RFID token identifier. Maximum 20 characters. An optional array of charger UUIDs to restrict the card to. Each UUID must belong to the location. When provided, it replaces the card's current charger restrictions; pass an empty array to allow the card on all chargers at the location. ## Response The numeric ID of the card. The display name of the card. The RFID token identifier of the card. The UUIDs of the chargers this card is restricted to. An empty array means the card is allowed on all chargers at the location. ISO 8601 timestamp of when the card was created. ISO 8601 timestamp of when the card was last updated. # Bulk Command Source: https://developer.plugchoice.com/api-reference/charger-actions/bulk-command POST /v3/chargers/commands/bulk Queues the same OCPP 1.6 command against multiple chargers at once. Each charger is processed by a background job; the response returns a run resource you can poll to track progress. Chargers the authenticated user cannot access are silently reported as `skipped_forbidden` in the run results. Chargers that are offline at dispatch time are reported as `offline`. Other failures are reported as `error` with a message. The OCPP 1.6 command name (e.g. `Reset`, `ChangeAvailability`, `UnlockConnector`, `TriggerMessage`, `ChangeConfiguration`). Command-specific payload forwarded to each charger. Optional. Shape depends on the command. UUIDs of the target chargers. Minimum 1, no hard upper bound — result rows are inserted in batches and one queue job is dispatched per accessible charger. ## Response Returns `202 Accepted` with the created run wrapped in `data`. Unique identifier of the bulk run. Use this with `GET /v3/chargers/commands/bulk/{run}` to poll progress. The OCPP command that was queued. The command payload forwarded to each charger. `running` while jobs are in flight, `completed` once every charger has a terminal result. Number of chargers submitted. Chargers that acknowledged the command. Chargers that were offline when the command was dispatched. Chargers whose command failed for any other reason (message in the per-result payload). Chargers the authenticated user does not have access to, or that could not be resolved. When the run was created (ISO 8601 date-time). When every charger reached a terminal result (ISO 8601 date-time). `null` while the run is still in progress. Per-charger status. Each entry contains `charger_uuid`, `status` (`pending`, `sent`, `offline`, `error`, `skipped_forbidden`), `message`, `executed_at`, and — when the user has access — an embedded `charger` object with `uuid`, `identity`, and `reference`. # Clear Charging Profile Source: https://developer.plugchoice.com/api-reference/charger-actions/clear-charging-profile POST /v3/chargers/{charger}/actions/clear-charging-profile Sends a ClearChargingProfile command to the charger. All parameters are optional filters -- if none are provided, all charging profiles are cleared. The UUID of the charger. The ID of the charging profile to clear. The connector ID to clear profiles for. Must be 0 or greater. Filter by purpose. One of `ChargePointMaxProfile`, `TxDefaultProfile`, or `TxProfile`. Filter by stack level. Must be 0 or greater. ## Response The response status from the charger (e.g., `Accepted`, `Unknown`). # Get Bulk Command Run Source: https://developer.plugchoice.com/api-reference/charger-actions/get-bulk-command GET /v3/chargers/commands/bulk/{run} Retrieves the current state of a bulk command run, including per-charger results. Poll this endpoint (e.g. every two seconds) until `status` is `completed`. The UUID returned by `POST /v3/chargers/commands/bulk`. ## Response Returns the run resource wrapped in `data`. See [Bulk Command](/api-reference/charger-actions/bulk-command#response) for field descriptions. # Get Composite Schedule Source: https://developer.plugchoice.com/api-reference/charger-actions/get-composite-schedule POST /v3/chargers/{charger}/actions/composite-schedule Retrieves the composite charging schedule from the charger. The composite schedule is a merged view of all active charging profiles for a given connector and time duration. The UUID of the charger. The ID of the connector to get the schedule for. Use `0` to get the schedule for the entire charge point. The duration in seconds for the requested schedule. The unit in which the schedule should be expressed. Possible values: `A` (Amperes), `W` (Watts). ## Response The response status from the charger (`Accepted` or `Rejected`). The connector ID for which the schedule is provided. The start date and time of the composite schedule (ISO 8601). The composite charging schedule. The unit of the schedule (`A` or `W`). List of charging schedule periods. Start of the period in seconds from the start of the schedule. Power or current limit during this period. Number of phases that can be used for charging. Duration of the schedule in seconds. Start date and time of the schedule (ISO 8601). Minimum charging rate supported. # Restart Source: https://developer.plugchoice.com/api-reference/charger-actions/restart-charger POST /v3/chargers/{charger}/actions/restart Sends a remote reset command to the charger, causing it to restart. The UUID of the charger. ## Response The response status from the charger (e.g., `Accepted`, `Rejected`). # Set Charge Limit Source: https://developer.plugchoice.com/api-reference/charger-actions/set-charge-limit POST /v3/chargers/{charger}/actions/charge-limit Sets the charging current limit for a specific connector. The limit is specified in Amperes (A). Optionally specify a stack level for the charging profile. The UUID of the charger. The ID of the connector to set the limit for. Use `0` for the charge point level. The charging current limit in Amperes (A). Must be 0 or greater. The stack level for the charging profile. Higher stack levels take priority over lower ones. Defaults to `1` if not specified. Not all chargers support all stack levels. ## Response The response status from the charger (e.g., `Accepted`, `Rejected`). # Set Charging Profile Source: https://developer.plugchoice.com/api-reference/charger-actions/set-charging-profile POST /v3/chargers/{charger}/actions/charging-profile Sends a SetChargingProfile command to the charger. Supports the full OCPP 1.6 SetChargingProfile structure including `ChargePointMaxProfile`, `TxDefaultProfile`, and `TxProfile` purposes. The UUID of the charger. The connector ID. Use `0` for the charge point level, or a positive integer for a specific connector. The charging profile to set. Unique identifier for the charging profile. Transaction ID. Only applicable for `TxProfile` purpose. Priority level of the profile in the stack. Must be 0 or greater. Purpose of the profile. One of `ChargePointMaxProfile`, `TxDefaultProfile`, or `TxProfile`. Kind of schedule. One of `Absolute`, `Recurring`, or `Relative`. Recurrency period. One of `Daily` or `Weekly`. Only applicable for `Recurring` kind. Start of profile validity as an ISO 8601 date-time. End of profile validity as an ISO 8601 date-time. The charging schedule. Duration of the schedule in seconds. Start of the schedule as an ISO 8601 date-time. Unit of rate. Either `A` (Amperes) or `W` (Watts). List of schedule periods. At least one period is required. Start of the period in seconds from the schedule start. Must be 0 or greater. The charging rate limit for this period. Must be 0 or greater. The number of phases to use. Between 1 and 3. Minimum charging rate supported. ## Response The response status from the charger (e.g., `Accepted`, `Rejected`). # Start Charging Source: https://developer.plugchoice.com/api-reference/charger-actions/start-charging POST /v3/chargers/{charger}/actions/start Sends a remote start transaction command to the charger. The charger will attempt to start a charging session on the specified connector using the provided ID token. The UUID of the charger. The connector ID to start charging on. Must be greater than 0. If not specified, the charger will select a connector automatically. The ID token (RFID tag) to authorize the charging session. Maximum 20 characters. ## Response The response status from the charger (e.g., `Accepted`, `Rejected`). # Stop Charging Source: https://developer.plugchoice.com/api-reference/charger-actions/stop-charging POST /v3/chargers/{charger}/actions/stop Sends a remote stop transaction command to the charger to end an active charging session. The UUID of the charger. The ID of the transaction to stop. Must be 0 or greater. If not specified, the charger will stop the active transaction. ## Response The response status from the charger (e.g., `Accepted`, `Rejected`). # Remove NANOGRID Configuration Source: https://developer.plugchoice.com/api-reference/charger-settings/delete-nanogrid DELETE /v3/chargers/{charger}/settings/nanogrid Removes the NANOGRID configuration file from the specified charger. Returns a `204 No Content` response on success. The UUID of the charger. # Get Lock Status Source: https://developer.plugchoice.com/api-reference/charger-settings/get-cable-lock GET /v3/chargers/{charger}/settings/lock Returns the current lock status for the specified charger. When locked, the charger is set to `Unavailable` in OCPP and will not accept new charging sessions. The UUID of the charger. ## Response Whether the charger is currently locked (unavailable). Whether the lock can be toggled right now. This is `false` while any connector is in an active state (such as `Charging`, `Preparing`, `Finishing`, `Reserved`, `Faulted`, `SuspendedEV`, or `SuspendedEVSE`). # Get Display & LED Settings Source: https://developer.plugchoice.com/api-reference/charger-settings/get-display-led GET /v3/chargers/{charger}/settings/display-led Returns the current display and LED settings for the specified charger. The UUID of the charger. ## Response A list of configurable display and LED settings. The setting key identifier (e.g., `LightIntensity`). A human-readable label for the setting. The value type (e.g., `integer`, `boolean`). The current value of the setting. The minimum allowed value (for numeric types). The maximum allowed value (for numeric types). # Get NANOGRID Configuration Source: https://developer.plugchoice.com/api-reference/charger-settings/get-nanogrid GET /v3/chargers/{charger}/settings/nanogrid Returns the NANOGRID configuration file status for the specified charger, including whether the charger model supports NANOGRID and the current file contents. The UUID of the charger. ## Response Whether the charger model supports the NANOGRID configuration. Whether a NANOGRID configuration file is currently present on the charger. The current contents of the NANOGRID configuration file. Empty when no file is present. A human-readable error message. Only present when the configuration could not be read, for example when the charger is offline. # Get Plug & Charge Status Source: https://developer.plugchoice.com/api-reference/charger-settings/get-plug-charge GET /v3/chargers/{charger}/settings/plug-charge Returns the current Plug & Charge status for the specified charger. The UUID of the charger. ## Response Whether Plug & Charge is currently enabled. The RFID card UID currently configured for Plug & Charge. May be an empty string when none is set. # Get Public Charging Settings Source: https://developer.plugchoice.com/api-reference/charger-settings/get-public-charging GET /v3/chargers/{charger}/settings/public-charging Returns the public charging (Scan to Pay) settings for the specified charger, including pricing, currency, billing plan, and the connected Stripe account status. The UUID of the charger. ## Response Whether public charging is currently enabled for the charger. The price per kWh in the smallest currency unit (for example, cents). May be `null` when not set. The fixed start fee in the smallest currency unit. Defaults to `0`. The ISO currency code of the connected Stripe account. May be `null` when no account is connected. The public code used to reach the charger's Scan to Pay page. May be `null` when public charging has never been enabled. The full URL of the charger's Scan to Pay page. May be `null` when `public_code` is not set. The pre-authorisation amount charged to the driver, in the smallest currency unit. The configurable pricing limits for the merchant's currency. The maximum allowed price per kWh, in the smallest currency unit. The maximum allowed start fee, in the smallest currency unit. The status of the merchant's connected Stripe account. Whether the merchant has a connected Stripe account. Whether Stripe Connect onboarding has been completed. The name of the merchant team. May be `null`. The billing configuration for public charging. The billing plan. One of `subscription` or `transaction`. May be `null` when never chosen. The transaction fee percentage applied to public charging sessions. The monthly AC socket subscription price, in the smallest currency unit. The monthly DC socket subscription price, in the smallest currency unit. Whether the merchant currently has an active socket subscription. Whether the merchant has a default payment method on file. # Get Socket Lock Status Source: https://developer.plugchoice.com/api-reference/charger-settings/get-socket-lock GET /v3/chargers/{charger}/settings/socket-lock Returns the current socket lock status for the specified charger. When the socket is locked, the charging cable is held in place and cannot be removed. The UUID of the charger. ## Response Whether the socket is currently locked. Whether the socket lock can be toggled right now. This is `true` when the socket is already locked or when a cable is physically inserted (the connector is in a `Preparing`, `Charging`, `SuspendedEV`, `SuspendedEVSE`, or `Finishing` state). A human-readable error message. Only present when the setting could not be read, for example when the charger is offline. When present, `enabled` and `interactable` are returned as `false`. # Set Lock Source: https://developer.plugchoice.com/api-reference/charger-settings/set-cable-lock POST /v3/chargers/{charger}/settings/lock Locks or unlocks the charger. When locked, the charger is set to `Unavailable` in OCPP and will not accept new charging sessions. Returns a `204 No Content` response on success. The UUID of the charger. Set to `true` to lock the charger (make unavailable) or `false` to unlock it (make available). # Set Display & LED Settings Source: https://developer.plugchoice.com/api-reference/charger-settings/set-display-led POST /v3/chargers/{charger}/settings/display-led Updates the display and LED settings for the specified charger. Returns a `204 No Content` response on success. The UUID of the charger. An object of setting key-value pairs. Each key should be a valid setting key (e.g., `LightIntensity`) and the value should be a string. At least one setting is required. Maximum 255 characters per value. # Set NANOGRID Configuration Source: https://developer.plugchoice.com/api-reference/charger-settings/set-nanogrid POST /v3/chargers/{charger}/settings/nanogrid Installs or replaces the NANOGRID configuration file on the specified charger. Returns a `204 No Content` response on success. The UUID of the charger. The contents of the NANOGRID configuration file. Maximum 65535 characters. # Set Plug & Charge Source: https://developer.plugchoice.com/api-reference/charger-settings/set-plug-charge POST /v3/chargers/{charger}/settings/plug-charge Enables or disables Plug & Charge for the specified charger. When enabling, a card UID must be provided. Returns a `204 No Content` response on success. The UUID of the charger. Whether to enable (`true`) or disable (`false`) Plug & Charge. The RFID card UID to use for Plug & Charge. Required when `enabled` is `true`. Maximum 20 characters. # Set Public Charging Settings Source: https://developer.plugchoice.com/api-reference/charger-settings/set-public-charging POST /v3/chargers/{charger}/settings/public-charging Enables or disables public charging (Scan to Pay) for the specified charger and updates its pricing and billing plan. Enabling requires that the organization has public charging enabled and has completed Stripe Connect onboarding. Requires a verified email address. Returns the updated public charging settings on success, in the same shape as [Get Public Charging Settings](/api-reference/charger-settings/get-public-charging). The UUID of the charger. Whether to enable (`true`) or disable (`false`) public charging. The price per kWh in the smallest currency unit (for example, cents). Required when `enabled` is `true`. Must be at least `1` and may not exceed the maximum allowed for the merchant's currency. The fixed start fee in the smallest currency unit. Must be `0` or greater and may not exceed the maximum allowed for the merchant's currency. The billing plan. One of `subscription` or `transaction`. When omitted, the existing plan is kept, otherwise the transaction plan is used. # Set Socket Lock Source: https://developer.plugchoice.com/api-reference/charger-settings/set-socket-lock POST /v3/chargers/{charger}/settings/socket-lock Locks or unlocks the charging socket for the specified charger. When locked, the charging cable is held in place and cannot be removed. Returns a `204 No Content` response on success. The UUID of the charger. Set to `true` to lock the socket or `false` to unlock it. # Set Firmware Auto-Update Source: https://developer.plugchoice.com/api-reference/chargers/auto-update-firmware POST /v3/chargers/{charger}/firmware/auto-update Enables or disables automatic firmware updates for the specified charger. Returns a `204 No Content` response on success. The UUID of the charger. Whether automatic firmware updates should be enabled (`true`) or disabled (`false`). # Create Charger Source: https://developer.plugchoice.com/api-reference/chargers/create-charger POST /v3/chargers Registers a new charger. The charger is assigned to the authenticated user's team. If the user does not have a team, a personal team is automatically created. The unique identity string for the charger (e.g., serial number). Maximum 45 characters. Must be unique across all chargers. The UUID of the team to assign the charger to. Must be a valid UUID of an existing team. The UUID of the location to assign the charger to. Must be a valid UUID of an existing location. ## Response The unique UUID of the charger. The numeric ID of the charger. The unique identity string of the charger. The serial number of the charger. May be `null`. The charger's pincode. Only returned if the authenticated user has sensitive permissions. A user-defined reference for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in Amperes the charger can deliver. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. Whether the charger is a MID-certified meter. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). # Delete Charger Source: https://developer.plugchoice.com/api-reference/chargers/delete-charger DELETE /v3/chargers/{charger} Deletes the specified charger. Returns a `204 No Content` response on success. The UUID of the charger to delete. # Get Charger Source: https://developer.plugchoice.com/api-reference/chargers/get-charger GET /v3/chargers/{charger} Returns the details of a specific charger, including its model and connectors. The UUID of the charger. ## Response The unique UUID of the charger. The numeric ID of the charger. The unique identity string of the charger. The serial number of the charger. May be `null`. The charger's pincode. Only returned if the authenticated user has sensitive permissions. A user-defined reference for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in Amperes the charger can deliver. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. The charger model details. The vendor or manufacturer name. The model name. Whether this is a DC charger. The URL of the model image. May be `null`. The internal model details. Only included when the internal model relationship is loaded. May be `null`. The internal model ID. The internal model name. The internal model SKU. Whether the charger is a MID-certified meter. Derived from the internal model, falling back to the model. May be `null`. The charger's connectors. The internal ID of the connector. The ID of the parent charger. The OCPP connector ID. The current status of the connector. The current error code, if any. Additional error information. The vendor identifier. A vendor-specific error code. The maximum amperage for the connector. The minimum current for the connector. The configured current limit for the connector. Indicates who set the connector's current limit. One of `api` or `user`. May be `null` when no manual limit has been applied. The maximum voltage for the connector. The connector standard (e.g., IEC 62196). The connector format (e.g., Cable, Socket). The power type (e.g., AC\_1\_PHASE, AC\_3\_PHASE, DC). The phase rotation configuration. ISO 8601 timestamp of when the connector was created. ISO 8601 timestamp of when the connector was last updated. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). # Get Firmware Status Source: https://developer.plugchoice.com/api-reference/chargers/get-firmware GET /v3/chargers/{charger}/firmware Returns the firmware overview for the specified charger, including the current version and whether an update is available. The UUID of the charger. ## Response The current firmware version installed on the charger. May be `null`. The latest firmware version available for this charger. May be `null`. Whether a newer firmware version is available for this charger. Whether automatic firmware updates are enabled for this charger. Whether an update can currently be triggered. `false` when no update is available or an update is already in progress. The current firmware update status. One of `idle`, `update_available`, `requested`, `downloading`, `downloaded`, `installing`, `installed`, `up_to_date`, or `failed`. The firmware update progress percentage (0-100). The most recent raw firmware status reported (e.g., `Downloading`, `Installed`, `Requested`). May be `null`. ISO 8601 timestamp of the most recent firmware status. May be `null`. The reason a newer version is unavailable when applicable. One of `up_to_date`, `no_pipeline`, `unknown_version`, or `invalid_version`. May be `null`. # Get Proxy Servers Source: https://developer.plugchoice.com/api-reference/chargers/get-proxy GET /v3/chargers/{charger}/proxy Returns the proxy server configuration for the specified charger. The UUID of the charger. ## Response A list of proxy server entries. The WebSocket URL of the proxy server. The role of this server. Either `ROLE_LEADER` or `ROLE_FOLLOWER`. Whether a password is currently stored for this server. The password value itself is never returned. ISO 8601 timestamp of when the proxy entry was created. ISO 8601 timestamp of when the proxy entry was last updated. # List Chargers Source: https://developer.plugchoice.com/api-reference/chargers/list-chargers GET /v3/chargers Returns a paginated list of chargers accessible to the authenticated user. Each charger includes its associated model. ## Response The unique UUID of the charger. The numeric ID of the charger. The unique identity string of the charger (e.g., serial number). The serial number of the charger. May be `null`. The charger's pincode. Only returned if the authenticated user has sensitive permissions. A user-defined reference or label for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in Amperes the charger can deliver. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. The charger model details. Only included when the model relationship is loaded. The vendor or manufacturer name. The model name. Whether this is a DC charger. The URL of the model image. May be `null`. Whether the charger is a MID-certified meter. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). # Setup Charger Source: https://developer.plugchoice.com/api-reference/chargers/setup-charger POST /v3/chargers/{charger}/setup Configures initial settings for a charger including phases, current limits, and other configuration. The charger will automatically restart after a successful setup. This endpoint is rate limited to 1 request per 60 seconds per charger. The UUID of the charger to set up. The number of phases. Must be `1` or `3`. The maximum current in Amperes. Must be at least 6. The location group ID to assign the charger to. Must reference an existing location group. The electrical network type. One of `IT`, `TT`, `TN`, or `unknown`. The phase rotation configuration. The length must match the number of phases. Valid values for 3 phases: `RST`, `RTS`, `SRT`, `STR`, `TRS`, `TSR`. Valid values for 1 phase: `R`, `S`, `T`. ## Response A success message indicating the charger will restart. Whether the setup is still pending. # Update Charger Source: https://developer.plugchoice.com/api-reference/chargers/update-charger PUT /v3/chargers/{charger} Updates the details of a specific charger. The UUID of the charger to update. A user-defined reference or label for the charger. Maximum 255 characters. Set to `null` (or an empty string) to clear the reference for the resolved team. The UUID of the team the reference applies to. Must be a valid UUID of an existing team accessible for this charger. When omitted, the authenticated user's current team is used. ## Response The unique UUID of the charger. The numeric ID of the charger. The unique identity string of the charger. The serial number of the charger. May be `null`. The charger's pincode. Only returned if the authenticated user has sensitive permissions. The updated reference for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in Amperes the charger can deliver. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. Whether the charger is a MID-certified meter. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). # Update Firmware Source: https://developer.plugchoice.com/api-reference/chargers/update-firmware POST /v3/chargers/{charger}/firmware/update Triggers a firmware update to the latest available version for the specified charger. Returns `202 Accepted` when the update is successfully requested. Returns `422 Unprocessable Entity` with a `message` field when no newer firmware is available, no update track is configured, or the current version cannot be determined. The UUID of the charger to update. ## Response The current firmware version installed on the charger. May be `null`. The target firmware version for the update. May be `null`. Whether a newer firmware version is available for this charger. Whether automatic firmware updates are enabled for this charger. Whether an update can currently be triggered. Always `false` after a successful trigger. The firmware update status. Always `requested` after a successful trigger. The firmware update progress percentage. `12` immediately after a successful trigger. The most recent raw firmware status reported. May be `null`. ISO 8601 timestamp of the most recent firmware status. May be `null`. The reason a newer version is unavailable when applicable. May be `null`. # Update Proxy Servers Source: https://developer.plugchoice.com/api-reference/chargers/update-proxy PUT /v3/chargers/{charger}/proxy Updates the proxy server configuration for the specified charger. There must be exactly one leader across the vendor role and all server entries. The UUID of the charger. The role of the vendor (Plugchoice) connection. Either `ROLE_LEADER` or `ROLE_FOLLOWER`. An array of proxy server configurations. The WebSocket URL of the proxy server. Must use `ws://` or `wss://` protocol. The role of this server. Either `ROLE_LEADER` or `ROLE_FOLLOWER`. Optional credential the charger uses to authenticate to this server. Stored encrypted at rest and never returned by the API. Three-state semantics: * **Omit the field** to preserve the password currently stored for this server (matched by `websocket`). * Pass a **non-empty string** to set or replace the password. * Pass `null` (or an empty string) to clear the stored password. This means partial updates from a UI that does not know existing passwords (e.g. only changing a role) will not wipe credentials. ## Response The updated list of proxy server entries. The WebSocket URL of the proxy server. The role of this server. Whether a password is currently stored for this server. The password value itself is never returned. ISO 8601 timestamp of when the proxy entry was created. ISO 8601 timestamp of when the proxy entry was last updated. # Get Latest Meter Value Source: https://developer.plugchoice.com/api-reference/connectors/get-latest-meter-value GET /v3/chargers/{charger}/connectors/{connector_id}/latest-metervalue Returns the latest OCPP meter value for a specific connector. This includes detailed sampled values for energy, current, voltage, and other measurands. The UUID of the charger. The OCPP connector ID. ## Response The connector ID this meter value belongs to. The ID of the transaction the meter value relates to, when the reading was taken during an active transaction. May be omitted. An array of meter value entries. ISO 8601 timestamp of the measurement. Array of sampled values. The measured value. The context of the reading (e.g., `Trigger`, `Sample.Periodic`). The value format (e.g., `Raw`). The type of measurement (e.g., `Energy.Active.Import.Register`, `Current.Import`, `Voltage`). The phase this value applies to (e.g., `L1`, `L2`, `L3`, `L1-N`). May be `null`. The measurement location (e.g., `Outlet`, `Inlet`). The unit of measurement (e.g., `Wh`, `A`, `V`). # Get Power Usage Source: https://developer.plugchoice.com/api-reference/connectors/get-power-usage GET /v3/chargers/{charger}/connectors/{connector_id}/power-usage Returns the current real-time power usage for a specific connector. Data is retrieved from live measurements. The UUID of the charger. The OCPP connector ID. ## Response ISO 8601 timestamp of when the measurement was taken. Current on phase L1 in Amperes. Displays `-` if not available. Current on phase L2 in Amperes. Displays `-` if not available. Current on phase L3 in Amperes. Displays `-` if not available. Total power consumption in kilowatts. State of charge of the connected vehicle's battery, as a whole-number percentage (0–100). Only reported by chargers that support it (typically DC fast chargers); the field is omitted when unavailable. # Update Connector Source: https://developer.plugchoice.com/api-reference/connectors/update-connector PUT /v3/chargers/{charger}/connectors/{connector_id} Updates the phase rotation and max amperage configuration for a specific connector. The UUID of the charger. The OCPP connector ID. The phase rotation configuration. Valid values for 3 phases: `RST`, `RTS`, `SRT`, `STR`, `TRS`, `TSR`. Valid values for 2 phases: `RS`, `RT`, `SR`, `ST`, `TR`, `TS`. Valid values for 1 phase: `R`, `S`, `T`. The maximum amperage for the connector. Must be at least 1 and may not exceed the charger's configured max current (defaults to 1000 when the charger has no max current set). The minimum charging current for the connector. Must be at least 0 and may not exceed the charger's configured max current (defaults to 1000 when the charger has no max current set). The manual charging speed (current limit) for the connector. Must be at least 0 and may not exceed the charger's configured max current (defaults to 1000 when the charger has no max current set). The values 1, 2, 3, 4, and 5 are not allowed. Setting a current limit is a smart-charging feature and requires the charger to have a Smart license. ## Response The internal ID of the connector. The ID of the parent charger. The OCPP connector ID. The current status of the connector. One of `Available`, `Charging`, `Faulted`, `Finishing`, `Preparing`, `Reserved`, `SuspendedEV`, `SuspendedEVSE`, `Unavailable`. The current error code, if any. Additional error information. The vendor identifier. A vendor-specific error code. The maximum amperage for the connector. The minimum charging current for the connector. The manual charging speed (current limit) for the connector. Indicates who set the connector's current limit. One of `api` or `user`. Set to `user` when the limit is changed through this endpoint. May be `null` when no manual limit has been applied. The maximum voltage for the connector. The connector standard. One of `CHADEMO`, `IEC_62196_T1`, `IEC_62196_T2`, `IEC_62196_T2_COMBO`, `IEC_62196_T3A`, `IEC_62196_T3C`, `TESLA_S`. The connector format. One of `CABLE`, `SOCKET`. The power type. One of `AC_1_PHASE`, `AC_2_PHASE`, `AC_2_PHASE_SPLIT`, `AC_3_PHASE`, `DC`. The phase rotation configuration. ISO 8601 timestamp of when the connector was created. ISO 8601 timestamp of when the connector was last updated. # List Models Source: https://developer.plugchoice.com/api-reference/data/list-models GET /v3/models Returns a list of published charger models, ordered by vendor then name. This endpoint does not require authentication. ## Response Array of model objects. The numeric ID of the model. The vendor name. Resolved from the canonical vendor when the model is linked to one, otherwise the raw vendor string stored on the model. The model name. The customer-facing display name for the model. Can be `null`. Whether the model is a DC charger. Can be `null` if not set. Whether the model has MID-certified metering. Can be `null` if not set. The publicly accessible URL for the model's image, or `null` when no image is set. The expected shape of the model's serial number, or `null` when not configured. Either `numeric` or `alphanumeric`. The exact required length. Only present when `type` is `numeric`. The maximum allowed length. Only present when `type` is `alphanumeric`. An optional prefix prepended to the charger identity for this model (e.g. `VT_`). Can be `null`. The identifier of the associated Intercom help article. Can be `null`. Whether setting up a charger of this model requires a PIN code. Whether the model's setup flow includes a Wi-Fi configuration step. Whether the model is certified. The settings/capabilities supported by this model. `lock` and `autostart` are generic and always `true`; the rest are derived from the model-specific support classes so they can never drift from what the firmware actually supports. Always `true`. Always `true`. Whether the model supports guided setup. Whether the model supports socket locking. Whether the model supports reading the display LED state. Whether the model supports NanoGrid. # List Products Source: https://developer.plugchoice.com/api-reference/data/list-products GET /v3/products Returns a list of all available products (e.g., charger licenses). ## Response Array of product objects. The numeric ID of the product. The product name. The product SKU identifier. Whether the product is currently active and available for purchase. Whether the product is a digital product. The product price, expressed as an integer in minor currency units. # List Providers Source: https://developer.plugchoice.com/api-reference/data/list-providers GET /v3/providers Returns a list of available charging network providers, ordered alphabetically by name. This endpoint does not require authentication. ## Response Array of provider objects. The provider name. The OCPP WebSocket URL for connecting chargers to this provider. # List Tariffs Source: https://developer.plugchoice.com/api-reference/data/list-tariffs GET /v3/tariffs Returns a list of energy tariffs for a specific location. Only tariffs from today onwards are returned. The location identifier to retrieve tariffs for. ## Response Array of tariff objects. The tariff type. The location identifier. ISO 8601 timestamp of when the tariff rate applies. The energy price, expressed as an integer in minor currency units. Whether the price includes tax. # Energy Export Source: https://developer.plugchoice.com/api-reference/insights/energy-export GET /v3/sites/{site}/insights/energy-export Exports energy usage data for a location at 15-minute intervals, including the location power curve and per-charger summary. The UUID of the location. The start date for the export range. Must be a valid date string (e.g., `2024-01-01`). Data is returned from the start of this day. The end date for the export range. Must be a valid date string and equal to or after `started_from`. Data is returned through the end of this day. ## Response The location-level power curve, sampled at 15-minute intervals from site statistics. The timestamp marking the start of the 15-minute interval bucket. The average power draw across the interval, in kilowatts (rounded to 2 decimals). The energy delivered during the interval, in kilowatt-hours (rounded to 4 decimals). A per-charger energy summary derived from completed transactions, ordered by total energy delivered (descending). The OCPP identity of the charger. The viewing team's reference for the charger, or an empty string if none is set. The total energy delivered by the charger over the range, in kilowatt-hours (rounded to 2 decimals). The number of completed transactions for the charger over the range. # List Meter Values Source: https://developer.plugchoice.com/api-reference/meter-values/list-charger-meter-values GET /v3/chargers/{charger}/metervalues Returns a paginated list of historical OCPP meter values for the specified charger. If you only need the most recent meter value, use [Get Latest Meter Value](/api-reference/connectors/get-latest-meter-value) instead. The UUID of the charger. Start date for the query. Format: `Y-m-d H:i:s` (e.g., `2025-01-01 00:00:00`). End date for the query. Format: `Y-m-d H:i:s` (e.g., `2025-12-31 23:59:59`). Filter by measurement context. One of `Interruption.Begin`, `Interruption.End`, `Other`, `Sample.Clock`, `Sample.Periodic`, `Transaction.Begin`, `Transaction.End`, or `Trigger`. Filter by measurand type. One of `Current.Export`, `Current.Import`, `Current.Offered`, `Energy.Active.Export.Register`, `Energy.Active.Import.Register`, `Energy.Reactive.Export.Register`, `Energy.Reactive.Import.Register`, `Energy.Active.Export.Interval`, `Energy.Active.Import.Interval`, `Energy.Reactive.Export.Interval`, `Energy.Reactive.Import.Interval`, `Frequency`, `Power.Active.Export`, `Power.Active.Import`, `Power.Factor`, `Power.Offered`, `Power.Reactive.Export`, `Power.Reactive.Import`, `RPM`, `SoC`, `Temperature`, or `Voltage`. Filter by phase. One of `L1`, `L2`, `L3`, `N`, `L1-N`, `L2-N`, `L3-N`, `L1-L2`, `L2-L3`, or `L3-L1`. Filter by measurement location. One of `Body`, `Inlet`, `Cable`, `Outlet`, or `EV`. Filter by unit. One of `Wh`, `kWh`, `varh`, `kvarh`, `W`, `kW`, `VA`, `kVA`, `var`, `kvar`, `A`, `V`, `Celsius`, `Fahrenheit`, `K`, or `Percent`. Maximum number of results to return. Maximum 10,000. Sort order. Either `asc` or `desc`. ## Response The meter value record ID. The ID of the charger. Deprecated. Use `connector_id` instead. The connector ID this meter value belongs to. Deprecated. Use `transaction_id` instead. The transaction ID this meter value belongs to. May be `null`. ISO 8601 timestamp of the measurement. The measured value as a string. The context of the reading. Deprecated. Always returns `Raw`. The type of measurement. The phase this value applies to. May be `null`. The measurement location. The unit of measurement. # List Logs Source: https://developer.plugchoice.com/api-reference/ocpp-logs/list-charger-logs GET /v3/chargers/{charger}/logs Returns a paginated list of OCPP communication logs for a specific charger. Supports filtering by method, status, destination, date range, and sorting. The UUID of the charger. Filter by OCPP method (e.g., `Heartbeat`, `StartTransaction`, `MeterValues`). Accepts an array or a comma-separated list of values. Filter by log status. One or more of `pending`, `done`, or `failed`. Accepts an array or a comma-separated list of values. Filter by message destination. One or more of `centralsystem` or `charger`. Accepts an array or a comma-separated list of values. Hide high-volume, low-significance logs (`Heartbeat`, `MeterValues`, `SetChargingProfile`, `SecurityEventNotification`, `GetConfiguration`, and `ChangeConfiguration`). Use `1` to hide or `0` to show. Filter logs from this date. Format: `Y-m-d` or `Y-m-d H:i:s`. Filter logs until this date. Must be after or equal to `filter[date_from]`. Format: `Y-m-d` or `Y-m-d H:i:s`. Sort field. Use `created_at` for ascending or `-created_at` for descending (default). Page number for pagination. ## Response The response is a paginated payload (`simplePaginate`, 25 per page). Log entries are returned in the `data` array, alongside the standard pagination fields (`current_page`, `per_page`, `first_page_url`, `prev_page_url`, `next_page_url`, `from`, `to`, `path`) and the additional `filter_options` field described below. The list of log entries. Each entry has the following fields. The log entry ID. The ID of the charger. The status of the OCPP message. One of `pending`, `done`, or `failed`. May be `null`. The OCPP protocol version used. The OCPP method name (e.g., `Heartbeat`, `StartTransaction`, `StatusNotification`). May be `null`. The message destination (`centralsystem` or `charger`). May be `null`. The parameters sent with the OCPP message. Structure varies per OCPP action (e.g., `BootNotification`, `StartTransaction`). The result or response of the OCPP message. Structure varies per OCPP action. May be `null` for pending messages. ISO 8601 timestamp of when the log entry was created. ISO 8601 timestamp of when the log entry was last updated. Available filter options. A list of all available OCPP method names that can be used with the `filter[method]` parameter. # Get Power History Source: https://developer.plugchoice.com/api-reference/power-management/get-power-history GET /v3/sites/{site}/power-history Returns historical power metrics for a branch (location group) or connector. Data is sampled to a maximum of 400 points. Use the `from` and `to` parameters to zoom in on a specific time range for more granular data. When the `from` and `to` parameters are omitted, the default range is the last 7 days. The UUID of the location. The history type. Must be `branch` or `connector`. The entity ID. Use the `site_group_id` when type is `branch`, or the `charger_id` when type is `connector`. The connector ID. Required when `type` is `connector`. Start date/time filter in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`). End date/time filter in ISO 8601 format. Must be after or equal to `from`. ## Response An array of data points, ordered by timestamp. Each point groups its measurands by phase. The ISO 8601 timestamp of the data point. A map of measurand name to value (number) for phase L1. For branch history the measurands are `Current.Meter`, `Current.Available`, `Current.Requested`, and `Current.Allocated`; for connector history they are `Current.Requested`, `Current.Allocated`, and `Current.Import`. Only measurands present for that timestamp are included. The same structure as `L1`, for phase L2. The same structure as `L1`, for phase L3. Metadata describing the returned range and series. The ISO 8601 start of the returned range. The ISO 8601 end of the returned range. The history type, either `branch` or `connector`. The entity ID the data was queried for. The connector ID, or `null` for branch history. The measurands included for this history type. The phases included, always `L1`, `L2`, and `L3`. The total number of distinct timestamps in the requested range before sampling. # Get Power Management Source: https://developer.plugchoice.com/api-reference/power-management/get-power-management GET /v3/sites/{site}/power-management Returns the power management status for the specified location, including the hierarchical group structure, chargers, connectors, and real-time metrics for load management visualization. The UUID of the location. ## Response The power management payload. An array of top-level load balancing group objects. The numeric ID of the group. Whether this is a root-level group. The total available amperage for the group. The electrical network type (e.g., `TT`, `TN`, `IT`). The load balancing method. Peak shaving configuration. Whether peak shaving is enabled. The peak shaving threshold in amps. The attached meter, or `null` if none. The numeric ID of the meter. The UUID of the meter. The meter type. The serial number of the meter. Solar integration settings. Additional amperage from solar. Whether to always charge when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. A map of Redis key names for the group's real-time available, requested, and allocated amperage per phase, plus the `meter` key (or `null` when no meter is attached). An array of charger objects assigned to this group. Each charger has the same structure as the entries in `unattachedChargers`. An array of nested subgroup objects (same structure as group). An array of chargers not assigned to any group. The numeric ID of the charger. The UUID of the charger. The charger's identity label. The connection status of the charger. The maximum current of the charger. Whether the charger has a smart charging license. An array of connector objects for this charger. The numeric ID of the connector. The numeric ID of the parent charger. The OCPP connector ID on the charger. The connector status. The phase rotation (e.g., `RST`). The maximum amperage for the connector. The minimum current for the connector. The configured current limit, or `null`. What set the current limit. One of `api` or `user`, or `null` when not set. The power type of the connector, or `null`. The connector standard, or `null`. The connector format, or `null`. The maximum voltage for the connector, or `null`. A map of Redis key names for the connector's real-time requested/allocated amperage per phase and power usage. A flat array of all location chargers with group assignment info. The numeric ID of the charger. The UUID of the charger. The charger's identity label. The connection status of the charger. The ID of the group the charger is assigned to, or `null`. A map of data keys to their current values for real-time load management metrics (available, requested, and allocated amperage per phase). A map of meter IDs to their current power readings. # Get Smart Charging Source: https://developer.plugchoice.com/api-reference/power-management/get-smart-charging GET /v3/sites/{site}/smart-charging Returns the smart charging configuration for the specified location. The UUID of the location. ## Response The smart charging configuration. The location's configured timezone. The smart charging mode. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The day-ahead pricing strategy. One of `automatic` or `manual`. The day-ahead pricing threshold. The calculated smart mode price for day-ahead pricing. The off-peak start time in `HH:mm` format. The off-peak end time in `HH:mm` format. The selected tariff zone key for zonal day-ahead-pricing markets, or `null`. For example, `GB_C` for the London region. The available tariff zone options for the location's country. Empty for single-zone countries. The tariff zone key (e.g., `GB_C`). The human-readable zone label (e.g., `London`). # Update Smart Charging Source: https://developer.plugchoice.com/api-reference/power-management/update-smart-charging PUT /v3/sites/{site}/smart-charging Updates the smart charging settings for the specified location. The UUID of the location. A valid timezone identifier (e.g., `Europe/Amsterdam`). The smart charging mode. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The day-ahead pricing strategy. One of `automatic` or `manual`. The day-ahead pricing threshold. Required when `day_ahead_pricing_strategy` is `manual` and no threshold has been previously set. The off-peak start time in `HH:mm` format. The off-peak end time in `HH:mm` format. The tariff zone key for zonal day-ahead-pricing markets (e.g., `GB_C`). Must be a valid zone for the location's country, or `null`. ## Response The updated smart charging configuration. The location's configured timezone. The smart charging mode. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The day-ahead pricing strategy. One of `automatic` or `manual`. The day-ahead pricing threshold. The calculated smart mode price for day-ahead pricing. The off-peak start time in `HH:mm` format. The off-peak end time in `HH:mm` format. The selected tariff zone key for zonal day-ahead-pricing markets, or `null`. The available tariff zone options for the location's country. Empty for single-zone countries. The tariff zone key (e.g., `GB_C`). The human-readable zone label (e.g., `London`). # Add Charger Source: https://developer.plugchoice.com/api-reference/site-chargers/add-charger-to-site POST /v3/sites/{site}/chargers Attaches an existing charger to the specified location using its identity and pincode. The UUID of the location. The OCPP identity of the charger to attach. Maximum 255 characters. The pincode of the charger (4–8 digits), as printed on the charger. Send it as a string so any leading zeros are preserved. A number is also accepted for compatibility with clients that cannot send a string, in which case leading zeros are lost in transit (`00503437` becomes `503437`). The pincode is matched on its significant digits, so those requests still resolve to the right charger. ## Response Returns the attached charger. The unique UUID of the charger. The numeric ID of the charger. The charger's OCPP identity string. The charger's serial number. May be `null`. The charger's pincode. Only included when the authenticated user has sensitive access to the charger. A custom reference label for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in amps. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. The charger model details. Only included when the model relationship is loaded. The vendor or manufacturer name. The model name. Whether this is a DC charger. The URL of the model image. May be `null`. The internal model details. Only included when the internal model relationship is loaded, otherwise `null`. The numeric ID of the internal model. The internal model name. The internal model SKU. Whether the charger is MID-certified, derived from its internal or public model. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). An array of connector objects for this charger. Only included when the connectors relationship is loaded. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. # List Chargers Source: https://developer.plugchoice.com/api-reference/site-chargers/list-site-chargers GET /v3/sites/{site}/chargers Returns a paginated list of chargers assigned to the specified location. Includes connector information for each charger. Results are paginated with 25 items per page. The UUID of the location. ## Response The unique UUID of the charger. The numeric ID of the charger. The charger's OCPP identity string. The charger's serial number. May be `null`. The charger's pincode. Only included when the authenticated user has sensitive access to the charger. A custom reference label for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. Additional error information, if any. The vendor identifier. The vendor-specific error code, if any. The charger's firmware version string. The parsed firmware version, or `null` if unparseable. The OCPP server the charger is connected to. ISO 8601 timestamp of the last connection. ISO 8601 timestamp of the last disconnection. ISO 8601 timestamp of the last heartbeat. Whether the charger has a pending setup. Whether the charger setup is completed. Whether the charger is blocked. The maximum current in amps. The charger's active licenses. Whether the smart license is active. Whether the pro license is active. An array of connector objects for this charger. The numeric ID of the connector. The ID of the parent charger. The OCPP connector ID. The current connector status. The current connector error code, if any. May be `null`. Additional connector error information. May be `null`. The vendor identifier for the connector. May be `null`. The vendor-specific error code for the connector. May be `null`. The maximum amperage of the connector. The minimum current of the connector in amps. The current limit applied to the connector in amps. Identifies what is currently managing the connector's current limit. May be `null`. The maximum voltage of the connector. The connector standard (e.g., IEC 62196). The connector format (e.g., Socket, Cable). The power type (e.g., AC\_1\_PHASE, AC\_3\_PHASE, DC). The phase rotation configuration. ISO 8601 timestamp of when the connector was created. ISO 8601 timestamp of when the connector was last updated. The ID of the charger model. May be `null`. The charger model details. Only included when the model relationship is loaded. The vendor or manufacturer name. The model name. Whether this is a DC charger. The URL of the model image. May be `null`. The internal model details. Only included when the internal model relationship is loaded, otherwise `null`. The numeric ID of the internal model. The internal model name. The internal model SKU. Whether the charger is MID-certified, derived from its internal or public model. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. # Move Charger Source: https://developer.plugchoice.com/api-reference/site-chargers/move-charger PATCH /v3/sites/{site}/chargers/{charger}/move Moves a charger to a different location and resets its configuration. You must have sensitive access to both the source and target locations. The UUID of the current location. The UUID of the charger to move. The UUID of the target location to move the charger to. Must be an existing location and cannot be the same as the current location. ## Response Returns the moved charger. The unique UUID of the charger. The numeric ID of the charger. The charger's OCPP identity string. The charger's serial number. May be `null`. The charger's pincode. Only included when the authenticated user has sensitive access to the charger. A custom reference label for the charger. May be `null`. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. May be `null`. Additional error information. May be `null`. The vendor identifier. May be `null`. A vendor-specific error code. May be `null`. The raw firmware version string. May be `null`. The parsed and normalized firmware version. May be `null`. The OCPP server the charger is connected to. May be `null`. ISO 8601 timestamp of the last connection. May be `null`. ISO 8601 timestamp of the last disconnection. May be `null`. ISO 8601 timestamp of the last heartbeat. May be `null`. Whether the charger has a pending setup operation. Whether the charger has completed initial setup. Whether the charger is blocked. The maximum current in amps. The charger's active licenses. Whether the smart charging license is active. Whether the pro license is active. The ID of the charger model. May be `null`. The charger model details. Only included when the model relationship is loaded. The vendor or manufacturer name. The model name. Whether this is a DC charger. The URL of the model image. May be `null`. The internal model details. Only included when the internal model relationship is loaded, otherwise `null`. The numeric ID of the internal model. The internal model name. The internal model SKU. Whether the charger is MID-certified, derived from its internal or public model. May be `null`. The authenticated user's permissions for this charger. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., pincode, transactions). Whether the user has full control (e.g., delete, transfer). An array of connector objects for this charger. Only included when the connectors relationship is loaded. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. # Reassign Charger Source: https://developer.plugchoice.com/api-reference/site-chargers/reassign-charger PATCH /v3/sites/{site}/chargers/{charger}/reassign Moves a charger to a different load balancing group within the same location. The UUID of the location. The UUID of the charger. The ID of the target group or subgroup to reassign the charger to. ## Response A confirmation message indicating the charger was reassigned successfully. # Remove Charger Source: https://developer.plugchoice.com/api-reference/site-chargers/remove-charger-from-site DELETE /v3/sites/{site}/chargers/{charger} Detaches a charger from the specified location. Returns a `204 No Content` response on success. The UUID of the location. The UUID of the charger. The UUID of the team to reassign the charger to after detaching. Must be a valid UUID. # List Connectors Source: https://developer.plugchoice.com/api-reference/site-connectors/list-site-connectors GET /v3/sites/{site}/connectors Returns a paginated list of all connectors across all chargers for the specified location. Each connector includes its parent charger information. Results are paginated with 25 items per page. The UUID of the location. ## Response The numeric ID of the connector. The ID of the parent charger. The OCPP connector ID. The current connector status. The current error code, if any. Additional error information, if any. The vendor identifier. The vendor-specific error code, if any. The maximum amperage of the connector. The minimum current of the connector. The current limit of the connector. Identifies what is currently managing the connector's current limit. May be `null`. The maximum voltage of the connector. The connector standard (e.g., IEC 62196). The connector format (e.g., Socket, Cable). The power type (e.g., AC\_1\_PHASE, AC\_3\_PHASE, DC). The phase rotation configuration. The parent charger object. The unique UUID of the charger. The numeric ID of the charger. The charger's OCPP identity string. The charger's serial number. The charger's pincode. Only included when the authenticated user has permission to view sensitive data. A custom reference label for the charger, or `null` if none is set. The current connection status of the charger. The current OCPP status of the charger. The current error code, if any. Additional error information, if any. The vendor identifier. The vendor-specific error code, if any. The charger's firmware version string. The parsed firmware version, or `null` if unparseable. The OCPP server the charger is connected to. ISO 8601 timestamp of the last connection. ISO 8601 timestamp of the last disconnection. ISO 8601 timestamp of the last heartbeat. Whether the charger has a pending setup. Whether the charger setup is completed. Whether the charger is blocked. The maximum current in amps. ISO 8601 timestamp of when the charger was created. ISO 8601 timestamp of when the charger was last updated. The charger's active licenses. Whether the smart license is active. Whether the pro license is active. The ID of the charger's model. Whether the charger is a MID-certified (metering compliant) model. The authenticated user's permissions for this charger. ISO 8601 timestamp of when the connector was created. ISO 8601 timestamp of when the connector was last updated. # Assign Chargers to Group Source: https://developer.plugchoice.com/api-reference/site-groups/assign-chargers-to-group POST /v3/sites/{site}/groups/{siteGroup}/chargers Assigns multiple chargers to the specified load balancing group. The UUID of the location. The ID of the group to assign chargers to. An array of charger UUIDs to assign to the group. Must contain at least one UUID. ## Response Returns the group object the chargers were assigned to. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Create Group Source: https://developer.plugchoice.com/api-reference/site-groups/create-group POST /v3/sites/{site}/groups Creates a new load balancing group for the specified location. If a group already exists, it will be deleted and replaced with the new one. The UUID of the location. The electrical network type. Must be one of: `IT`, `TT`, `TN`, `unknown`. A value of `unknown` is stored as `TT`. The total available amperage for the group. Minimum value is `6`. The UUID of a meter to attach to the group. Cannot be used together with `meter_id`. The numeric ID of a meter to attach to the group. Cannot be used together with `meter_uuid`. ## Response Returns the created group object. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Create Subgroup Source: https://developer.plugchoice.com/api-reference/site-groups/create-subgroup POST /v3/sites/{site}/groups/{siteGroup}/subgroups Creates a new subgroup under an existing load balancing group. Optionally assigns chargers to the new subgroup. The UUID of the location. The ID of the parent group. The total available amperage for the subgroup. Minimum value is `1`. An array of charger UUIDs to assign to the new subgroup. ## Response Returns the created subgroup object. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Delete All Groups Source: https://developer.plugchoice.com/api-reference/site-groups/delete-all-groups DELETE /v3/sites/{site}/groups Deletes all load balancing groups for the specified location. Returns a `204 No Content` response on success. The UUID of the location. # Delete Group Source: https://developer.plugchoice.com/api-reference/site-groups/delete-group DELETE /v3/sites/{site}/groups/{siteGroup} Deletes a single load balancing group from the specified location. Returns a `204 No Content` response on success. The UUID of the location. The ID of the group to delete. # Get Group Meter Source: https://developer.plugchoice.com/api-reference/site-groups/get-group-meter GET /v3/sites/{site}/groups/{siteGroup}/meter Returns the meter readings for the specified group. Returns a `404` error if no meter is attached to the group. The UUID of the location. The ID of the group. ## Response The unique UUID of the meter. The numeric ID of the meter. The meter type. The latest real-time meter readings. Current on phase L1 in amps. Current on phase L2 in amps. Current on phase L3 in amps. Timestamp of the last meter reading. Calculated power information for the meter. May be `null` when no reading is available, or a string message when power information cannot be retrieved for the meter. Net active power in watts (positive when consuming, negative when exporting). The unit of the `value` field. Always `W`. Per-phase current in milliamps (negative when returning to the grid). Current on phase L1 in milliamps. May be `null`. Current on phase L2 in milliamps. May be `null`. Current on phase L3 in milliamps. May be `null`. Per-phase voltage in volts. Voltage on phase L1 in volts. May be `null`. Voltage on phase L2 in volts. May be `null`. Voltage on phase L3 in volts. May be `null`. Timestamp of the power reading. ISO 8601 timestamp of when the meter was created. ISO 8601 timestamp of when the meter was last updated. # List Groups Source: https://developer.plugchoice.com/api-reference/site-groups/list-groups GET /v3/sites/{site}/groups Returns a list of load balancing groups for the specified location. Returns up to 25 groups. The UUID of the location. ## Response The response is an array of group objects. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Reassign Group Source: https://developer.plugchoice.com/api-reference/site-groups/reassign-group PATCH /v3/sites/{site}/groups/{siteGroup}/reassign Moves a group to a different parent group within the same location. A group cannot be assigned as its own parent. The UUID of the location. The ID of the group to reassign. The ID of the new parent group. Cannot be the same as the group being reassigned. ## Response Returns the reassigned group object. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Update Group Source: https://developer.plugchoice.com/api-reference/site-groups/update-group PUT /v3/sites/{site}/groups/{siteGroup} Updates an existing load balancing group or subgroup. All fields are optional; only provided fields will be updated. The UUID of the location. The ID of the group or subgroup. The total available amperage for the group. Minimum value is `1`. The electrical network type. One of `TN`, `TT`, or `IT`. The load balancing method. One of `boost` or `solar`. The UUID of a meter to attach to the group. Set to `true` to remove the currently attached meter. Additional amperage from solar. Minimum value is `0`. Whether to always allow charging when solar is available. The minimum amperage to allocate when solar always charge is enabled. Minimum value is `0`. Whether to enable charging when solar export is detected. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. Minimum value is `0`. ## Response Returns the updated group object. The numeric ID of the group. The numeric ID of the location this group belongs to. The ID of the parent group, or `null` if this is a root group. The ID of the attached meter, or `null`. The total available amperage for the group. The electrical network type. One of `TN`, `TT`, or `IT`. May be `null`. The load balancing method. One of `boost` or `solar`. Additional amperage from solar. Whether to always allow charging when solar is available. Minimum amperage when solar always charge is enabled. Whether to charge on solar export. Whether peak shaving is enabled for this group. The peak shaving threshold in amps. ISO 8601 timestamp of when the group was created. ISO 8601 timestamp of when the group was last updated. # Create Location Source: https://developer.plugchoice.com/api-reference/sites/create-site POST /v3/sites Creates a new location and assigns it to the authenticated user's team. If the user does not have a team, a personal team is automatically created. The UUID of the team to assign the location to. Must be a team the authenticated user belongs to. If omitted, the location is assigned to the user's first team. The name of the location. Maximum 255 characters. The street name. Maximum 255 characters. The house number. Must be 0 or greater. The house number addition (e.g., "A", "B"). Maximum 255 characters. The postal code. Maximum 255 characters. The city name. Maximum 255 characters. The ISO 3166-1 alpha-2 country code (e.g., "NL", "DE"). Maximum 2 characters. Whether the location's coordinates are set manually. When `true`, `latitude` and `longitude` are required; otherwise the coordinates are geocoded from the address. The latitude of the location. Must be between -90 and 90. Required when `manual_coordinates` is `true`. The longitude of the location. Must be between -180 and 180. Required when `manual_coordinates` is `true`. ## Response The unique UUID of the location. The numeric ID of the location. The name of the location. The full formatted address of the location. The street name. The postal code. The house number. The house number addition. May be `null`. The city name. The ISO 3166-1 alpha-2 country code. The tariff zone key used for day-ahead pricing lookups. May be `null`. The latitude of the location. May be `null`. The longitude of the location. May be `null`. Whether the location's coordinates were set manually rather than geocoded automatically. The access level of the location. One of `closed`, `app_users`, or `roaming`. The smart charging mode of the location. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The number of chargers assigned to this location. The location's available capabilities based on licensing. Whether smart charging is available. Load management capabilities. Whether dynamic load management is available. Whether peak shaving is available. Whether solar integration is available. ISO 8601 timestamp of when the location was created. ISO 8601 timestamp of when the location was last updated. The authenticated user's permissions for this location. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., cards, transactions). Whether the user has full control (e.g., delete, transfer ownership). # Delete Location Source: https://developer.plugchoice.com/api-reference/sites/delete-site DELETE /v3/sites/{site} Deletes the specified location. Returns a `204 No Content` response on success. The UUID of the location to delete. The UUID of the team that owns the location. # Get Location Source: https://developer.plugchoice.com/api-reference/sites/get-site GET /v3/sites/{site} Returns the details of a specific location. The UUID of the location. ## Response The unique UUID of the location. The numeric ID of the location. The name of the location. The full formatted address of the location. The street name. The postal code. The house number. The house number addition. May be `null`. The city name. The ISO 3166-1 alpha-2 country code. The tariff zone key used for day-ahead pricing lookups. May be `null`. The latitude of the location. May be `null`. The longitude of the location. May be `null`. Whether the location's coordinates were set manually rather than geocoded automatically. The access level of the location. One of `closed`, `app_users`, or `roaming`. The smart charging mode of the location. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The number of chargers assigned to this location. The location's available capabilities based on licensing. Whether smart charging is available. Load management capabilities. Whether dynamic load management is available. Whether peak shaving is available. Whether solar integration is available. ISO 8601 timestamp of when the location was created. ISO 8601 timestamp of when the location was last updated. The authenticated user's permissions for this location. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., cards, transactions). Whether the user has full control (e.g., delete, transfer ownership). # List Locations Source: https://developer.plugchoice.com/api-reference/sites/list-sites GET /v3/sites Returns a paginated list of locations accessible to the authenticated user. Filter locations by team identifier. Search locations by name or address. ## Response The unique UUID of the location. The numeric ID of the location. The name of the location. The full formatted address of the location. The street name. The postal code. The house number. The house number addition (e.g., "A", "B"). May be `null`. The city name. The ISO 3166-1 alpha-2 country code. The tariff zone key used for day-ahead pricing lookups. May be `null`. The latitude of the location. May be `null`. The longitude of the location. May be `null`. Whether the location's coordinates were set manually rather than geocoded automatically. The access level of the location. One of `closed`, `app_users`, or `roaming`. The smart charging mode of the location. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The number of chargers assigned to this location. The location's available capabilities based on licensing. Whether smart charging is available. Load management capabilities. Whether dynamic load management is available. Whether peak shaving is available. Whether solar integration is available. ISO 8601 timestamp of when the location was created. ISO 8601 timestamp of when the location was last updated. The authenticated user's permissions for this location. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., cards, transactions). Whether the user has full control (e.g., delete, transfer ownership). # Update Location Source: https://developer.plugchoice.com/api-reference/sites/update-site PUT /v3/sites/{site} Updates the details of a specific location. All fields are optional; only the fields provided will be updated. The UUID of the location to update. The name of the location. Maximum 255 characters. The street name. Maximum 255 characters. The house number. Must be 0 or greater. The house number addition (e.g., "A", "B"). Maximum 255 characters. The postal code. Maximum 255 characters. The city name. Maximum 255 characters. The ISO 3166-1 alpha-2 country code (e.g., "NL", "DE"). Maximum 2 characters. The access level of the location. One of `closed`, `app_users`, or `roaming`. Setting `app_users` or `roaming` requires the current team to be an admin team. Whether the location's coordinates are set manually. When `true`, `latitude` and `longitude` are required; otherwise the coordinates are geocoded from the address. The latitude of the location. Must be between -90 and 90. Required when `manual_coordinates` is `true`. The longitude of the location. Must be between -180 and 180. Required when `manual_coordinates` is `true`. ## Response The unique UUID of the location. The numeric ID of the location. The name of the location. The full formatted address of the location. The street name. The postal code. The house number. The house number addition. May be `null`. The city name. The ISO 3166-1 alpha-2 country code. The tariff zone key used for day-ahead pricing lookups. May be `null`. The latitude of the location. May be `null`. The longitude of the location. May be `null`. Whether the location's coordinates were set manually rather than geocoded automatically. The access level of the location. One of `closed`, `app_users`, or `roaming`. The smart charging mode of the location. One of `disabled`, `off_peak`, or `day_ahead_pricing`. The number of chargers assigned to this location. The location's available capabilities based on licensing. Whether smart charging is available. Load management capabilities. Whether dynamic load management is available. Whether peak shaving is available. Whether solar integration is available. ISO 8601 timestamp of when the location was created. ISO 8601 timestamp of when the location was last updated. The authenticated user's permissions for this location. Whether the user has basic read access. Whether the user has access to sensitive data (e.g., cards, transactions). Whether the user has full control (e.g., delete, transfer ownership). # List Chargers Source: https://developer.plugchoice.com/api-reference/team-chargers/list-team-chargers GET /v3/teams/{team}/chargers Returns a paginated list of chargers belonging to the specified team, with filtering and sorting support. The UUID of the team. Filter by charger identity, serial number, or team reference. Filter by connection status. One of `online`, `offline`, or `never_seen`. Filter by charger status. One of `Available`, `Charging`, `Faulted`, `Finishing`, `Preparing`, `Reserved`, `SuspendedEV`, `SuspendedEVSE`, or `Unavailable`. Filter by connector status. One of `Available`, `Charging`, `Faulted`, `Finishing`, `Preparing`, `Reserved`, `SuspendedEV`, `SuspendedEVSE`, or `Unavailable`. Accepts a single value or an array. Filter by charger vendor. Accepts a single value or an array. Filter by charger model name. Accepts a single value or an array. Filter by firmware version. Matches partially. Filter by license type. One of `basic`, `smart`, or `pro`. Accepts a single value or an array. Filter by location UUID. Accepts a single value or an array. Sort field. One of `identity`, `connection_status`, `status`, `created_at`, `firmware_version`, or `model`. Prefix with `-` for descending order. Defaults to `-created_at`. Page number for pagination. ## Response Array of charger objects. The unique UUID of the charger. The charger's identity string. The charger's serial number. May be `null`. The team's reference for this charger. May be `null`. The connection status (`online`, `offline`, or `never_seen`). The charger status. One of `Available`, `Charging`, `Faulted`, `Finishing`, `Preparing`, `Reserved`, `SuspendedEV`, `SuspendedEVSE`, or `Unavailable`. The charger's firmware version. May be `null`. License status for the charger. Whether the smart license is active. Whether the pro license is active. The charger model information. The charger vendor name. The charger model name. Internal model details. The internal model name. The internal model SKU. The location assigned to this charger. The location UUID. The location name. The charger's connectors. Array of connector objects. The connector ID. The OCPP connector ID. The connector status. The connector error code, if any. May be `null`. Additional information about the connector error. May be `null`. The vendor identifier reported for the connector. May be `null`. The vendor-specific error code for the connector. May be `null`. Available filter options based on the current dataset. Available connection status values. Available charger status values. Available connector status values. Available vendor names. Available model names. Available locations, each as an object with `value` (location UUID) and `label` (location name). Available license type values (`basic`, `smart`, `pro`). # List Locations Source: https://developer.plugchoice.com/api-reference/team-sites/list-team-sites GET /v3/teams/{team}/sites Returns a paginated list of locations belonging to the specified team, with filtering and sorting support. The UUID of the team. Filter by location name or address. Filter by ISO 3166-1 alpha-2 country code (e.g., `NL`, `DE`, `BE`). Filter by smart charging mode. One of `disabled`, `day_ahead_pricing`, or `off_peak`. Sort field. One of `name`, `country`, `chargers_count`, or `created_at`. Prefix with `-` for descending order. Defaults to `-created_at`. Page number for pagination. ## Response Array of location objects. The unique UUID of the location. The location name. The full formatted address. The street name. The postal code. The house number. The house number addition (e.g., "A", "B"). May be `null`. The city name. The ISO 3166-1 alpha-2 country code. The latitude coordinate of the location. May be `null`. The longitude coordinate of the location. May be `null`. Whether the coordinates were set manually rather than geocoded. The smart charging mode (`disabled`, `day_ahead_pricing`, or `off_peak`). The number of chargers at this location. ISO 8601 timestamp of when the location was created. The authenticated user's permissions for this location. Whether the user has basic access to the location. Whether the user has access to sensitive location data. Whether the user has full access to the location. Available filter options based on the current dataset. Available country codes. Available smart charging mode values. # Create Team Source: https://developer.plugchoice.com/api-reference/teams/create-team POST /v3/teams Creates a new team for the authenticated user. The name of the team. Maximum 255 characters. The contact email address for the team. Must be a valid email. Maximum 255 characters. Accepted for backwards compatibility with older clients. One of `personal` or `business`. This value is no longer stored and has no effect. ## Response The unique UUID of the team. The numeric ID of the team. The team name. The URL-friendly slug of the team. The team's contact email address. ISO 8601 timestamp of when the team was created. ISO 8601 timestamp of when the team was last updated. # Delete Team Source: https://developer.plugchoice.com/api-reference/teams/delete-team DELETE /v3/teams/{team} Deletes the specified team. Returns a `204 No Content` response on success. The UUID of the team to delete. # List Teams Source: https://developer.plugchoice.com/api-reference/teams/list-teams GET /v3/teams Returns a list of all teams the authenticated user belongs to. ## Response Array of team objects. The unique UUID of the team. The numeric ID of the team. The team name. The URL-friendly slug of the team. The team's contact email address. ISO 8601 timestamp of when the team was created. ISO 8601 timestamp of when the team was last updated. # List Transactions Source: https://developer.plugchoice.com/api-reference/transactions/list-charger-transactions GET /v3/chargers/{charger}/transactions Returns a paginated list of transactions for a specific charger. The UUID of the charger. Maximum number of transactions to return. Between 1 and 10,000. Filter by transaction status. One of `active` or `finished`. Filter transactions started from this date. ISO 8601 date format. Filter transactions stopped until this date. Must be after or equal to `filter[started_from]`. ISO 8601 date format. Sort field. One of `created_at`, `started_at`, `stopped_at`, `total_kwh`, `meter_start`, or `meter_stop`. Prefix with `-` for descending order. Defaults to `-started_at`. ## Response The transaction ID. The ID of the charger. The ID of the connector used. The reservation ID, if applicable. May be `null`. The RFID tag or token used to authorize the transaction. The meter reading at the start of the transaction in Wh. The meter reading at the end of the transaction in Wh. May be `null` for active transactions. The total energy consumed in kWh. ISO 8601 timestamp of when the transaction started. ISO 8601 timestamp of when the transaction stopped. May be `null` for active transactions. The reason the transaction was stopped (e.g., `Remote`, `EVDisconnected`). May be `null`. Whether the transaction is considered valid. May be `null` if not yet determined. The charger associated with this transaction. The UUID of the charger. The Chargepoint ID of the charger. The serial number of the charger. May be `null`. The reference label of the charger. May be `null`. The connector used for this transaction. The OCPP connector ID. ISO 8601 timestamp of when the transaction record was created. ISO 8601 timestamp of when the transaction record was last updated. # List Transactions Source: https://developer.plugchoice.com/api-reference/transactions/list-site-transactions GET /v3/sites/{site}/transactions Returns a paginated list of transactions for all chargers at a specific location. Includes the total energy consumption across the location. The UUID of the location. Maximum number of transactions to return. Between 1 and 10,000. Filter by transaction status. One of `active` or `finished`. Filter by a specific charger UUID. Filter transactions started from this date. ISO 8601 date format. Filter transactions stopped until this date. Must be after or equal to `filter[started_from]`. ISO 8601 date format. Filter by exact RFID tag or token. Maximum 20 characters. Sort field. One of `created_at`, `started_at`, `stopped_at`, `total_kwh`, `meter_start`, or `meter_stop`. Prefix with `-` for descending order. Defaults to `-started_at`. ## Response The transaction ID. The ID of the charger. The ID of the connector used. The reservation ID, if applicable. May be `null`. The RFID tag or token used to authorize the transaction. The meter reading at the start of the transaction in Wh. The meter reading at the end of the transaction in Wh. May be `null` for active transactions. The total energy consumed in kWh. ISO 8601 timestamp of when the transaction started. ISO 8601 timestamp of when the transaction stopped. May be `null` for active transactions. The reason the transaction was stopped. May be `null`. Whether the transaction is considered valid. May be `null` if not yet determined. The charger associated with this transaction. The UUID of the charger. The Chargepoint ID of the charger. The serial number of the charger. May be `null`. The reference label of the charger. May be `null`. The connector used for this transaction. The OCPP connector ID. ISO 8601 timestamp of when the transaction record was created. ISO 8601 timestamp of when the transaction record was last updated. The response includes an additional top-level field: The total energy consumption in kWh across all chargers at the location. # List Team Transactions Source: https://developer.plugchoice.com/api-reference/transactions/list-team-transactions GET /v3/teams/{team}/transactions Returns a paginated list of transactions across all chargers the team has sensitive access to. Uses cursor-based pagination (simple pagination) for infinite scroll support. The UUID of the team. Filter by transaction status. One of `active` or `finished`. Search by transaction ID (numeric), Card UID, or Chargepoint ID. Sort field. One of `started_at`, `stopped_at`, `total_kwh`, `meter_start`, or `meter_stop`. Prefix with `-` for descending order. Defaults to `-started_at`. Page number for pagination. 25 results per page. ## Response Array of transaction objects. The transaction ID. The transaction status. One of `active` or `finished`. The charger associated with this transaction. May be `null`. The UUID of the charger. The Chargepoint ID of the charger. The reference label of the charger. May be `null`. The location the charger belongs to. May be `null`. The UUID of the location. The name of the location. Whether the charger model is MID certified. May be `null` if unknown. The OCPP connector ID used for this transaction. May be `null`. The RFID tag or token used to authorize the transaction. ISO 8601 timestamp of when the transaction started. ISO 8601 timestamp of when the transaction stopped. `null` for active transactions. The meter reading at the start of the transaction in Wh. The meter reading at the end of the transaction in Wh. `null` for active transactions. The total energy consumed in kWh, rounded to 2 decimal places. The reason the transaction was stopped (e.g., `Local`, `Remote`, `EVDisconnected`). `null` for active transactions. Available filter options. Available status filter values (`active`, `finished`). # Delete User Source: https://developer.plugchoice.com/api-reference/users/delete-user DELETE /v3/user Sends an email to the authenticated user with a link to delete their account. Returns a `204 No Content` response on success. # Get Current User Source: https://developer.plugchoice.com/api-reference/users/get-current-user GET /v3/user Returns the authenticated user's account details. ## Response The unique UUID of the user. The numeric ID of the user. The user's full name. The user's email address. Whether the user has verified their email address. Onboarding status for the user. Whether the user still has a pending onboarding profile to complete. The next onboarding step to complete, or `null` when none is pending. One of `company` or `tailor`. Gravatar URL for the user's avatar, based on their email address. Credentials used to identify the user in Intercom. Signed JWT identifying the user to Intercom. HMAC identity verification hash for the Android SDK. HMAC identity verification hash for the iOS SDK. HMAC identity verification hash for the web SDK. ISO 8601 timestamp of when the user was created. ISO 8601 timestamp of when the user was last updated. # Authentication Source: https://developer.plugchoice.com/guides/authentication Authenticate with the Plugchoice API using OAuth 2.0 or personal access tokens. All API requests must include a bearer token in the `Authorization` header: ``` Authorization: Bearer YOUR_API_TOKEN ``` ## Personal access tokens The simplest way to authenticate is with a personal access token. Generate one from your [dashboard settings](https://app.plugchoice.com/settings/personal-access-tokens). Navigate to **Settings > Personal Access Tokens** in the Plugchoice dashboard. Click **Create Token**, give it a descriptive name, and copy the token value. The token is only shown once. Include the token in the `Authorization` header of your API requests. ```bash theme={null} curl https://app.plugchoice.com/api/v3/user \ -H "Authorization: Bearer your_personal_access_token" ``` ## OAuth 2.0 For third-party integrations, Plugchoice supports OAuth 2.0. The following grant types are available: | Grant type | Use case | | ------------------ | -------------------------------------------------- | | Authorization code | Web apps that need user authorization | | Client credentials | Server-to-server communication | | Refresh token | Renewing expired access tokens | | Device code | Devices without a browser (e.g., charger displays) | ### Authorization code flow Redirect the user to the authorization endpoint: ``` GET https://app.plugchoice.com/oauth/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=YOUR_REDIRECT_URI &response_type=code &scope= ``` After the user grants access, exchange the authorization code for tokens: ```bash theme={null} curl -X POST https://app.plugchoice.com/oauth/token \ -d grant_type=authorization_code \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET \ -d redirect_uri=YOUR_REDIRECT_URI \ -d code=AUTHORIZATION_CODE ``` Use the returned `access_token` in the `Authorization` header: ```json theme={null} { "token_type": "Bearer", "expires_in": 31536000, "access_token": "eyJ0...", "refresh_token": "def5..." } ``` ### Client credentials flow For server-to-server integrations that don't require user authorization: ```bash theme={null} curl -X POST https://app.plugchoice.com/oauth/token \ -d grant_type=client_credentials \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET \ -d scope= ``` ### Refreshing tokens Use a refresh token to obtain a new access token: ```bash theme={null} curl -X POST https://app.plugchoice.com/oauth/token \ -d grant_type=refresh_token \ -d client_id=YOUR_CLIENT_ID \ -d client_secret=YOUR_CLIENT_SECRET \ -d refresh_token=YOUR_REFRESH_TOKEN ``` ### Revoking tokens Revoke an authorized access token when it's no longer needed by deleting it by ID: ```bash theme={null} curl -X DELETE https://app.plugchoice.com/oauth/tokens/TOKEN_ID \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` Keep your client secret confidential. Never expose it in client-side code or public repositories. # Errors Source: https://developer.plugchoice.com/guides/errors How the Plugchoice API communicates errors and HTTP status codes. The Plugchoice API uses standard HTTP status codes and returns JSON error responses. ## Error response format All error responses include a `message` field: ```json theme={null} { "message": "The given data was invalid." } ``` Validation errors (422) include field-level details in the `errors` field: ```json theme={null} { "message": "The given data was invalid.", "errors": { "name": ["The name field is required."], "email": ["The email must be a valid email address."] } } ``` ## HTTP status codes | Code | Description | | ----- | -------------------------------------------------------------------- | | `200` | OK - Request succeeded | | `201` | Created - Resource created successfully | | `204` | No Content - Request succeeded with no response body (e.g., deletes) | | `400` | Bad Request - Malformed request | | `401` | Unauthorized - Missing or invalid authentication token | | `403` | Forbidden - Valid token but insufficient permissions | | `404` | Not Found - Resource does not exist | | `422` | Unprocessable Entity - Validation errors in request body | | `429` | Too Many Requests - Rate limit exceeded | | `500` | Internal Server Error - Unexpected server error | | `504` | Gateway Timeout - The charger could not be reached in time | ## Common error scenarios ### Authentication errors (401) Returned when no token is provided or the token is expired/revoked: ```json theme={null} { "message": "Unauthenticated." } ``` ### Authorization errors (403) Returned when the authenticated user lacks permission for the requested action: ```json theme={null} { "message": "This action is unauthorized." } ``` ### Charger timeout (504) Some charger actions communicate with the physical charger in real-time. If the charger doesn't respond within the timeout period, a 504 is returned: ```json theme={null} { "message": "Unable to communicate with the charger. Please check the connection and try again." } ``` This does not necessarily mean the action failed - the charger may still execute the command. # Pagination Source: https://developer.plugchoice.com/guides/pagination Navigate large result sets with page-based pagination. List endpoints return paginated results with 25 items per page by default. ## Request Use the `page` query parameter to navigate through pages: ```bash theme={null} curl https://app.plugchoice.com/api/v3/chargers?page=2 \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ## Response format Paginated responses include `data`, `links`, and `meta` fields: ```json theme={null} { "data": [ { "uuid": "abc-123", "identity": "CHARGER-001", ... }, { "uuid": "def-456", "identity": "CHARGER-002", ... } ], "links": { "first": "https://app.plugchoice.com/api/v3/chargers?page=1", "last": null, "prev": "https://app.plugchoice.com/api/v3/chargers?page=1", "next": "https://app.plugchoice.com/api/v3/chargers?page=3" }, "meta": { "current_page": 2, "from": 26, "path": "https://app.plugchoice.com/api/v3/chargers", "per_page": 25, "to": 50 } } ``` ## Fields | Field | Description | | ------------------- | -------------------------------------------------------- | | `data` | Array of resources for the current page | | `links.first` | URL to the first page | | `links.last` | URL to the last page (may be `null`) | | `links.prev` | URL to the previous page, or `null` if on the first page | | `links.next` | URL to the next page, or `null` if on the last page | | `meta.current_page` | Current page number | | `meta.from` | Index of the first item on this page | | `meta.to` | Index of the last item on this page | | `meta.per_page` | Number of items per page | ## Iterating through pages To fetch all results, follow the `links.next` URL until it returns `null`: ```javascript theme={null} let url = 'https://app.plugchoice.com/api/v3/chargers'; const allChargers = []; while (url) { const response = await fetch(url, { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }); const json = await response.json(); allChargers.push(...json.data); url = json.links.next; } ``` # Rate Limiting Source: https://developer.plugchoice.com/guides/rate-limiting Understand API rate limits and how to handle them. The Plugchoice API enforces rate limits to ensure fair usage and platform stability. ## Default limits | Scope | Limit | | ----------------------------------------------------------------------- | -------------------------------------------------------- | | Global API | 500 requests per minute per authenticated user | | Location invitations | 5 requests per minute | | Chargee meter | 5 requests per minute | | Public charging: start session | 3 requests per minute per IP address | | Public charging: session actions (confirm, stop, cancel, receipt email) | 10 requests per minute per session token | | Public charging: charger/session status polling | 30 requests per minute per charger code or session token | | Public charging: page load | 30 requests per minute per IP address | Unauthenticated requests are rate limited by IP address. The public charging endpoints (driver-facing, session-token based) are keyed by session token or IP address rather than by authenticated user account. ## Rate limit headers Rate-limited responses include the following headers: | Header | Description | | ----------------------- | ------------------------------------------------------- | | `X-RateLimit-Limit` | Maximum number of requests allowed in the window | | `X-RateLimit-Remaining` | Number of requests remaining in the current window | | `Retry-After` | Seconds to wait before retrying (only on 429 responses) | ## Handling rate limits When you exceed the rate limit, the API returns a `429 Too Many Requests` response: ```json theme={null} { "message": "Too Many Attempts." } ``` Back off and retry after the number of seconds indicated by the `Retry-After` header: ```javascript theme={null} const response = await fetch(url, { headers }); if (response.status === 429) { const retryAfter = parseInt(response.headers.get('Retry-After') || '60', 10); await new Promise(resolve => setTimeout(resolve, retryAfter * 1000)); // Retry the request } ``` ## Best practices * **Cache responses** when possible to reduce the number of requests. * **Use pagination** rather than fetching large datasets repeatedly. * **Implement exponential backoff** when receiving 429 responses. * **Batch operations** where the API supports it (e.g., card imports). # Plugchoice API Source: https://developer.plugchoice.com/index Build integrations with the Plugchoice EV charging management platform. The Plugchoice API lets you manage EV chargers, sites, teams, and charging sessions programmatically. All endpoints are RESTful, accept JSON request bodies, and return JSON responses. ## Base URL ``` https://app.plugchoice.com/api/v3 ``` ## Authentication All API requests require a bearer token in the `Authorization` header. ```bash theme={null} curl https://app.plugchoice.com/api/v3/user \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` You can generate personal access tokens from your [dashboard settings](https://app.plugchoice.com/settings/personal-access-tokens), or use OAuth 2.0 for third-party integrations. Learn about OAuth 2.0 flows, personal access tokens, and token management. ## Resource hierarchy Plugchoice resources are organized in a hierarchy: * **Teams** are the top-level organizational unit. Users belong to one or more teams. * **Locations** represent physical sites with chargers. Locations belong to teams. * **Chargers** are individual charging stations. Chargers are assigned to locations. * **Connectors** are the physical plugs on a charger. A charger can have one or more connectors. ## Quick links OAuth 2.0, personal access tokens, and bearer auth. Manage chargers, firmware, and settings. Create and manage charging locations. Start/stop charging, restart chargers, and more.