Ampcontrol logo
API docs by Redocly

Ampcontrol API (2.0.0)

Download OpenAPI specification:Download

E-mail: support@ampcontrol.io Terms of Service

ampcontrol.io is an AI-based optimization service accessible through an API for charging point operators (CPO), car manufacturers, and developers. It delivers a toolset to generate optimized charging profiles for electric vehicle (EV) charging stations (Smart Charging).'

Introduction

Ampcontrol's Knowledge Base

The Knowledge Base provides comprehensive vocabulary, detailed descriptions, and step-by-step tutorials. It is a valuable resource for customers who want to integrate Ampcontrol into their software systems. The password for the knowledge base can be found in the User Interface of the Ampcontrol platform.

Working with Ampcontrol's API

Ampcontrol's API powers its smart charging software. Behind this API is a software layer optimizing charging stations, charging networks, and electric fleets around the world to allow more electric vehicles on our roads, globally. Ampcontrol, for example, provides a REST API for load management, electric fleet charging, and public charging networks. With this API, you can connect Ampcontrol to any existing software system. Ampcontrol's resources have one or more methods that can be used over HTTP, like GET, POST, PATCH, and DELETE.

Authenticate with HTTP

Ampcontrol supports HTTP Bearer authentication. This allows you to protect the URLs on your web server so that only you and Ampcontrol can access them. In order to authenticate, you will use your Ampcontrol authentication token: Authorization: Bearer <token>

A typical API request

Let's do one simple API request with Ampcontrol. The code below shows how to create a new charging session. This will in turn create an optimization.

# example API request
import requests
import json
# You should have received your Bearer Token from our team
token = 'your_bearer_token'
headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}
# If you don't have chargePoints or connectors, you can use the API to create new ones
payload = {
  "chargePointId": "7f761661-39fc-5220-b167-dc550d9ad06c",
  "connectorId": "9c82883b-694e-5e10-bfc2-be7f88f376ce",
}
url = "https://api.ampcontrol.io/v2/charging_sessions/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

# example API response {
  "status": "success",
  "data": [
    {
      "id": "e92f5fb6-e014-5267-9f3e-41cd72248f89",
      "created": "2021-07-09T18:08:52.649578+00:00",
      "updated": "2021-07-09T18:08:52.649578+00:00",
      "connectorId": "9c82883b-694e-5e10-bfc2-be7f88f376ce",
      "chargingRateUnit": "kW",
      "vehicleId": null,
      "transactionId": null,
      "energyToCharge": null,
      "maximumChargingTimeDate": null,
      "maxChargingPowerOfVehicle": null,
      "chargePointId": "7f761661-39fc-5220-b167-dc550d9ad06c"
    }
  ],
  "total": 1
}

Webhooks

Webhooks are user-defined HTTP callbacks triggered by an event in a web application. Ampcontrol uses webhooks to asynchronously let your application know when optimizations happen, like getting a new charging profile for your vehicle. This is optional, and you can use Ampcontrol also without using webhooks. When the webhook event occurs, Ampcontrol makes a POST request to the URL you have configured for your webhook. Ampcontrol’s request to your application includes details of the event, like kilowatt limits for a certain charge point connector. Your application can then perform whatever logic is necessary. Webhook requests are signed with an X-Webhook-Signature HTTP header containing the HMAC sha256 digest output of your network's webhookSecret and the request body. This way you can optionally use the header to verify that the request comes from a trusted source. The User-Agent header is set to Ampcontrol Delivery Service, firewall rules can be added to allow inbound requests containing this header on the client-side.

How to validate requests sent to the webhook URL from our delivery service, an example:

webhook_secret = 'my-secret-token' # this can be set on /v2/networks/ endpoint
headers = response.header
body = response.body
print(body)
"""
  {
      'this is a simple json reponse payload'
  }
"""
print(headers)
""" {
  "User-Agent": "Ampcontrol Delivery Service"
  "X-Webhook-Signature": "676851448a4cda2f3c285ed2274867654c801e8a6394c351b77c713ab4ad20e4"
} """
# to validate that the payload was sent by ampcontrol we can do the following:
signature = hmac.create(
    key=webhook_secret.encode("UTF-8"),
    msg=body.enconde("UTF-8"),
    hash_function=sha256
)
# Make sure that the HMAC library you are using returns as a string containing only hexadecimal digits.
assert signature == headers["X-Webhook-Signature"]

Getting started

Ampcontrol works with digital twins of a charging network or charging location. The system differentiates the following objects: Networks, chargePoints, connectors, chargingSessions, optimizations, and vehicles (optional).

Integrating Ampcontrol into your app is simple, and you can follow these steps:

  1. Login and get your token
  2. Test your token
  3. Post a new network
  4. Post a charge point
  5. Post a connector
  6. Post ("start") a charging session
  7. Get optimization results
  8. Post meter values
  9. Delete ("stop") a charging session
  10. Post a vehicle
  11. Update vehicle
  12. Post/start a charging session with vehicle data
  13. Set a webhook for a network

1. Login and get your token

To obtain your authentication token, log in to your account and extract the token.

# replace with your own username and password
login_credentials = {
  "name": "username",
  "password": "password"
}
url = "https://api.ampcontrol.io/v2/users/login"
response = requests.post(url, login_credentials)
token = response.json()["data"][0]["session"]
print(response.json()["data"][0]["session"])

Ampcontrol returns a "success" message with a "session" field that contains your token.

{
  "status": "success",
  "data": [
    {
      "length": 284,
      "payload": {
        "chk": "4204fce9425a7011",
        "company": "843c686f-5602-46ca-96c8-6b200740a37d",
        "exp": "2022-03-08T17:47:49.440481+00:00",
        "role": "user",
        "type": "user",
        "user": "0333e0c4-1989-41b7-b12f-45aa61a9093c"
      },
      "session": "gieIqM78mDMGosLkHfNYQSFfnKm26XEVmyFaFEuHq2Q.0nIwETO2EWNyQTOlNmZ1ADNyIiOisGajJCL5YjNxYzN2QjNxojIwhXZiwiIyV2c1JiOiUGbvJnIsIyMiV2NxIjNlFWZhNTLyUWN50yNjRTNtkTM5MTLiljYTewq1QmI6ISeuFGct92Yisrett3L.modn4rN4MGOtYGOkFWL5YWM10CMmZ2MtATS1k3hNMJeoojIyV2c1Jye.9JiN1IzUIJiOicGbhJCLiQ1VKJA4oan4elks"
    }
  ],
  "total": 1
}

2. Test your token

To check that your integration is working correctly, make a test API request using your test token to get all your charge points.

# replace the token with your token
headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}
url = "https://api.ampcontrol.io/v2/charge_points/"
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a "success". If you haven't created any charge points, the data will be empty.

{
  "status": "success",
  "data": [],
  "total": 0
}

3. Post a network

Before using Ampcontrol, you typically have to create a new network, charge point, and connector. In this step, we create a network, using only the required data.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}

payload = {
  "name": "my first network",
  "maxCapacity": 30  # maxCapacity of networks is always in kW
}
url = "https://api.ampcontrol.io/v2/networks/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a network object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "maxCapacity": 30.0,
      "currentChargingLoad": null,
      "name": "my first network",
      "id": "3b87971f-e7ec-5a73-be26-cee0aafe75fe",
      "created": "2021-07-10T17:21:33.462196+00:00",
      "updated": "2021-07-10T17:21:33.462196+00:00",
      "objective": "load_sharing",
      "timeZone": "UTC",
      "location": null,
      "webhook": null,
      "currentLimit": null
    }
  ],
  "total": 1
}

4. Post a charge point

In this step, we create a charge point and a connector, using only the required data. The charge point is linked to your network.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}

payload = {
  "maxCapacity": 75, # maxCapacity of charge point is always in kW
  "name": "Charger 1",
  "networkId": "3b87971f-e7ec-5a73-be26-cee0aafe75fe" # the charge point is linked to the networkId
}
url = "https://api.ampcontrol.io/v2/charge_points/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a chargePoint object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "id": "42e56909-f84f-5852-a7ad-98f284104af4",
      "created": "2021-07-10T17:27:08.404196+00:00",
      "updated": "2021-07-10T17:27:08.404196+00:00",
      "maxCapacity": 75.0,
      "currentChargingLoad": 0.0,
      "name": "Charger 1",
      "networkId": "3b87971f-e7ec-5a73-be26-cee0aafe75fe",
      "location": null,
      "latitude": null,
      "longitude": null,
      "vendor": null,
      "protocol": null,
      "active": false,
      "currentLimit": null
    }
  ],
  "total": 1
}

5. Post a connector

In this step, we create a connector, using only the required data. The connector is linked to your charge point.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}

payload = {
  "maxCapacity": 75, # maxCapacity of connectors is always in kW
  "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4", # the connector is linked to the chargePointId
  "connectorId": 1,  # connectorId is an integer >0
  "currentType": "DC", # currentType can be DC, AC_phase3_LN, or AC_phase3_LL
  "voltage": 230 # Minimum voltage is 120V
}
url = "https://api.ampcontrol.io/v2/connectors/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a connector object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "maxCapacity": 75.0,
      "currentChargingLoad": 0.0,
      "name": null,
      "id": "c77a41a0-be89-58a6-867b-5d61b04f2d22",
      "created": "2021-07-10T17:32:15.059072+00:00",
      "updated": "2021-07-10T17:32:15.059072+00:00",
      "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4",
      "connectorId": 1,
      "currentType": "DC",
      "voltage": 230.0,
      "powerFactor": 1.0,
      "active": false,
      "currentLimit": null
    }
  ],
  "total": 1
}

6. Post/start a charging session

In this step, we create a charging session on the created connector, using only the required data.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}
# the charging session is linked to charge point and connector
payload = {
  "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4",
  "connectorId": "c77a41a0-be89-58a6-867b-5d61b04f2d22"
}
url = "https://api.ampcontrol.io/v2/charging_sessions/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a chargingSession object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "id": "066dad20-d289-560b-9b67-fd9bb9f52057",
      "created": "2021-07-10T17:40:40.898007+00:00",
      "updated": "2021-07-10T17:40:40.898007+00:00",
      "connectorId": "c77a41a0-be89-58a6-867b-5d61b04f2d22",
      "chargingRateUnit": "kW",
      "vehicleId": null,
      "transactionId": null,
      "energyToCharge": null,
      "maximumChargingTimeDate": null,
      "maxChargingPowerOfVehicle": null,
      "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4"
    }
  ],
  "total": 1
}

7. Get optimization results

In this step, we receive optimization results for the created charging session.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}
# Use the query parameter to filter by network, chargepoint, connector, or charge_session
url = "https://api.ampcontrol.io/v2/optimizations/?network=3b87971f-e7ec-5a73-be26-cee0aafe75fe"
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns an Optimization object in the response of your API request. In this case, the network is the limiting factor and the optimization allows 30 kW.

{
  "status": "success",
  "data": [
    {
      "id": "b87ecec4-5805-50d3-ac62-f75da4138e70",
      "created": "2021-07-10T17:40:40.970125+00:00",
      "updated": "2021-07-10T17:40:40.970125+00:00",
      "method": "load_sharing",
      "csChargingProfiles": {
        "chargingProfileId": 12962,
        "chargingProfileKind": "Absolute",
        "chargingProfilePurpose": "TxProfile",
        "chargingSchedule": {
          "chargingRateUnit": "kW",
          "chargingSchedulePeriod": [
            {
              "limit": 30.0,
              "startPeriod": 0.0
            },
            {
              "limit": 30.0,
              "startPeriod": 900.0
            },
            {
              "limit": 30.0,
              "startPeriod": 1800.0
            },
            {
              "limit": 30.0,
              "startPeriod": 2700.0
            },
            {
              "limit": 30.0,
              "startPeriod": 3600.0
            },
            {
              "limit": 30.0,
              "startPeriod": 4500.0
            },
            {
              "limit": 30.0,
              "startPeriod": 5400.0
            },
            {
              "limit": 30.0,
              "startPeriod": 6300.0
            },
            {
              "limit": 30.0,
              "startPeriod": 7200.0
            },
            {
              "limit": 30.0,
              "startPeriod": 8100.0-
            }
          ],
          "duration": 9000.0
        },
        "stackLevel": 0.0,
        "transactionId": null,
        "validFrom": "2021-07-10T17:40:40.970125+00:00",
        "validTo": "2021-07-10T20:10:40.970125+00:00"
      },
      "profile": {
        "start": "2021-07-10T17:40:40.970125+00:00",
        "stop": "2021-07-10T20:10:40.970125+0-0:00",
        "unit": "kW",
        "data": [
          {
            "time": "2021-07-10T17:40:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T17:55:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T18:10:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T18:25:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T18:40:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T18:55:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T19:10:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T19:25:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T19:40:40.970125+00:00",
            "value": 30.0
          },
          {
            "time": "2021-07-10T19:55:40.970125+00:00",
            "value": 30.0
          }
        ]
      },
      "connectorId": 1,
      "connector": "c77a41a0-be89-58a6-867b-5d61b04f2d22",
      "chargepointId": "42e56909-f84f-5852-a7ad-98f284104af4",
      "networkId": "3b87971f-e7ec-5a73-be26-cee0aafe75fe"
    }
  ],
  "total": 1
}

Your dashboard will show the load profile.

8. Post meter values

In this step, we send a meter value from the connector to Ampcontrol. Ampcontrol uses meter values to confirm and adjust the optimization dynamically.


  headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
  }

  payload = {
    "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4",
    "connectorId": 1,
    "meterValues": [
        {
            "sampledValue": [
                {
                    "context": "Sample.Periodic",
                    "format": "Raw",
                    "location": "Outlet",
                    "measurand": "Energy.Active.Import.Register",
                    "phase": "L1",
                    "unit": "Wh",
                    "value": 56790
                }
            ],
            "timestamp": "2021-07-10T17:40:56+00:00"
        }
    ]
}
url = "https://api.ampcontrol.io/v2/meter_values/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a meterValue object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4",
      "connectorId": 1,
      "meterValues": [
        {
          "timestamp": "2021-07-10T17:40:56+00:00",
          "sampledValue": [
            {
              "context": "Sample.Periodic",
              "format": "Raw",
              "location": "Outlet",
              "measurand": "Energy.Active.Import.Register",
              "phase": "L1",
              "unit": "Wh",
              "value": 56790
            }
          ]
        }
      ]
    }
  ],
  "total": 1
}

9. Delete/stop a charging session

In this step, we stop the same charging session. This is typically the step when the vehicle leaves the charge point.

headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}
# we use the charging session ID which Ampcontrol sent after the POST
url = "https://api.ampcontrol.io/v2/charging_sessions/066dad20-d289-560b-9b67-fd9bb9f52057"
response = requests.delete(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a chargingSession object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "id": "066dad20-d289-560b-9b67-fd9bb9f52057",
      "created": "2021-07-10T17:40:40.898007+00:00",
      "updated": "2021-07-10T20:25:30.749445+00:00",
      "connectorId": "c77a41a0-be89-58a6-867b-5d61b04f2d22",
      "chargingRateUnit": "kW",
      "vehicleId": null,
      "transactionId": null,
      "energyToCharge": null,
      "maximumChargingTimeDate": null,
      "maxChargingPowerOfVehicle": null,
      "chargePointId": "42e56909-f84f-5852-a7ad-98f284104af4"
    }
  ],
  "total": 1
}

10. Post a vehicle

In this step, we create a vehicle. All fields are optional. The vehicle is not related to a specific network and can be used across networks.

headers = {
        'content-type': 'application/json'
        'authorization': 'Bearer ' +  token
        }

payload = {
  "name": "Bus 2", # name can be defined by customer
  "VIN": "4Y1SL65848Z411439", # Vehicle identification number (VIN) is the identifying code for the vehicle
  "batteryCapacity": 100,  # batteryCapacity is always in kWh, is an integer >0
  "maxChargingPower": 11.5,  # maxChargingPower is in kW and defines the upper limit of the vehicle's power input
  "targetStateOfCharge": 100 # targetStateOfCharge is in percentage (%)
}
url = "https://api.ampcontrol.io/v2/vehicles/"
response = requests.post(url, headers=headers, data=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a Vehicle object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "name": "Bus 2",
      "id": "4e389086-efa1-57d4-981b-a63f25630cb8",
      "created": "2021-08-12T13:05:42.982026+00:00",
      "updated": "2021-08-12T13:05:42.982026+00:00",
      "VIN": "4Y1SL65848Z411439",
      "customerVehicleId": null,
      "stateOfCharge": 0.0,
      "targetStateOfCharge": 100.0,
      "maxChargingPower": 11.5,
      "batteryCapacity": 100.0,
      "location": null,
      "departureTime": null,
      "active": false
    }
  ],
  "total": 1
}

11. Update vehicle

In this step, we update a vehicle. We send a target state of charge, the current state of charge and a departure time for the existing vehicle.

headers = {
        'content-type': 'application/json'
        'authorization': 'Bearer ' +  token
        }

payload = {
  "departureTime": "2020-08-13T06:00:00+00:00",  # departure time can be used for the next charging session
  "stateOfCharge": 15.5,  # previous targetStateOfCharge will be replaced
  "targetStateOfCharge": 90.0  # stateOfCharge can be updated also during the charging session
}
url = "https://api.ampcontrol.io/v2/vehicles/4e389086-efa1-57d4-981b-a63f25630cb8"  # we add the vehicleId int the URL
# we use the PATCH method
response = requests.patch(url, headers=headers, data=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns an updated Vehicle object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "name": "Bus 2",
      "id": "4e389086-efa1-57d4-981b-a63f25630cb8",
      "created": "2021-08-12T13:05:42.982026+00:00",
      "updated": "2021-08-12T13:15:24.175699+00:00",
      "VIN": "4Y1SL65848Z411439",
      "customerVehicleId": null,
      "stateOfCharge": 15.5,
      "targetStateOfCharge": 90.0,
      "maxChargingPower": 11.5,
      "batteryCapacity": 100.0,
      "location": null,
      "departureTime": "2020-08-13T06:00:00.000000+00:00",
      "active": false
    }
  ],
  "total": 1
}

12. Post/start a charging session with vehicle data

In this step, we create a new charging session on the created connector, using vehicle data. This allows fleet optimizations. (note: the network's objective has to be set on "fleet" for this functionality).

headers = {
        'content-type': 'application/json'
        'authorization': 'Bearer ' +  token
        }

# the charging session is linked to charge point, connector, vehicle payload = {
  "chargePointId": "3121d5bc-e6b1-5fc0-baa2-a232e89d5b5c",
  "connectorId": "8b3041c7-6b7c-5c55-9d43-d3a0666dd40e",
  "vehicleId": "4e389086-efa1-57d4-981b-a63f25630cb8"
}
url = "https://api.ampcontrol.io/v2/charging_sessions/"
response = requests.patch(url, headers=headers, data=payload)
print(json.dumps(response.json(), indent=4))

Ampcontrol returns a chargingSession object in the response of your API request.

{
  "status": "success",
  "data": [
    {
      "id": "bb4f07b5-c419-5efd-9640-870729ae4be3",
      "created": "2021-08-12T13:23:30.736521+00:00",
      "updated": "2021-08-12T13:23:30.736521+00:00",
      "connectorId": "8b3041c7-6b7c-5c55-9d43-d3a0666dd40e",
      "chargingRateUnit": "kW",
      "vehicleId": "4e389086-efa1-57d4-981b-a63f25630cb8",
      "transactionId": null,
      "energyToCharge": null,
      "maximumChargingTimeDate": null,
      "maxChargingPowerOfVehicle": null,
      "chargePointId": "3121d5bc-e6b1-5fc0-baa2-a232e89d5b5c",
      "active": true,
      "sessionStart": "2021-08-12T13:23:30.757062+00:00",
      "sessionEnd": null
    }
  ],
  "total": 1
}

13. Set a webhook for a network

If you want optimization profiles to be sent via a POST request to an endpoint of your choice, you can set the network's webhook parameter when creating or updating the network (POST/PATCH). To avoid a malicious source from making requests to your webhook, an additional webhookSecret parameter must be provided. Webhook events are signed with an X-Webhook-Signature HTTP header. This string contains the HMAC sha256 digest output of your webhook secret and request body. One thing to keep in mind is that if the POST request to your webhook endpoint returns a 404 response, then the charging session associated with the optimization profiles will be ended.


headers = {
  'content-type': 'application/json',
  'authorization': 'Bearer ' +  token
}


payload = {
  "webhook": "https://example.com/custom-webhook/"
  "webhookSecret": "some-secret-string"
}

url = "https://api.ampcontrol.io/v2/networks/3b87971f-e7ec-5a73-be26-cee0aafe75fe"

response = requests.patch(url, headers=headers, json=payload)

print(json.dumps(response.json(), indent=4))

Ampcontrol then returns the updated network object in the response of your API request.


{
  "status": "success",
  "data": [
    {
      "maxCapacity": 30.0,
      "currentChargingLoad": null,
      "name": "my first network",
      "id": "3b87971f-e7ec-5a73-be26-cee0aafe75fe",
      "created": "2021-07-10T17:21:33.462196+00:00",
      "updated": "2021-07-10T17:21:33.462196+00:00",
      "objective": "load_sharing",
      "timeZone": "UTC",
      "location": null,
      "webhook": "https://example.com/custom-webhook/"
      "currentLimit": null
    }
  ],
  "total": 1
}

Alerts

/v2/alerts/

Queries and returns the alerts corresponding to a network. A default 24 hours range will be applied if start or alert are not specified.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

charger
string <uuid>
Example: charger=f0adb0c5-31b7-4a36-8052-de019a1a1638

Filter alerts by charger's uuid

connector
string <uuid>
Example: connector=f32ae6f5-b640-46fc-82c4-99c5cbedde37

Filter alerts by connector's uuid

name
Array of strings (alert_name_schema_enum)
Items Enum: "METER_VALUE_LIMIT_VIOLATION" "UNEXPECTED_CONNECTOR_AND_PHASE_COMBINATION" "CHARGER_DISCONNECTED" "INVALID_ID_TAGS" "OCPP_MESSAGE_OUT_OF_SYNC" "CALL_ERROR" "CHARGE_POINT_HIGH_INTERNAL_TEMPERATURE" "SUSPENDED_EVSE" "SUSPENDED_EV" "UNAVAILABLE" "FAULTED" "CONNECTOR_LOCK_FAILURE" "EV_COMMUNICATION_ERROR" "GROUND_FAILURE" "HIGH_TEMPERATURE" "INTERNAL_ERROR" "LOCAL_LIST_CONFLICT" "OVER_CURRENT_FAILURE" "OVER_VOLTAGE" "POWER_METER_FAILURE" "POWER_SWITCH_FAILURE" "READER_FAILURE" "RESET_FAILURE" "UNDER_VOLTAGE" "WEAK_SIGNAL" "VENDOR_ERROR_CODE" "INCORRECT_SETTINGS"

Filter by alert name. This will override the 'category' and 'urgency' fields.

category
Array of strings (alert_category_schema_enum)
Items Enum: "Charge Point" "Connector" "Vehicle" "IdTag" "Operations" "Maintenance" "System Error" "Settings Error" "Hardware" "Software"

Filter by alert categories.

urgency
Array of strings (alert_urgency_schema_enum)
Items Enum: "Very High" "High" "Medium" "Low" "Very Low"

Filter by alert urgency.

status
Array of strings (alert_status_schema_enum)
Items Enum: "Triggered" "Acknowledged" "Resolved" "Pending"

Filter by alert status.

sort
Array of strings[^(start|end|urgency|name):(desc|asc)$]

Sort by specific values. Defaults to 'start' in descending order. Uses the following pattern ^(start|end|urgency|name):(desc|asc)$

isActive
boolean
Example: isActive=true

Filter by alert active status.

vehicleId
string <uuid>
Example: vehicleId=f32ae6f5-b640-46fc-82c4-99c5cbedde37

Filter alerts by vehicle uuid

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/alerts/{alert_id}

Returns alert by UUID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/alerts/{alert_id}

Modifies and returns the corresponding alert

Request Body schema: application/json
status
string
Enum: "Triggered" "Acknowledged" "Resolved"

Change the status of the alert

notes
string

Add notes and information for this alert

Responses

Request samples

Content type
application/json
{
  • "status": "Triggered",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

AmpEdge

Baseloads

/v2/baseloads/

Add baseloads

Request Body schema: application/json
networkId
required
string <uuid> (uuid)
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "baseloadMeterValues": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 2
}

/v2/baseloads/

List baseloads for a network

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 5
}

Capacities

/v2/capacities/

Create a maximum capacity time range for a network or charger. Submitted capacity cannot be less than the network.maxCapacity. Either networkId or chargePointId must be provided. Submitting a maximum capacity for a charger is under development an won't affect optimizations.

Request Body schema: application/json
networkId
string <uuid> (uuid)
chargePointId
string <uuid> (uuid)
required
Array of objects <= 100 items

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "maxCapacityIntervals": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/capacities/

Fetch all maximum capacities for a network. Either network or charger must be provided as a query parameter.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network ID.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by charger ID.

start
string <date-time> (datetime_utc_now)
Default: "Current time"
Example: start=2020-10-11T08:19:00+00:00

Date-time interval limit: 7 days
Search lower bound of the query. Defaults to current time in UTC.

end
string <date-time> (datetime_utc_12)
Default: "Current time + 12 hours"
Example: end=2020-10-11T08:19:00+00:00

Date-time interval limit: 7 days
Search upper bound of the query. Defaults to current time in UTC plus 12 hours into the future.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/capacities/{capacity_uuid}

Fetch an specific variable maximum capacities

path Parameters
capacity_uuid
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Capacity UUID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/capacities/{id}

Update a max capacity time range for a network.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
type
string
Value: "utilityLimit"

Purpose of the capacity limitation

maxCapacity
number <float>

In kW (Kilowatt). Maximum allowed power on this resource.

start
string <date-time>
Default: "Current time"

The start date-time of the maximum allowed power period.

end
string <date-time>
Default: "Current time + 24 hours"

The end date-time of the maximum allowed power period.

Responses

Request samples

Content type
application/json
{
  • "type": "utilityLimit",
  • "maxCapacity": 22,
  • "start": "2020-10-11T08:19:00+00:00",
  • "end": "2020-10-11T08:19:00+00:00"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/capacities/{id}

Delete a max capacity.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

CDRs

The cdrData array shows the full Charging Detail Record for the charging session including the exact charge periods, tariffs, total energy, duration and price.

/v2/cdrs/

List CDRs

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

cdr
string

CDR ID.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start. Filters CDRs that started or ended after the specified value.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end. Filters CDRs that started or ended before the specified value.

export
boolean
Default: false

Return CDR data with export format

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "total": 0,
  • "data": [
    ]
}

Charge points

/v2/charge_points/

Add a charge point.

Request Body schema: application/json
maxCapacity
required
number <float> >= 0

Maximum allowed power on this resource in kW (Kilowatt).

name
required
string <string> <= 40 characters
Deprecated

This field is optional. If provided, it will be duplicated to the "customName" field. We recommend using "customName" for clarity, and "name" will be phased out in future updates.

networkId
required
string <uuid> (uuid)
allowAllIdTags
boolean or null

The default value is set to True. When set to True, any id tag is accepted when a vehicle connects.

customName
required
string or null <= 40 characters
firmwareVersion
string or null <= 50 characters

Charge point firmware version.

latitude
number or null <float> <= 90 characters >= -90

Charge point location Latitude, + is North, - is South.

location
string or null <= 128 characters
longitude
number or null <float> [ -180 .. 180 ]

Charge point location Longitude, + is East, - is West.

modelName
string or null

Charge point model name.

ocppId
any or null <string>
ocppStatus
string (charger_ocpp_status)
Enum: "Available" "Faulted" "Unavailable"

Value from OCPP StatusNotification message.

ocppStatusUpdate
string <date-time> (datetime)

ISO 8601.

onlineStatus
string or null
Enum: "OFFLINE" "ONLINE"

Whether the Charge point is connected to the CMS or not.

onlineStatusUpdate
string <date-time> (datetime)

ISO 8601.

orientation
number <float> [ 0 .. 360 ]
Default: 0

The orientation angle of the charge point in degrees. This value can range from 0 to 360, representing a full circle. The reference point for the orientation is North, with 0 degrees pointing in that direction.

object (charge_point_position)

Position and orientation on Fleet Management view.

protocol
string or null <= 255 characters
securityProfile
integer or null (securityProfile) [ 1 .. 3 ]
Deprecated

[Not Implemented] Charge point security profile. Consult OCPP documentation for more details.

[Warning] The security profile MUST be updated through OCPP messages under normal operations.

source
string or null
Enum: "CMS" "UI"

Intended for internal use. If charge point is to be created through an API integration, leave this field empty.

subNetworkId
string <uuid>

UUID of the parent sub_network, if null, the sub_network is directly attached to the network.

vendor
string or null

Charge Point vendor name.

powerSplit
boolean or null

Indicates whether a charge point with multiple connectors has the capability to distribute power among those connectors simultaneously. This parameter is irrelevant if the charge point has only one connector.

paymentTerminalID
string or null

Payment terminal ID.

shareToPublicMaps
boolean or null

When true, this charger's location and status will be shared to public charging maps. Consider this if you want to open your charger to public access. When setting this field to true, publicGuestRates should also be defined.

publicGuestRates
Array of strings or null <uuid>

Charging fees that will be displayed to public charging maps. Use with shareToPublicMaps.

password
string or null
Deprecated

[Not Implemented] Charge point password used to authenticate with CMS. This is not mandatory.

[Warning] The password MUST be updated through OCPP messages under normal operations. Contact the manufacturer if the default password is unknown.

Responses

Request samples

Content type
application/json
{
  • "maxCapacity": 22,
  • "name": "EVSE 1",
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "allowAllIdTags": true,
  • "customName": "12",
  • "firmwareVersion": "V1.02.23rc2",
  • "latitude": 32.2431,
  • "location": "New York",
  • "longitude": 115.793,
  • "modelName": "EX-1193-1A11",
  • "ocppId": "CHARGER-123",
  • "ocppStatus": "Available",
  • "ocppStatusUpdate": "2020-10-11T08:19:00",
  • "onlineStatus": "ONLINE",
  • "onlineStatusUpdate": "2020-10-11T08:19:00",
  • "orientation": 30.2,
  • "position": {
    },
  • "protocol": "OCPP 1.6",
  • "securityProfile": 1,
  • "source": "CMS",
  • "subNetworkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "vendor": "Vendor Name",
  • "powerSplit": true,
  • "paymentTerminalID": "00000001",
  • "shareToPublicMaps": true,
  • "publicGuestRates": [
    ],
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "total": 1
}

/v2/charge_points/

List charge points.

query Parameters
object (is_active)

Filter by active status

allow_all_id_tags
boolean

filter by charge_points that have allowAllIdTags set to specified True/False.

current
string
Enum: "AC" "DC" "Mix"

Filter by connector current type

custom_name
string

Filter by customName

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

name
string
Deprecated

Filter by charger name. Ampcontrol will soon move supporting “customName” instead, as the user centric naming parameter.

network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

online_status
string
Enum: "ONLINE" "OFFLINE"

Filter by online status.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

order
string
Deprecated
Enum: "ascending" "descending"

Specify an ordering for the sorting parameter. Default is descending. (Deprecated: use sort)

powerSplit
boolean

Indicates whether a charge point with multiple connectors has the capability to distribute power among those connectors simultaneously. This parameter is irrelevant if the charge point has only one connector.

search
string

This is a string search that compares to a number of different string like customName, serialNumber, ocppId, vendor, firmwareVersion, or id (charger point id).

sort
string`^(custom_name|name|active|max_capacity|curre...
Example: sort=custom_name:desc

Sort by specific values. Defaults to 'active' in descending order. Accepted values: active, allowAllIdTags, current, current_charging_load, custom_name, firmwareVersion, last_session_started, max_capacity, name, numberOfConnectors, ocppId, online_status, powerSplit, vendor. Accepted ordering: asc, desc.

sort_by
string
Deprecated
Enum: "custom_name" "name" "active" "max_capacity" "current_charging_load" "last_session_started"

Sort by a given field. (Deprecated: use sort)

updated
string <date-time>
Example: updated=2020-10-11T08:19:00+00:00

Returns objects updated after the specified timestamp.

vendor
string

Filter by charger vendor

share_to_public_maps
boolean

Filter by charge_point that have shareToPublicMaps set to the specified (True/False).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "total": 1
}

/v2/charge_points/{charge_point_uuid}

Get a charge point.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID as uuid4. This represents a unique identifier for the resource.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "total": 1
}

/v2/charge_points/{charge_point_uuid}

Update a charge point.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID as uuid4. This represents a unique identifier for the resource.

Request Body schema: application/json
name
string <string> <= 40 characters
Deprecated

This field is optional. If provided, it will be duplicated to the "customName" field. We recommend using "customName" for clarity, and "name" will be phased out in future updates.

networkId
string <uuid> (uuid)
allowAllIdTags
boolean or null

The default value is set to True. When set to True, any id tag is accepted when a vehicle connects.

customName
string or null <= 40 characters
firmwareVersion
string or null <= 50 characters

Charge point firmware version.

latitude
number or null <float> <= 90 characters >= -90

Charge point location Latitude, + is North, - is South.

location
string or null <= 128 characters
longitude
number or null <float> [ -180 .. 180 ]

Charge point location Longitude, + is East, - is West.

modelName
string or null

Charge point model name.

ocppId
any or null <string>
ocppStatus
string (charger_ocpp_status)
Enum: "Available" "Faulted" "Unavailable"

Value from OCPP StatusNotification message.

ocppStatusUpdate
string <date-time> (datetime)

ISO 8601.

onlineStatus
string or null
Enum: "OFFLINE" "ONLINE"

Whether the Charge point is connected to the CMS or not.

onlineStatusUpdate
string <date-time> (datetime)

ISO 8601.

orientation
number <float> [ 0 .. 360 ]
Default: 0

The orientation angle of the charge point in degrees. This value can range from 0 to 360, representing a full circle. The reference point for the orientation is North, with 0 degrees pointing in that direction.

object (charge_point_position)

Position and orientation on Fleet Management view.

protocol
string or null <= 255 characters
securityProfile
integer or null (securityProfile) [ 1 .. 3 ]
Deprecated

[Not Implemented] Charge point security profile. Consult OCPP documentation for more details.

[Warning] The security profile MUST be updated through OCPP messages under normal operations.

source
string or null
Enum: "CMS" "UI"

Intended for internal use. If charge point is to be created through an API integration, leave this field empty.

subNetworkId
string <uuid>

UUID of the parent sub_network, if null, the sub_network is directly attached to the network.

vendor
string or null

Charge Point vendor name.

powerSplit
boolean or null

Indicates whether a charge point with multiple connectors has the capability to distribute power among those connectors simultaneously. This parameter is irrelevant if the charge point has only one connector.

paymentTerminalID
string or null

Payment terminal ID.

shareToPublicMaps
boolean or null

When true, this charger's location and status will be shared to public charging maps. Consider this if you want to open your charger to public access. When setting this field to true, publicGuestRates should also be defined.

publicGuestRates
Array of strings or null <uuid>

Charging fees that will be displayed to public charging maps. Use with shareToPublicMaps.

maxCapacity
number <float> >= 0

Maximum allowed power on this resource in kW (Kilowatt).

password
string or null
Deprecated

[Not Implemented] Charge point password used to authenticate with CMS. This is not mandatory.

[Warning] The password MUST be updated through OCPP messages under normal operations. Contact the manufacturer if the default password is unknown.

meterType
string or null

Charge Point meter type.

serialNumber
string or null

Charge Point serial number.

Responses

Request samples

Content type
application/json
{
  • "name": "EVSE 1",
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "allowAllIdTags": true,
  • "customName": "12",
  • "firmwareVersion": "V1.02.23rc2",
  • "latitude": 32.2431,
  • "location": "New York",
  • "longitude": 115.793,
  • "modelName": "EX-1193-1A11",
  • "ocppId": "CHARGER-123",
  • "ocppStatus": "Available",
  • "ocppStatusUpdate": "2020-10-11T08:19:00",
  • "onlineStatus": "ONLINE",
  • "onlineStatusUpdate": "2020-10-11T08:19:00",
  • "orientation": 30.2,
  • "position": {
    },
  • "protocol": "OCPP 1.6",
  • "securityProfile": 1,
  • "source": "CMS",
  • "subNetworkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "vendor": "Vendor Name",
  • "powerSplit": true,
  • "paymentTerminalID": "00000001",
  • "shareToPublicMaps": true,
  • "publicGuestRates": [
    ],
  • "maxCapacity": 22,
  • "password": "string",
  • "meterType": "Meter Type I",
  • "serialNumber": "00000001"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "total": 1
}

/v2/charge_points/{charge_point_uuid}

Delete a charge point.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID as uuid4. This represents a unique identifier for the resource.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "status": "success",
  • "total": 1
}

Charging sessions

/v2/charging_sessions/

Request an optimization. This will not remote start a charger, it will have no direct affect on the charger operations.

Request Body schema: application/json
required
integer or string

Connector UUID or Connector ID, typically 1-4.

chargePointId
required
string <uuid> (uuid)
chargingRateUnit
string (chargingRateUnit)
Deprecated
Default: "W"
Enum: "W" "kW" "A"

Sets the unit of the optimization result profiles (limits). The chargingRateUnit does not affect other request input parameters (e.g energyToCharge).

idTag
string

Id tag value used when starting the session (this might be an RFID tag or a credit card token)

energyToCharge
number <float> (energyToCharge)

Energy to be delivered during the charging session (kWh).

maxChargingPowerOfVehicle
number <float> (maxChargingPowerOfVehicle)

In kW (Kilowatt). Maximum input power of the vehicle. If null, the maxCapacity of the connector will be used in calculations.

maximumChargingTimeDate
string <date-time> (datetime_utc)

ISO 8601 in UTC.

meterStart
number >= 0

In kWh (Kilowatt-hour), energy meter value reading of the charger at the start of the charging session.

ocppTransactionStart
string <date>

Timestamp of the StartTransaction ocpp message. If the ocppTransactionStart timestamp is present on session create, the sessionStart timestamp will be set to the same value.

paymentInfo
string (paymentInfo)

Payment provider identifier

priority
number <integer> (priority) [ 0 .. 5 ]

Priority of the charging session. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
remoteStopOnCompletion
boolean (remoteStopOnCompletion)

This parameter configures if the session will automatically be remote stopped once the session completion criteria (e.g. the specified energyToCharge was succesfully charged) are fulfilled. Note: this remote stopping functionality is only supported when using the AmpCMS.

transactionId
number <int64> (transactionId)

If set, transactionId will be returned as part of the optimizations. Usually defined by the central charging management system (e.g. OCPP backend).

vehicleId
string <uuid> (uuid)

Responses

Request samples

Content type
application/json
{
  • "connectorId": 1,
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "chargingRateUnit": "W",
  • "idTag": "FHH92JFNMSK93",
  • "energyToCharge": 80,
  • "maxChargingPowerOfVehicle": 22,
  • "maximumChargingTimeDate": "2020-10-11T08:19:00+00:00",
  • "meterStart": 12.2,
  • "ocppTransactionStart": "2021-12-17T22:30:27.629927+00:00",
  • "paymentInfo": "string",
  • "priority": 5,
  • "remoteStopOnCompletion": true,
  • "transactionId": 1,
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/

List the current active charging sessions. In order to see ended sessions start and end query parameters are required. At least one of network, vehicle or transaction_id is required.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
Array of strings <uuid> (uuid) [ items <uuid > ]
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint IDs.

status
string
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Unavailable" "Faulted"

Filter by OCPP chargepoint status

connector
Array of strings <uuid> (uuid) [ items <uuid > ]
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector IDs.

vehicle
Array of strings <uuid> (uuid) [ items <uuid > ]
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle IDs (this UUID was returned by POST /v2/vehicles/)

idTag
Array of any

List of Id tag values used when starting the charging session (this might be an RFID tag or a credit card token)

transaction_id
integer
Example: transaction_id=92813645

Filter charging sessions by transaction ID

active
boolean
Deprecated
Default: false

Filter charging sessions by active status

isActive
boolean
Default: null

Filter charging sessions by active status

priority
Array of integers
Example: priority=1

Filter charging sessions by priority

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start. Returns sessions that ended after this value or that have not ended yet.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end. Returns sessions that started before the specified value.

updated
string <date-time> (datetime)
Example: updated=2020-10-11T08:19:00

Filters charging sessions with an updated timestamp greater than or equal to the specified value.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

search
string

This is a free text search that compares to a number of different fields like chargerName, connectorId, connectorName, idTag, vehicleName, transactionId, or id (charge session id).

sort
string`^(chargerName|connectorId|connectorName|char...
Example: sort=chargerName:desc

Sort by specific values. Defaults to 'isActive' in descending order. Accepted values: chargerName, connectorId, connectorName, chargingDuration, energyConsumption, idTag, isActive, priority, sessionEnd, sessionStart, vehicleName. Accepted ordering: asc, desc.

chargingDuration
string
Example: chargingDuration=>=300

Filter by the chargingDuration of the charging session. The possible values are: <300 (less than 5 minutes), >=300 (greater than or equal to 5 minutes), >=1800 (greater than or equal to 30 minutes), >=3600 (greater than or equal to 1 hour), >=10800 (greater than or equal to 3 hours), >=21600 (greater than or equal to 6 hours).

energyConsumption
string
Example: energyConsumption=>=40

Filter by the energy consumption of the charging session in kWh (Kilowatt-hour). The possible values are: <20 (less than 20 kWh), >=20 (greater than or equal to 20 kWh), >=40 (greater than or equal to 40 kWh), >=100 (greater than or equal to 100 kWh), >=200 (greater than or equal to 200 kWh).

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/{charging_session_uuid}

Get charging session details.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/{charging_session_uuid}

Update or close a charging session. One of priority, meterStop, ocppTransactionStop, paymentInfo, energyToCharge, vehicleId, startSoC remoteStopOnCompletion is required. Submitting a meterStop or ocppTransactionStop value will end the charging session. priority cannot be set if the charging session is being closed

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
energyToCharge
number <float> (energyToCharge)

Energy to be delivered during the charging session (kWh).

meterStop
number

In kWh (Kilowatt-hour), energy meter value reading of the charger at the end of the charging session. If set, the session will be closed.

ocppTransactionStop
string <date> (ocppTransactionStop)

Timestamp of the StopTransaction ocpp message. If set, the session will be closed and the sessionEnd will be updated with the same timestamp.

paymentInfo
string (paymentInfo)

Payment provider identifier

priority
number <integer> (priority) [ 0 .. 5 ]

Priority of the charging session. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
remoteStopOnCompletion
boolean (remoteStopOnCompletion)

This parameter configures if the session will automatically be remote stopped once the session completion criteria (e.g. the specified energyToCharge was succesfully charged) are fulfilled. Note: this remote stopping functionality is only supported when using the AmpCMS.

vehicleId
string <uuid> (uuid)
startSoC
number <float> [ 0 .. 100 )

Responses

Request samples

Content type
application/json
{
  • "energyToCharge": 80,
  • "meterStop": 12.2,
  • "ocppTransactionStop": "2021-12-17T22:30:27.629927+00:00",
  • "paymentInfo": "string",
  • "priority": 5,
  • "remoteStopOnCompletion": true,
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "startSoC": 22
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/{charging_session_uuid}

Delete / Complete a charging session. Typically triggered by a connector unplug event.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/{charging_session_uuid}/{transaction_id}

Delete / Complete a charging session. Typically triggered by a connector unplug event.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

transaction_id
required
integer
Example: 92813645

Transaction ID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/charging_sessions/profiles/

Get profiles for all active charging sessions.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start. Returns sessions that ended after this value or that have not ended yet.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end. Returns sessions that started before the specified value.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Configurations

ABOUT CONFIGURATION'S SETUP

We use both query parameters and json body to use the available endpoints, and at each level (customer, network and chargepoint level) we expect different behaviours.

1. Customer level:

Whenever using v2/configurations/?customer={customer_uuid}, inside the data component of the response, we expect to get the fields deliveryOptions, integrations and ampCmsOptions, in the following structure by default:

  {
      "deliveryOptions": {
          "presets": {
              "TxProfile": {
                  "ampcontrol-default-TxProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 2,
                          "numberPhases": false,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "All",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxProfile"
                      },
                      "isDefault": true
                  },
                  "ampcontrol-squential-TxProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 2,
                          "numberPhases": false,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-sequential-ampere-TxProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 2,
                          "numberPhases": false,
                          "chargingRateUnit": "A",
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-default-TxProfile-number-phases": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 2,
                          "numberPhases": true,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "All",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-sequential-ampere-number-phases-TxProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 2,
                          "numberPhases": true,
                          "chargingRateUnit": "A",
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxProfile"
                      },
                      "isDefault": false
                  }
              },
              "TxDefaultProfile": {
                  "ampcontrol-default-TxDefaultProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 1,
                          "numberPhases": false,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "All",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxDefaultProfile"
                      },
                      "isDefault": true
                  },
                  "ampcontrol-squential-TxDefaultProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 1,
                          "numberPhases": false,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxDefaultProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-sequential-ampere-TxDefaultProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 1,
                          "numberPhases": false,
                          "chargingRateUnit": "A",
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxDefaultProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-default-TxDefaultProfile-number-phases": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 1,
                          "numberPhases": true,
                          "chargingRateUnit": null,
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "All",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxDefaultProfile"
                      },
                      "isDefault": false
                  },
                  "ampcontrol-sequential-ampere-number-phases-TxDefaultProfile": {
                      "settings": {
                          "timeZone": "utc",
                          "stackLevel": 1,
                          "numberPhases": true,
                          "chargingRateUnit": "A",
                          "timestampsFormat": "default",
                          "useTransactionId": true,
                          "limitDeliveryType": "Sequential",
                          "chargingProfileKind": "Absolute",
                          "useChargingProfileId": true,
                          "chargingProfilePurpose": "TxDefaultProfile"
                      },
                      "isDefault": false
                  }
              }
          },
          "TxProfile": "ampcontrol-default-TxProfile",
          "TxDefaultProfile": "ampcontrol-default-TxDefaultProfile"
      },
      "integrations": {
          "webfleet": {
              "connected" : true,
              "base_url": "https://csv.webfleet.com",
              "user_name": "my-username",
              "account": "account",
              "password": "my-password", 
              "api_key": "my-api-key" 
          },
          "geotab": {
              "connected": False,
              "base_url": "https://my.geotab.com/",
              "database": "test_db",
              "user_name": "test_user",
              "password": "test_password",
          }
      
      },
      "ampCmsOptions": {
          "feature": "off",
          "secret": "unregistered",
          "targetCmsUrl": null,
          "defaultNetworkId": null
      }
  }

  • For deliveryOptions: Contains the the pre-defined configurations to which the other elements in further levels (network or chargepoint) will refer to when declaring the TxProfile and TxDefaultProfile. Inside deliveryOptions->presets you will find a isDefault boolean key that indicates if for all the further levels of configurations, this specific profile will be applied by default, in case no particular configuration is specified, once again, in further levels.

  • For integrations: Contains the integration(s) info that this particular customer (or simmilarly for network and chargepoint) have.

  • For ampCmsOptions: Contains the authentication and usage specifications for a connection stablished through the AmpCMS service

2. Network level:

From using v2/configurations/?network={network_uuid} we expect a response like:

{
      "alerts": true,
      "idTagPriority": false,
      "integrations": {
          "shelly": {
              "base_url": "https://www.dummy-url.com",
              "device_id": "DEVICE_ABC",
              "auth_key": "my-auth-key"
          },
      },
      "deliveryOptions": {
          "TxProfile": "ampcontrol-default-TxProfile",
          "TxDefaultProfile": "ampcontrol-default-TxDefaultProfile"
      },
      "chargingRules": null,
      "alertOptions": {
          "callError": {
              "enabled": true,
              "urgency": "High",
              "category": ["List", "of", "categories"],
              "notifications": {
                  "enabled": false
              },
              "description": "This is a description of the alert.",
              "action": "Suggested action to take"
          }
      }
  }
  • alerts sets the boolean that toggles on/off alerts
  • ìdTagPriority ...
  • integrations contains the integration authentication details of our partners
  • deliveryOptions, just as explained above for customers, points to a specific configuration set by its name, depending of the profile type that it refers to. If no specific type is set, the endpoint should return an empty string:
"deliveryOptions": {
    "TxProfile": "",
    "TxDefaultProfile": "",
}
  • chargingRules ...
  • alertOptions Contains the configuration for alerts and notification, Example:
"alertOptions": {
  "callError": {
    "enabled": true,
    "urgency": "High",
    "category": ["List", "of", "categories"],
    "notifications": {
        "enabled": false
    },
    "description": "This is a description of the alert.",
    "action": "Suggested action to take"
  }
}

3. Chargepoint level:

Using v2/configurations/?chargepoint={chargepoint_uuid} sets the configuration of the following fields:

{
  "deliveryOptions": {
      "TxProfile": "ampcontrol-default-TxProfile",
      "TxDefaultProfile": "ampcontrol-default-TxDefaultProfile"
  }
}

Similar to the network's level of configuration

4. User level:

Finally, use ``2/configurations/?user={user_uuid}` to set the configuration of the following fields:

{
  "notificationChannels": {
    "smsNotifications": false,
    "emailNotifications": false
  }
}

/v2/configurations/

Creates Configuration object

query Parameters
customer
string <uuid>
Example: customer=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by customer uuid. Only by this parameter it is possible to fetch presets at deliveryOptions field

network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

user
string <uuid>
Example: user=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by user uuid.

Request Body schema: application/json
object (configurations_payload)

Any JSON-serializable object

Responses

Request samples

Content type
application/json
{
  • "alerts": false,
  • "integrations": {
    },
  • "alertOptions": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/configurations/

Returns Configuration object

query Parameters
customer
string <uuid>
Example: customer=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by customer uuid. Only by this parameter it is possible to fetch presets at deliveryOptions field

network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

user
string <uuid>
Example: user=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by user uuid.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/configurations/

Updates Configuration object

query Parameters
customer
string <uuid>
Example: customer=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by customer uuid. Only by this parameter it is possible to fetch presets at deliveryOptions field

network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

user
string <uuid>
Example: user=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by user uuid.

Request Body schema: application/json
object (configurations_payload)

Any JSON-serializable object

Responses

Request samples

Content type
application/json
{
  • "alerts": false,
  • "integrations": {
    },
  • "alertOptions": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/configurations/

Deletes Configuration object

query Parameters
configuration_uuid
required
string <uuid> (uuid)
Example: configuration_uuid=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "fail",
  • "data": { }
}

/v2/configurations/ocpp_settings

Create ocpp settings for current logged user's domain (customer)

Request Body schema: application/json
secret
required
string

Customer's secret for ocpp connection authentication The combination of customerShortName + secret grants connection permission.

feature
string
Default: "cms"
Enum: "off" "cms" "proxy"

Specifies the mode of charger interaction management. Options:

  • off: Third party manages charger interaction and updates Ampcontrol through API.
  • cms: Ampcontrol manages direct charger interaction.
  • proxy: Ampcontrol manages direct charger interaction and forwards data to a third party system.
targetCmsUrl
string

When using feature=proxy, the targetCmsUrl sets the CMS that handles request/operations/messages. Ignored otherwise

defaultNetworkId
string <uuid>

The Catch-all network. All new chargers that connect successfully to the CMS, will be created in this network.

Responses

Request samples

Content type
application/json
{
  • "secret": "dummy-s3cr3t",
  • "feature": "proxy",
  • "targetCmsUrl": "wss://dummy.cms-url.com/",
  • "defaultNetworkId": "03a2c917-143b-5f68-9c63-04426bc73f36"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/configurations/ocpp_settings

Fetch ocpp settings for current logged user's domain (customer)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/configurations/ocpp_settings

Update ocpp settings for current logged user's domain (customer)

Request Body schema: application/json
secret
string

Customer's secret for ocpp connection authentication The combination of customerShortName + secret grants connection permission.

feature
string
Default: "cms"
Enum: "off" "cms" "proxy"

Specifies the mode of charger interaction management. Options:

  • off: Third party manages charger interaction and updates Ampcontrol through API.
  • cms: Ampcontrol manages direct charger interaction.
  • proxy: Ampcontrol manages direct charger interaction and forwards data to a third party system.
targetCmsUrl
string

When using feature=proxy, the targetCmsUrl sets the CMS that handles request/operations/messages. Ignored otherwise

defaultNetworkId
string <uuid>

The Catch-all network. All new chargers that connect successfully to the CMS, will be created in this network.

Responses

Request samples

Content type
application/json
{
  • "secret": "dummy-s3cr3t",
  • "feature": "proxy",
  • "targetCmsUrl": "wss://dummy.cms-url.com/",
  • "defaultNetworkId": "03a2c917-143b-5f68-9c63-04426bc73f36"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/configurations/ocpp_settings/charge_points/{id}

Fetch charge point ocpp settings.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/configurations/ocpp_settings/charge_points/{id}

Create charge point ocpp settings

Request Body schema: application/json
secret
string

Charge point's secret for ocpp connection authentication The combination of customerShortName + secret grants connection permission.

feature
string
Default: "cms"
Enum: "off" "cms" "proxy"

Specifies the mode of charger interaction management. Options:

  • off: Third party manages charger interaction and updates Ampcontrol through API.
  • cms: Ampcontrol manages direct charger interaction.
  • proxy: Ampcontrol manages direct charger interaction and forwards data to a third party system.

Responses

Request samples

Content type
application/json
{
  • "secret": "dummy-s3cr3t",
  • "feature": "proxy"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/configurations/ocpp_settings/charge_points/{id}

Update ocpp settings for current logged user's domain (customer)

Request Body schema: application/json
secret
string

Charge point's secret for ocpp connection authentication The combination of customerShortName + secret grants connection permission.

feature
string
Default: "cms"
Enum: "off" "cms" "proxy"

Specifies the mode of charger interaction management. Options:

  • off: Third party manages charger interaction and updates Ampcontrol through API.
  • cms: Ampcontrol manages direct charger interaction.
  • proxy: Ampcontrol manages direct charger interaction and forwards data to a third party system.

Responses

Request samples

Content type
application/json
{
  • "secret": "dummy-s3cr3t",
  • "feature": "proxy"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

Connectors

About current types

The currentType field refers to the type of the electrical connection of the connector. It differentiates between AC (alternating currrent) single phase systems, different types of AC three-phase systems and DC (direct current) systems.
It is used for energy calculations and conversions.

A single-phase power system consists of a two-wire AC power circuit. On the other hand, a three-phase power system consists of a three-wire AC power circuit. In such a three-phase system the three voltage phase angles are 120 degrees apart.

As a summary:

  • DC: Direct current
  • AC_phase3_LN: Three-phased system, voltage is measured from line to neutral
  • AC_phase3_LL: Three-phased system, voltage is measured from line to line
  • AC_phase1: Single-phased system

About power factor and performance:

The PF (power factor) of an AC power system is the ratio of the real power absorbed by the load to the apparent power flowing in the circuit. Real power represents the amount of work per time that is actually performed. The apparent power can be higher than the real power due to a non-linear load that distorts the wave shape of the current drawn from the source. If the apparent power is higher than the real power, more current flows in the circuit than would be required to transfer real power alone. A power factor magnitude of less than one indicates the voltage and current are not in phase.

Typically, the power factor ranges between 0.85 and 1. It is required for converting to power values when only Volts and Ampéres are reported. While creating or modifying a connector and depending on the currentType set, the PF will participate as follows:

P = PCF × PF × I × V / 1000

Where:

  • P: Power (in kW).
  • PCF (Power conversion factor):
    • = 1 if currentType is AC_phase1 or DC
    • = √3 if currentType is AC_phase3_LL
    • = 3 if currentType is AC_phase3_LN
  • PF: Power factor
  • I: Current (in A).
  • V: Voltage (in V).

/v2/connectors/

Add connector.

Request Body schema: application/json
chargePointId
required
string <uuid> (uuid)
connectorId
required
number <int32>

Connector ID, typically 1-4.

currentType
required
string (current_type)
Enum: "DC" "AC_phase3_LN" "AC_phase3_LL" "AC_phase1"
name
string
voltage
required
integer

Voltage is in Volts. Must be >= 120.

plugType
string (plug_type)
Enum: "CCS1" "CCS2" "CHAdeMO" "GB/T" "Type 1" "Type 2" "Tesla"
plugPowerLevel
string (plug_power_level)
Enum: "Level 1" "Level 2" "DCFC"
ocppStatus
string (connector_ocpp_status)
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted" "Unavailable"

Value from OCPP StatusNotification message.

ocppStatusUpdate
string <date-time> (datetime)

ISO 8601.

ocpiStatus
string (connector_ocpi_status)
Enum: "AVAILABLE" "BLOCKED" "CHARGING" "INOPERATIVE" "OUTOFORDER" "PLANNED" "REMOVED" "RESERVED" "UNKNOWN"

Value from OCPI EVSE's status

priority
number or null <integer> (connector_priority) [ 0 .. 5 ]

Priority assigned to charging sessions on the connector. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
currentChargingLoad
number or null <float>

Current charging load of the connector (in kW).

maxAmperage
number or null <float>

Max connector's current (in A)

maxCapacity
required
number <float> >= 0

Maximum allowed power on this resource in kW (Kilowatt).

powerFactor
number <float>

Efficiency percentage factor. For further details of its contribution in performance, check Connectors description.

Responses

Request samples

Content type
application/json
{
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "connectorId": 1,
  • "currentType": "DC",
  • "name": "EVSE 1 Con 1",
  • "voltage": 230,
  • "plugType": "CHAdeMO",
  • "plugPowerLevel": "Level 1",
  • "ocppStatus": "Available",
  • "ocppStatusUpdate": "2020-10-11T08:19:00",
  • "ocpiStatus": "AVAILABLE",
  • "priority": 5,
  • "currentChargingLoad": 2.3,
  • "maxAmperage": 5,
  • "maxCapacity": 22,
  • "powerFactor": 0.93
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/connectors/

The list of connectors.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
Array of strings <uuid> (uuid) [ items <uuid > ]
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint. Supports multiple values e.g. chargepoint=uuid1&chargepoint=uuid2.

connectorId
Array of integers
Example: connectorId=2

Filter by the connectorId. Supports multiple values e.g. connectorId=2&connectorId=1.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

ocppStatus
Array of strings (connector_ocpp_status)
Items Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted" "Unavailable"
Example: ocppStatus=Available

Filter by OCPP status. Supports multiple values e.g. ocppStatus=Charging&ocppStatus=Available.

priority
Array of numbers or null <integer> (connector_priority) [ items <integer > [ 0 .. 5 ] ]
Example: priority=5

Priority assigned to charging sessions on the connector. Supports multiple values e.g. priority=4&priority=5.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
currentType
string
Enum: "AC" "DC"

Filter by connector current type

plugType
Array of strings (plug_type)
Items Enum: "CCS1" "CCS2" "CHAdeMO" "GB/T" "Type 1" "Type 2" "Tesla"
Example: plugType=CHAdeMO

The connector's plug type. Supports multiple values e.g. plugType=CHAdeMO&plugType=CCS2.

search
string

This is a string search that compares to a number of different strings like connector name, connector Id (UUID), charger name, or charger Id (UUID).

sort
string`^(chargerName|connectorId|currentType|maxCap...
Example: sort=name:desc

Sort by specific values. Defaults to 'active' in descending order. Accepted values: chargerName, connectorId, currentType, maxCapacity, name, ocppStatus, plugType, powerFactor, priority, voltage. Accepted ordering: asc, desc.

updated
string <date-time> (datetime)
Example: updated=2020-10-11T08:19:00

Filters connectors with an updated timestamp greater than or equal to the specified value.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/connectors/{id}

Get connector details.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/connectors/{id}

Update a connector.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
chargePointId
required
string <uuid> (uuid)
connectorId
required
number <int32>

Connector ID, typically 1-4.

currentType
required
string (current_type)
Enum: "DC" "AC_phase3_LN" "AC_phase3_LL" "AC_phase1"
name
string
voltage
required
integer

Voltage is in Volts. Must be >= 120.

plugType
string (plug_type)
Enum: "CCS1" "CCS2" "CHAdeMO" "GB/T" "Type 1" "Type 2" "Tesla"
plugPowerLevel
string (plug_power_level)
Enum: "Level 1" "Level 2" "DCFC"
ocppStatus
string (connector_ocpp_status)
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted" "Unavailable"

Value from OCPP StatusNotification message.

ocppStatusUpdate
string <date-time> (datetime)

ISO 8601.

ocpiStatus
string (connector_ocpi_status)
Enum: "AVAILABLE" "BLOCKED" "CHARGING" "INOPERATIVE" "OUTOFORDER" "PLANNED" "REMOVED" "RESERVED" "UNKNOWN"

Value from OCPI EVSE's status

priority
number or null <integer> (connector_priority) [ 0 .. 5 ]

Priority assigned to charging sessions on the connector. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
currentChargingLoad
number or null <float>

Current charging load of the connector (in kW).

maxAmperage
number or null <float>

Max connector's current (in A)

maxCapacity
required
number <float> >= 0

Maximum allowed power on this resource in kW (Kilowatt).

powerFactor
number <float>

Efficiency percentage factor. For further details of its contribution in performance, check Connectors description.

Responses

Request samples

Content type
application/json
{
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "connectorId": 1,
  • "currentType": "DC",
  • "name": "EVSE 1 Con 1",
  • "voltage": 230,
  • "plugType": "CHAdeMO",
  • "plugPowerLevel": "Level 1",
  • "ocppStatus": "Available",
  • "ocppStatusUpdate": "2020-10-11T08:19:00",
  • "ocpiStatus": "AVAILABLE",
  • "priority": 5,
  • "currentChargingLoad": 2.3,
  • "maxAmperage": 5,
  • "maxCapacity": 22,
  • "powerFactor": 0.93
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/connectors/{id}

Delete a connector.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Diagnostics

/v2/diagnostics

Return all diagnostics.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint ID.

user
string <uuid>
Example: user=e5e28f7a-6284-4682-bfff-88a2cfae1b64

Filter by user ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/diagnostics

Request diagnostics from charger.

query Parameters
chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint ID.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/diagnostics/{diagnostics_uuid}

Return specific diagnostics info.

path Parameters
diagnostics_uuid
required
string <uuid>
Example: 4f4f1d5f-5e0e-4c4f-bc3a-2b2b2b2b2b2b

Diagnostics UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/diagnostics/{diagnostics_uuid}/download

Download diagnostics from system.

path Parameters
diagnostics_uuid
required
string <uuid>
Example: 4f4f1d5f-5e0e-4c4f-bc3a-2b2b2b2b2b2b

Diagnostics UUID

Responses

DR Events

/v2/dr_events/

Add a demand response (DR) event response record. Our algorithms support the execution of DR requests in the form of load curtailment by reducing the available variable network capacity by a given “load amount” for a certain time period, or in the form of power generation through discharging vehicles that are connected to the network by a given “discharge amount”.

Request Body schema: application/json
networkId
string <uuid> (uuid)
Array of objects (demand_response_write_required)

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "drEvents": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/dr_events/

List DR Events for a network

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/dr_events/{id}

Get DR Event

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/dr_events/{id}

Update a DR Event

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
start
string <date-time>
Default: "Current time"

Start of the demand response period ISO 8601.

end
string <date-time>
Default: "Current time + 24 hours"

End of the demand response period ISO 8601.

value
number <float>

In kW (Kilowatt). If Load Amount, the value is the load reduction on the network. If V2G, the value is the provided power from the network.

type
string
Enum: "Load Amount" "V2G"

Demand Response type

Responses

Request samples

Content type
application/json
{
  • "start": "2020-10-11T08:19:00+00:00",
  • "end": "2020-10-11T08:19:00+00:00",
  • "value": 22,
  • "type": "Load Amount"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/dr_events/{id}

Delete a DR Event

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Events

/v2/events/

Queries and returns the events corresponding to a network. A default 24 hours range will be applied if start is not specified

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

alert
string <uuid> (uuid)
Example: alert=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by alert.

category
string
Enum: "Delivery" "Optimization"

Optimization or delivery event logs will include a category value.

charger
string <uuid>
Example: charger=f0adb0c5-31b7-4a36-8052-de019a1a1638

Filter event source by charger's uuid

connector
string <uuid>
Example: connector=684ce4d6-6267-490f-b7f1-4ad0874d2453

Filter event source by connector's uuid

sessionSource
string
Enum: "regular" "alert" "notification"

Session source for event logging

sort
string
Enum: "datetime" "urgency" "source" "category"

Sort by specific values. Defaults to 'eventTime' in descending order. Accepted values: datetime, urgency, source, category. Accepted ordering: asc, desc.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/events/{event_uuid}

Modifies and returns the corresponding event

Request Body schema: application/json
status
string
Enum: "Triggered" "Acknowledged" "Resolved" "Pending"

Responses

Request samples

Content type
application/json
{
  • "status": "Triggered"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Firmwares

/v2/firmwares

Return all firmwares.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

name
string
Example: name=v1.2.3

Filter by firmware name

filename
string
Example: filename=firmware-1.2.3.bin

Filter by firmware file name

created
string <date-time>
Example: created=2023-08-31T14-56-54.05437+00:00

Filter by created timestamp

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/firmwares

Store a firmware.

Request Body schema: application/json
name
string or null

Firmware name

Responses

Request samples

Content type
application/json
{
  • "name": "firmware-1.2.3.bin"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/firmwares/{firmware_uuid}

Return specific firmware info.

path Parameters
firmware_uuid
required
string <uuid>
Example: 4f4f1d5f-5e0e-4c4f-bc3a-2b2b2b2b2b2b

Firmware UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

Id tags

/v2/id_tags/

Create an id tag

Request Body schema: application/json
value
required
string

Id tag's value. Should not exceed a length of 20 characters

priority
required
number or null <integer> (id_tag_priority) [ 0 .. 5 ]

Priority assigned to charging sessions when the id tag is associated. This takes precedence over connector priority. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
group
required
string
Enum: "RFID" "credit card reader" "VID or MAC address"
vehicleId
string <uuid> (uuid)
listVersion
number
customGroup
string

Custom group name to group idTags

disabled
boolean

If set to true, the idTag will be disabled and not authorize the charge.

Responses

Request samples

Content type
application/json
{
  • "value": "FHH92JFNMSK93",
  • "priority": 5,
  • "group": "RFID",
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "listVersion": 4,
  • "customGroup": "Depot One Group",
  • "disabled": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/id_tags/

List Id tags messages for the current user

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

value
string

The idTag value.

customGroup
Array of strings

Custom group name to group idTags. Supports multiple values e.g. customGroup=RFID&customGroup=VID or MAC address.

priority
Array of int

The idTag priority. Supports multiple values e.g. priority=1&priority=2.

search
string

String-based search to find id tags based on a substring by value, related vehicle name or id."

group
Array of strings

The group name of the idTags. Supports multiple values e.g. group=RFID&group=VID or MAC address.

vehicleId
Array of UUID

The vehicle associated to the idTag. Supports multiple values e.g. vehicleId=UUID1&vehicleId=UUID2.

sort
string
Enum: "customGroup:desc" "customGroup:asc" "group:desc" "group:asc" "priority:desc" "priority:asc" "value:desc" "value:asc" "vehicleName:desc" "vehicleName:asc" "disabled:desc" "disabled:asc"

Sort by specific values.

disabled
boolean

If set to true, returns all idTags that are disabled.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/id_tags/

Bulk update id tags.

Request Body schema: application/json
ids
Array of strings <uuid> (uuid) [ items <uuid > ]
object
object

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "filters": {
    },
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 1
}

/v2/id_tags/{id}

Fetch a specific id tag

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/id_tags/{id}

Update an Id tag.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
value
string

Id tag's value. Should not exceed a length of 20 characters

priority
number or null <integer> (id_tag_priority) [ 0 .. 5 ]

Priority assigned to charging sessions when the id tag is associated. This takes precedence over connector priority. Default value is 3.

  • 0 = Opt-Out / Will receive maximum power if possible
  • 1 = Very High
  • 2 = High
  • 3 = Medium
  • 4 = Low
  • 5 = Very Low
group
string
Enum: "RFID" "credit card reader" "VID or MAC address"
vehicleId
string <uuid> (uuid)
listVersion
number
customGroup
string

Custom group name to group idTags

disabled
boolean

If set to true, the idTag will be disabled and not authorize the charge.

Responses

Request samples

Content type
application/json
{
  • "value": "FHH92JFNMSK93",
  • "priority": 5,
  • "group": "RFID",
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "listVersion": 4,
  • "customGroup": "Depot Two Group",
  • "disabled": false
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/id_tags/{id}

Delete an Id tag.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/id_tags/custom_groups

Return a list of unique custom groups for the current customer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/id_tags/csv

This is an endpoint used to create id_tags in bulk through a CSV file. The file must be a maximum of 600 kilobytes and have the following format Required - Name, Required - Type, Priority, Group, Vehicle (UUID), Disabled Status.

Request Body schema: text/csv
id_tag_in
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 50
}

KPIs

Get KPIs for several metrics such as connectivity and uptime.

Time filters

All KPI endpoints have a start and end query parameters to indicate the evaluation period. Default: last week.

If only start is specified, end will be set to start + 1 week.

If only end is specified, start will be set to end - 1 week.

/v2/kpis/connectivity/network

Get network connectivity KPI.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/connectivity/charge_points

Get charge points connectivity KPI.

query Parameters
network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/uptime/network

Get network uptime KPI.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/uptime/charge_points

Get charge points connectivity KPI.

query Parameters
network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

aggregate_by_connector
any <boolean>
Default: true

When set to 'true,' this parameter enables the calculation of uptime using connector-level data. Alternatively, when set to 'false,' charger-level uptime data will be utilized for uptime calculations.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/uptime/connectors

Get connectors uptime KPI.

query Parameters
network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/vehicles/energy_usage

Retrieve energy efficiency data for vehicles.

query Parameters
vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/kpis/supply_rates

Get supply rate of KPI on network level.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by Connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 2
}

Meter values

/v2/meter_values/

Send meter values from active connectors. Ampcontrol currently accepts the following measurands:

  • Power.Active.Import with units W or kW
  • Power.Active.Export with units W or kW
  • Power.Offered with units W or kW
  • Power.Reactive.Export with units varh or kvarh
  • Power.Reactive.Import with units varh or kvarh
  • Power.Factor with no units
  • Energy.Active.Import.Register with units Wh or kWh
  • Energy.Active.Export.Register with units Wh or kWh
  • Energy.Reactive.Export.Register with units Wh or kWh
  • Energy.Active.Export.Interval with units Wh or kWh
  • Energy.Active.Import.Interval with units Wh or kWh
  • Energy.Reactive.Export.Interval with units varh or kvarh
  • Energy.Reactive.Import.Interval with units varh or kvarh
  • Current.Export with units A
  • Current.Import with units A
  • Current.Offered with units A
  • Frequency with no units
  • RPM with no units
  • SoC with units Percent
  • Temperature with units K, Celsius or Fahrenheit
  • Voltage with units V

If the connector is not measuring the meter values at a specific phase, you can leave the field phase empty.

If the connector measures multiple measurands, you can send all measurands for that connector in one single request, using the array. A maximum of 100 meter values can be sent in a single request. Each meter value can contain a maximum of 50 samples.

Either chargePointId and connectorId (together) or vehicleId are required.

In case your network has optimizeWithMeterValue on, submitting meter values can trigger a reoptimization and send out new limits to your network.

Request Body schema: application/json
chargePointId
required
string <uuid>

UUID of the parent charge point.

required
number or string

Connector ID, or UUID.

number or string

EVSE ID, or UUID.

vehicleId
string <uuid>

UUID of the vehicle.

required
Array of objects
transactionId
integer

Transaction ID associated with the meter values.

Responses

Request samples

Content type
application/json
{
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "connectorId": 1,
  • "evseId": 1,
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "meterValues": [
    ],
  • "transactionId": 92813645
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/meter_values/

List meter values. One of network, charger, vehicle, evse (for OCPP 2.0.1 chargers) or connector must be specified.

query Parameters
connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

evse
string <uuid> (uuid)
Example: evse=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by EVSE.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

start
required
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
required
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Networks

/v2/networks/

Create a network. The objective field determines how the network is optimized. Default value is off.

Objective Description
load_sharing Avoids peak power. Distributes available power among charging sessions. No vehicle data required.
fleet Avoids peak power and delays. Schedules sessions sequentially and distributes the available power to ensure on-time departure. All charging sessions require a link to a vehicle.
vehicle_to_grid Directs vehicles to discharge energy back to the grid according to network constraints and a V2G demand response event.
off Disable the delivery of optimized charging profiles to chargers.
Request Body schema: application/json
name
required
string

Helps to identify your network on the UI.

location
string or null

Location description for humans.

latitude
number or null <float>

Network location's latitude. Positive or negative value indicates North or South respectively.

longitude
number or null <float>

Network location's longitude. Positive or negative value indicates East or West respectively.

address
string or null
country
string
city
string or null
state
string or null
zipCode
string or null
objective
string (optimization_methods)
Enum: "load_sharing" "load_sharing_network_group (required if using sub networks)" "fleet" "vehicle_to_grid" "off"

Objective of optimization process, the default is off, if set to off no optimized profile will be delivered to chargers.

timeZone
string

Time zone in IANA zoneinfo format. Default is 'UTC'.

maxCapacityBuffer
number
Default: 0.02

A percentage buffer is applied to the maximum capacity of a charging network to prevent power violations. It is designed to account for delays in the charger's response to new charging profiles, which can cause sudden increases in demand that exceed the set network's capacity. We recommend setting a buffer between 2% and 5%.

webhook
string or null

URL for the delivery of optimization profiles. Webhook events are signed with an X-Webhook-Signature HTTP header. This string contains the HMAC sha256 digest output of your webhook secret + request body and can be used to verify that the request comes from a trusted source. If the webhook response status is a 404 then the charge session is ended.

webhookSecret
string or null

Webhook secret string used for authentication

connectorPowerStep
number

Allowed maximum resolution of charging limits in kW.

optimizeWithMeterValue
boolean
Default: true

Dynamic load management optimization is made far more accurate by utilizing live meter values. Ampcontrol reallocates power from charging sessions that charge slower than expected to other charging sessions that potentially can charge faster. Turn this off if you want to use a less dynamic load management that does not consider the live charging power. We recommend keeping this turned on.

solarActive
boolean
Default: false

By default solar_metering values posted to our API will not have an impact on the optimizations of your network. Once this field is set to true, the real-time solar meterings and a solar forecast will be will be considered when calculating the optimizations. The resulting estimated solar power is treated as additional capacity in your network.

closeIdleSessions
boolean
Default: true

Some charge points don't always close charging sessions correctly. Keep this on if you want Ampcontrol to identify and close deprecated charging sessions automatically. Turning this off typically results in a less efficient optimization. We recommend keeping this turned on.

reservedPower
number or null <float>

The optimization reserves this power on the inactive connectors (to reserve power at the charger level, set connectorReservedPowerSplit to False). Unit is in kW (Kilowatt). The default is 1 kW (same as the connectorMinimumLoad). If the user sets a reservedPower > the connector's maxCapacity, the optimization reserves only the maxCapacity. The value set must be greater than or equal to the connectorMinimumLoad value.

defaultEnergyPrice
number or null <float>

The default energy price for the network to be used if the objective is fleet_with_tou_rates

connectorMinimumLoad
number <float>
Default: 1

The charging behavior of your charger may be impacted by its minimum power limit. The default is 1 kW. In some cases, if the charger receives a power input under 1 kW, it may enter sleep mode or end the charging session. To prevent this from happening, we suggest configuring a minimum power limit within the range of 1 kW to 5 kW. Suggested values by charger type: DC: 1 kW AC 3 Phase (US): 2,2 kW AC 3 Phase (EU): 4,2 kW AC 1 Phase (US): 0.8 kW AC 1 Phase (EU): 1.4 kW

Array of objects or null (fleetSchedule)

This is an experimental feature that works with fleet scheduling network objectives only (see the objective field above).

startSessionsWithMeterValues
boolean
Default: true

Some charge points do not always start charging sessions correctly. Keep this on if you want Ampcontrol to identify and automatically start such sessions. Turning this off can result in chargers with deprecated or not fully OCPP-compliant firmware charging without an active session on Ampcontrol, which can negatively impact the load management functionality. We recommend keeping this turned on.

eventLogging
boolean
Default: true

Flag attribute that toggles the event sesson registration for the current network.

enableAnalytics
boolean
Default: false

Flag attribute that toggles the collection of analytics data and periodical generation of analytics reports.

baseloadActive
boolean
Default: false

Activate the consideration of the baseload power as part of the overall network load.

baseloadPeak
number or null <float>

Worst case estimate of the maximum baseload power of the network in kW.

baseloadAvgYearlyConsumption
number or null <float>

The average yearly consumption of the baseload in kWh.

baseloadBuildingType
string or null
Enum: "office" "industry"

The type of the connected building loads, e.g., "office" or "industry".

connectorReservedPowerSplit
boolean
Default: true

If set to True, the reserved power will be split per connector.

priceConstraintsActive
boolean

If set to True, the price constraints will be taken into account for the optimizations.

currency
string
Enum: "USD" "EUR"

Currency setting for the network. ISO 4217 currency codes are accepted.

onTimeDeparture
boolean or null

Enables a check to evaluate if soft constraints (s.a. price constraints, demand response, etc.) will allow fleet vehicles to depart on time. If not, then the price constraints are removed and reoptimization occurs.

geofenceRadius
number or null

Radius of the circle-shaped geofence around the network. It should encapsulate all areas the vehicles park. In meters.

ocpiLocation
boolean or null

Enables OCPI functionality for the network

defaultTariff
number or null [ 0 .. 1000 )

a The default energy tariff used when generating CDRs (v2/cdrs) and in OCPI generated CDRs when OCPI tariffs are not added. This value is not considered during tariff optimization, it is only the customer facing tariff. Currency units are not directly used in CDRs but the currency field may help to infer the dimension. The value range is inclusive-exclusive between 0 and 1000.

defaultTax
number or null [ 0 .. 1 ]

The default tax percentage applied to calculate incl_vat fields for OCPI generated CDRs, in cost-related attributes (total_cost, total_energy_cost, total_time_cost) when OCPI tariffs are not added. This value is not considered during tariff optimization, it is only the customer facing tariff. The value range is between 0 and 1.0 inclusive.

vehicleGroupPriority
string or null
Enum: "fair distribution" "unknown vehicles" "known vehicles"

Option to allocate power fairly to all vehicles or prioritize by vehicle group (known/unknown vehicles). The default is set to fair distribution, all vehicles are treated the same and power allocation is fair. To prioritize known or unknown vehicles, you can set this field to known vehicles or unknown vehicles , respectively. Only works in conjunctiton with Fleet as the optimization objective.

maxCapacity
required
number <float>

Maximum allowed power on this resource in kW (Kilowatt).

Responses

Request samples

Content type
application/json
{
  • "name": "Network 10",
  • "location": "New York",
  • "latitude": 32.2431,
  • "longitude": 115.793,
  • "address": "9400 S Normandie Ave #14",
  • "country": "United States",
  • "city": "Los Angeles",
  • "state": "California",
  • "zipCode": 90001,
  • "objective": "load_sharing",
  • "timeZone": "America/Chicago",
  • "maxCapacityBuffer": 0.1,
  • "webhook": "https://yourdomainexample.com/my/webhook/endpoint",
  • "webhookSecret": "PWpJ68GBtN",
  • "connectorPowerStep": 0.01,
  • "optimizeWithMeterValue": true,
  • "solarActive": false,
  • "closeIdleSessions": true,
  • "reservedPower": 22,
  • "defaultEnergyPrice": 0.3,
  • "connectorMinimumLoad": 4.2,
  • "fleetSchedule": [
    ],
  • "startSessionsWithMeterValues": true,
  • "eventLogging": true,
  • "enableAnalytics": true,
  • "baseloadActive": true,
  • "baseloadPeak": 400,
  • "baseloadAvgYearlyConsumption": "2,000",
  • "baseloadBuildingType": "office",
  • "connectorReservedPowerSplit": true,
  • "priceConstraintsActive": true,
  • "currency": "USD",
  • "onTimeDeparture": true,
  • "geofenceRadius": 140.5,
  • "ocpiLocation": false,
  • "defaultTariff": 50,
  • "defaultTax": 0.25,
  • "vehicleGroupPriority": "fair distribution",
  • "maxCapacity": 22
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/networks/

List networks.

query Parameters
vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

updated
string <date-time>
Example: updated=2020-10-11T08:19:00+00:00

Returns objects updated after the specified timestamp.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/networks/{network_uuid}

Get network details.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/networks/{network_uuid}

Update a network.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
name
string

Helps to identify your network on the UI.

location
string or null

Location description for humans.

latitude
number or null <float>

Network location's latitude. Positive or negative value indicates North or South respectively.

longitude
number or null <float>

Network location's longitude. Positive or negative value indicates East or West respectively.

address
string or null
country
string
city
string or null
state
string or null
zipCode
string or null
objective
string (optimization_methods)
Enum: "load_sharing" "load_sharing_network_group (required if using sub networks)" "fleet" "vehicle_to_grid" "off"

Objective of optimization process, the default is off, if set to off no optimized profile will be delivered to chargers.

timeZone
string

Time zone in IANA zoneinfo format. Default is 'UTC'.

maxCapacityBuffer
number
Default: 0.02

A percentage buffer is applied to the maximum capacity of a charging network to prevent power violations. It is designed to account for delays in the charger's response to new charging profiles, which can cause sudden increases in demand that exceed the set network's capacity. We recommend setting a buffer between 2% and 5%.

webhook
string or null

URL for the delivery of optimization profiles. Webhook events are signed with an X-Webhook-Signature HTTP header. This string contains the HMAC sha256 digest output of your webhook secret + request body and can be used to verify that the request comes from a trusted source. If the webhook response status is a 404 then the charge session is ended.

webhookSecret
string or null

Webhook secret string used for authentication

connectorPowerStep
number

Allowed maximum resolution of charging limits in kW.

optimizeWithMeterValue
boolean
Default: true

Dynamic load management optimization is made far more accurate by utilizing live meter values. Ampcontrol reallocates power from charging sessions that charge slower than expected to other charging sessions that potentially can charge faster. Turn this off if you want to use a less dynamic load management that does not consider the live charging power. We recommend keeping this turned on.

solarActive
boolean
Default: false

By default solar_metering values posted to our API will not have an impact on the optimizations of your network. Once this field is set to true, the real-time solar meterings and a solar forecast will be will be considered when calculating the optimizations. The resulting estimated solar power is treated as additional capacity in your network.

closeIdleSessions
boolean
Default: true

Some charge points don't always close charging sessions correctly. Keep this on if you want Ampcontrol to identify and close deprecated charging sessions automatically. Turning this off typically results in a less efficient optimization. We recommend keeping this turned on.

reservedPower
number or null <float>

The optimization reserves this power on the inactive connectors (to reserve power at the charger level, set connectorReservedPowerSplit to False). Unit is in kW (Kilowatt). The default is 1 kW (same as the connectorMinimumLoad). If the user sets a reservedPower > the connector's maxCapacity, the optimization reserves only the maxCapacity. The value set must be greater than or equal to the connectorMinimumLoad value.

defaultEnergyPrice
number or null <float>

The default energy price for the network to be used if the objective is fleet_with_tou_rates

connectorMinimumLoad
number <float>
Default: 1

The charging behavior of your charger may be impacted by its minimum power limit. The default is 1 kW. In some cases, if the charger receives a power input under 1 kW, it may enter sleep mode or end the charging session. To prevent this from happening, we suggest configuring a minimum power limit within the range of 1 kW to 5 kW. Suggested values by charger type: DC: 1 kW AC 3 Phase (US): 2,2 kW AC 3 Phase (EU): 4,2 kW AC 1 Phase (US): 0.8 kW AC 1 Phase (EU): 1.4 kW

Array of objects or null (fleetSchedule)

This is an experimental feature that works with fleet scheduling network objectives only (see the objective field above).

startSessionsWithMeterValues
boolean
Default: true

Some charge points do not always start charging sessions correctly. Keep this on if you want Ampcontrol to identify and automatically start such sessions. Turning this off can result in chargers with deprecated or not fully OCPP-compliant firmware charging without an active session on Ampcontrol, which can negatively impact the load management functionality. We recommend keeping this turned on.

eventLogging
boolean
Default: true

Flag attribute that toggles the event sesson registration for the current network.

enableAnalytics
boolean
Default: false

Flag attribute that toggles the collection of analytics data and periodical generation of analytics reports.

baseloadActive
boolean
Default: false

Activate the consideration of the baseload power as part of the overall network load.

baseloadPeak
number or null <float>

Worst case estimate of the maximum baseload power of the network in kW.

baseloadAvgYearlyConsumption
number or null <float>

The average yearly consumption of the baseload in kWh.

baseloadBuildingType
string or null
Enum: "office" "industry"

The type of the connected building loads, e.g., "office" or "industry".

connectorReservedPowerSplit
boolean
Default: true

If set to True, the reserved power will be split per connector.

priceConstraintsActive
boolean

If set to True, the price constraints will be taken into account for the optimizations.

currency
string
Enum: "USD" "EUR"

Currency setting for the network. ISO 4217 currency codes are accepted.

onTimeDeparture
boolean or null

Enables a check to evaluate if soft constraints (s.a. price constraints, demand response, etc.) will allow fleet vehicles to depart on time. If not, then the price constraints are removed and reoptimization occurs.

geofenceRadius
number or null

Radius of the circle-shaped geofence around the network. It should encapsulate all areas the vehicles park. In meters.

ocpiLocation
boolean or null

Enables OCPI functionality for the network

defaultTariff
number or null [ 0 .. 1000 )

a The default energy tariff used when generating CDRs (v2/cdrs) and in OCPI generated CDRs when OCPI tariffs are not added. This value is not considered during tariff optimization, it is only the customer facing tariff. Currency units are not directly used in CDRs but the currency field may help to infer the dimension. The value range is inclusive-exclusive between 0 and 1000.

defaultTax
number or null [ 0 .. 1 ]

The default tax percentage applied to calculate incl_vat fields for OCPI generated CDRs, in cost-related attributes (total_cost, total_energy_cost, total_time_cost) when OCPI tariffs are not added. This value is not considered during tariff optimization, it is only the customer facing tariff. The value range is between 0 and 1.0 inclusive.

vehicleGroupPriority
string or null
Enum: "fair distribution" "unknown vehicles" "known vehicles"

Option to allocate power fairly to all vehicles or prioritize by vehicle group (known/unknown vehicles). The default is set to fair distribution, all vehicles are treated the same and power allocation is fair. To prioritize known or unknown vehicles, you can set this field to known vehicles or unknown vehicles , respectively. Only works in conjunctiton with Fleet as the optimization objective.

maxCapacity
number <float>

Maximum allowed power on this resource in kW (Kilowatt).

Responses

Request samples

Content type
application/json
{
  • "name": "Network 10",
  • "location": "New York",
  • "latitude": 32.2431,
  • "longitude": 115.793,
  • "address": "9400 S Normandie Ave #14",
  • "country": "United States",
  • "city": "Los Angeles",
  • "state": "California",
  • "zipCode": 90001,
  • "objective": "load_sharing",
  • "timeZone": "America/Chicago",
  • "maxCapacityBuffer": 0.1,
  • "webhook": "https://yourdomainexample.com/my/webhook/endpoint",
  • "webhookSecret": "PWpJ68GBtN",
  • "connectorPowerStep": 0.01,
  • "optimizeWithMeterValue": true,
  • "solarActive": false,
  • "closeIdleSessions": true,
  • "reservedPower": 22,
  • "defaultEnergyPrice": 0.3,
  • "connectorMinimumLoad": 4.2,
  • "fleetSchedule": [
    ],
  • "startSessionsWithMeterValues": true,
  • "eventLogging": true,
  • "enableAnalytics": true,
  • "baseloadActive": true,
  • "baseloadPeak": 400,
  • "baseloadAvgYearlyConsumption": "2,000",
  • "baseloadBuildingType": "office",
  • "connectorReservedPowerSplit": true,
  • "priceConstraintsActive": true,
  • "currency": "USD",
  • "onTimeDeparture": true,
  • "geofenceRadius": 140.5,
  • "ocpiLocation": false,
  • "defaultTariff": 50,
  • "defaultTax": 0.25,
  • "vehicleGroupPriority": "fair distribution",
  • "maxCapacity": 22
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/networks/{network_uuid}

Delete a network.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

OCPP Events

Event tracking service that fetches from logs belonging to the OCPP/CMS service.

/v2/ocpp_events/

Queries customer's ocpp/CMS-related events. A default 24 hours range will be applied if start and/or end are not specified.

query Parameters
chargepoint_serial
string (chargepoint_serial)
Example: chargepoint_serial=XYZ-1234-F34

Charge point serial (corresponding to charge point's ocppId)

chargepoint
string <uuid> (chargepoint_uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Chargepoint's UUID

network
string <uuid> (network_uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Network UUID

source
string (source)
Enum: "regular" "alert"

Event source

status
string (schemas-status)
Enum: "Triggered" "Acknowledged" "Resolved"

Event's status

urgency
string (urgency)
Enum: "Info" "Warning" "Error" "Critical"

Event's urgency

type
string (type)
Enum: "Authentication" "Connection" "Disconnection"

Event's type

start
string <datetime> (start)
Default: "Current time"
Example: start=2022-10-11T08:15:00

Start time filter over eventTime field

end
string <datetime> (end)
Default: "Current time + 24 hours"
Example: end=2022-10-11T08:20:00

End time filter over eventTime field

limit
integer <1-1000> (limit)
Default: 100
Example: limit=50

Pagination limit

offset
integer <0-2147483647> (offset)
Default: 0
Example: offset=3

Pagination offset

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

OCPP messages

/v2/ocpp_messages/

send an OCPP message. The charger must have an ocppId.

Request Body schema: application/json
chargePointId
required
string <uuid> (uuid)
body
required
Array of arrays
url
string <url>

The target websocket URL where the OCPP message was originally sent

source
any
Enum: "Charger" "AmpCMS" "AmpCMS_created" "AmpCMS_queued" "External" "UI" "API"

Source label of where the message comes from. Default: API For consistency reasons, when using the endpoint directly, is recommended to use the default value API, since the rest of available values are for internal use only.

sendToCharger
boolean
Default: false

In case sendToCharger=True the message is sent to the charger.

At the moment sendToCharger messages do not expire. If the charger is offline then the message will be delivered when it connects to the CMS.

operationType
string
protocol
string
Default: "ocpp1.6"
Enum: "ocpp1.6" "ocpp2.0.1"

The OCPP protocol. If not set, 1.6 will be used.

Responses

Request samples

Content type
application/json
{
  • "chargePointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "body": [
    ],
  • "url": "wss://dummy-url.server.io/foo",
  • "source": "API",
  • "sendToCharger": false,
  • "operationType": "StatusNotification",
  • "protocol": "ocpp1.6"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/ocpp_messages/

List OCPP messages for the authenticated user's customer account

query Parameters
chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint. Supports multiple values e.g. chargepoint=uuid1&chargepoint=uuid2

source
any
Enum: "Charger" "AmpCMS" "AmpCMS_created" "AmpCMS_queued" "External" "UI" "API"

Filter by message source. Supports multiple values e.g. source=AmpCMS&source=UI

messageType
any
Enum: "Call" "CallResult" "CallError"

Filter by OCPP message type.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

operationType
any
Enum: "BootNotification" "Heartbeat" "Etc"

Filter by OCPP operation type. Supports multiple values e.g. operationType=BootNotification&operationType=Heartbeat

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

protocol
string
Enum: "ocpp1.6" "ocpp2.0.1"

Filter by OCPP protocol

search
string

Filter by either chargepoint customName or OCPP message operationType

sort
string
Enum: "chargepoint:desc" "chargepoint:asc" "timestamp:desc" "timestamp:asc" "source:desc" "source:asc" "operationType:desc" "operationType:asc"

Sort by specific values. When sorting by chargepoint, the customName is used.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Optimizations

/v2/optimizations/

List optimizations. One of the query parameters connector, charge_point, network or charging_session must be specified.

Returns active optimizations by default. However, when the start and end query parameters are used the relevant optimizations are delivered, even if they are deleted, i.e. inactive. If active is false and no start and end params are passed, a default time window of 7 days is applied.

query Parameters
connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

charging_session
string <uuid> (uuid)
Example: charging_session=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by ChargeSession.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

active
boolean
Example: active=true

filter by active status

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/optimizations/{id}

Get an optimization.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Planned Routes

/v2/planned_routes/

Planned routes are the future vehicle trips. These will be considered when optimizing energy delivery. Planned routes are defined by all the vehicle trips between two charging events. The limit of routes that can be posted is 4000 per call.

Request Body schema: application/json
required
Array of objects (planned_routes)

List of planned routes.

Responses

Request samples

Content type
application/json
{
  • "routes": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/planned_routes/

Fetch planned routes.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

vehicle
Array of strings

Filter by vehicle ID. Supports multiple values e.g. vehicle=UUID-1&vehicle=UUID-2.

vehicle_group
Array of strings

Filter by vehicle group. Supports multiple values e.g. vehicle_group=Group1&vehicle_group=Group2.

search
string

String-based search based on a combination from externalId, vehicle name, vehicleGroup, or planned route ID (UUID).

sort
string
Enum: "distance:desc" "distance:asc" "end:desc" "end:asc" "energy:desc" "energy:asc" "externalId:desc" "externalId:asc" "stateOfCharge:desc" "stateOfCharge:asc" "start:desc" "start:asc" "vehicleGroup:desc" "vehicleGroup:asc" "vehicleName:desc" "vehicleName:asc"

Sort by specific values.

status
Array of strings

The status field is based on start and end fields and can assume one of the values future, live, or past. Supports multiple values e.g. status=future&status=live.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/planned_routes/{id}

Fetch planned route by id.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/planned_routes/{id}

Patch a planned route.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
vehicleGroup
string

Vehicle group name.

vehicleId
string <uuid>

Vehicle id.

externalId
string

External id for the planned route.

start
string <date-time> (start_datetime)
Default: "Current time"

ISO 8601.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"

ISO 8601.

object

At least one of the fields is required.

Responses

Request samples

Content type
application/json
{
  • "vehicleGroup": "vehicleGroupOne",
  • "vehicleId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "externalId": "PlannedRouteOne",
  • "start": "2020-10-11T08:19:00",
  • "end": "2020-10-11T09:19:00",
  • "demand": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/planned_routes/{id}

Delete a planned route.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Prices

/v2/prices/

Add an energy price. All prices must be in $/kWh

Request Body schema: application/json
networkId
required
string <uuid> (uuid)
required
Array of objects (price_item)

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "energyPrices": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/

Fetch energy prices

query Parameters
start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/{price_uuid}

Update energy price

path Parameters
price_uuid
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Price UUID.

Request Body schema: application/json
start
string <date-time>
Default: "Current time"

Date-time interval limit: 7 days
The rate's start date

end
string <date-time>
Default: "Current time + 24 hours"

Date-time interval limit: 7 days
The rate's end date

price
number <float>

Responses

Request samples

Content type
application/json
{
  • "start": "2020-10-11T08:19:00+00:00",
  • "end": "2020-10-11T08:19:00+00:00",
  • "price": 0.32
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/{price_uuid}

Delete specific energy price

path Parameters
price_uuid
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Price UUID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/constraints/

Add a price constraint. All prices must be in $/kWh

Request Body schema: application/json
networkId
required
string <uuid> (uuid)
energyPrice
required
number <float>

All prices must be in $/kWh

maxCapacityRatio
required
number <float> [ 0 .. 1 ]

Value between 0 and 1 which represents a percentage of the network to be made available at a particular price level.

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "energyPrice": 0.32,
  • "maxCapacityRatio": 0.43
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/constraints/

Fetch network price constraints.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/prices/constraints/{price_uuid}

Delete specific price constraint.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Profiles

Changes to profiles endpoints (only applies to /v2/profiles/optimizations/, /v2/profiles/capacities/ and /v2/profiles/meter_values/{type})

To support queries with longer time window (end - start), the limit and offset params have been removed. When querying data between start and end, an ideal data resolution (space between each timeseries point returned) between 1 minute and 1 day is used and the data points are interpolated using a time weighted average methodology. The resolution is determined based on the width of the time window range (end - start). To query data at a higher resolution, you can reduce the width of the query's time window and vice versa.

example: a time window of 2 days will return data points at a 1 minute resolution, custom resolutions are also supported.

About pagination on profiles endpoints

While on other GET endpoints, the limit and offset query params apply normal pagination to define the maximum amount and shifting of data fetched from storage, for profile endpoints their behavior changes.

Due to internal timeseries interpolation procedures, when defining limit, one applies a trailing truncation to the processed data to return the first n=limit values; likewise, when defining offset in the query, the first m=offset values will be shiffted to return, as a result, the time series data corresponding to the interval [offset -> offset + limit].

Finally, the total field returned in the response will quantify the number of data series items before this special pagination was applied.

/v2/profiles/optimizations/

List optimization profiles (in kW). At least one query parameter is required. The same data can be listed with GET /v2/optimizations/ but this endpoint returns time series data in a more compact format. Only one of network, connector, chargepoint, optimization, vehicle or optimization is required and can be submitted. (end - start) < 1 week

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

optimization
string <uuid> (uuid)
Example: optimization=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by optimization ID

charging_session
string <uuid> (uuid)
Example: charging_session=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by ChargeSession.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 7
}

/v2/profiles/prices/

List energy prices for a network (in $). Similar data can be fetched from GET /v2/prices/, but this endpoint returns a continuous time series stream using the network's defaultEnergyPrice for times where no prices are available and resolving price overlaps based on their creation time

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (datetime_utc_minus_12)
Default: "Current time - 12 hours"
Example: start=2020-10-11T08:19:00+00:00

Date-time interval limit: 7 days
Time interval start. Defaults to current utc time minus 12 hours.

end
string <date-time> (datetime_utc_12)
Default: "Current time + 12 hours"
Example: end=2020-10-11T08:19:00+00:00

Date-time interval limit: 7 days
Time interval end. Defaults to current utc time plus 12 hours.

intervalLength
integer
Example: intervalLength=15

Interval length pace for timeseries data items (in minutes, greater or equal to 1).

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 5
}

/v2/profiles/telematics/soc

List telematics soc for a vehicle (in %). This endpoint returns a continuous time series stream.

query Parameters
vehicle
required
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/capacities/

List capacities for a network (in kW). Similar data can be fetched from GET /v2/capacities/, but this endpoint returns a continuous time series stream using the network's maxCapacity for times where no optimization profiles exist and resolving capacity overlaps based on their updated time. Either network or charger must be specified.

query Parameters
network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

charger
string <uuid>
Example: charger=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by charger uuid.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 5
}

/v2/profiles/meter_values/power

Previously profiles/meter_values List of power meter values (in kW) for a network. Similar data can be fetched from GET /v2/meter_values/, but this endpoint resolves meter value overlaps based on their creation time and converts Wh and kWh values into kW. At least one of chargepoint, connector or network must be specified.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/meter_values/energy

energy consumption from energy active import meter values (in kWh) for a network, charger or connector. Similar data can be fetched from GET /v2/meter_values/, but this endpoint resolves meter value overlaps based on their creation time and converts Wh and kWh values into kW. The timeseries data returned is irregular when data gaps are encountered. At least one of vehicle, connector, chargepoint or network must be specified.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
string <uuid> (uuid)
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/meter_values/frequency

Timeseries of frequency meter values (OCPP specify frequency as unitless but the expected value is Hz) for a connector. connector must be specified.

query Parameters
connector
required
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by Connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/meter_values/soc

Timeseries of state of charge meter values (in %) for a connector. Either connector or vehicle must be specified.

query Parameters
connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

vehicle
string <uuid> (uuid)
Example: vehicle=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by vehicle ID (this UUID was returned by POST /v2/vehicles/)

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/meter_values/temperature

Timeseries of temperature meter values (in K) for a connector. connector must be specified.

query Parameters
connector
required
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by Connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/meter_values/voltage

Timeseries of voltage meter values (in V) for a connector. connector must be specified.

query Parameters
connector
required
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by Connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/dr_events/

List Demand Response (DR) Events for a network (in kW) in timeseries format. Similar data can be fetched from GET /v2/dr_events/, but this endpoint returns a continuous time series stream using 0.0 to fill gaps for times where no dr event data is available and resolving demand response overlaps based on the demand response events' updated and created times.

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

type
required
string
Enum: "Load Amount" "V2G"

Demand Response type

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

intervalLength
integer
Example: intervalLength=15

Interval length pace for timeseries data items (in minutes, greater or equal to 1).

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 5
}

/v2/profiles/baseloads/

List baseload profiles (in kW). The same data can be listed with GET /v2/baseloads/ but this endpoint returns time series data in a more compact format.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/solar_meterings/

List solar meterings profiles (in kW). The same data can be listed with GET /v2/solar_meterings/ but this endpoint returns time series data in a more compact format.

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/connectivity/

List connectivity profiles (time series format, in fraction 0-1).

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/uptime/

List uptime profiles (time series format, in fraction 0-1).

query Parameters
network
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

resolution
string
Enum: "1m" "15m" "5h" "2d" "4w"

Time resolution of profile data

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

/v2/profiles/ocpp_status/

List ocpp status profiles (in time series format).

query Parameters
chargepoint
string <uuid>
Example: chargepoint=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by chargepoint uuid.

connector
string <uuid> (uuid)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 4
}

Reports

The reports functionality is recommended for scenarios requiring the export of larger data sets in CSV format. This format is compatible with common visualization software such as Excel. Please be aware that the maximum number of items that can be exported is capped at 100,000.

The report filters allow the data to reflect the same output as its corresponding API endpoint and its parameters.

To get more data, it is suggested to fix the start and end filter parameters, and shift the dataset by using limitand offset. Fixing the time period will avoid fetching new records, which would change the offset value.

/v2/reports

Return all reports.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

model
string (model)
Enum: "charging_sessions" "ocpp_messages" "alerts" "cdrs"

Model name

userId
string <uuid> (uuid)
Example: userId=83ad826c-5eb9-4113-b5bc-8c4408dcd2d2

User UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports

Create a report.

Request Body schema: application/json
required
charging_session_filters (object) or ocpp_message_filters (object) or alerts_filters (object) or cdrs_report_filters (object) (filters)

Filters applied to the report. The objects will follow the same format as the one of the corresponding endpoint.

model
required
string (model)
Enum: "charging_sessions" "ocpp_messages" "alerts" "cdrs"

Endpoint data that is being downloaded

name
required
string

Name of the report

fields
Array of arrays

The only fields/columns that should be included in the report and report template. Order of columns is kept and reflected later the CSV file.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "model": "charging_sessions",
  • "name": "string",
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/<report_uuid>

Return a report.

path Parameters
report_uuid
required
string <uuid> (uuid)
Example: 94b9ea2a-9ab0-4375-8ecd-e018f6cf4463

Report UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/<report_uuid>/download

Download a report.

path Parameters
report_uuid
required
string <uuid> (uuid)
Example: 94b9ea2a-9ab0-4375-8ecd-e018f6cf4463

Report UUID

Responses

/v2/reports/scopes

Return all available report types and their available filters and fields(columns).

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/templates

Return all available report templates.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

model
string (model)
Enum: "charging_sessions" "ocpp_messages" "alerts" "cdrs"

Model name

userId
string <uuid> (uuid)
Example: userId=83ad826c-5eb9-4113-b5bc-8c4408dcd2d2

User UUID

favorite
boolean (favorite)
Example: favorite=true
sort
string (sort)
Enum: "name" "favorite"
Example: sort=favorite:asc

sort report templates by name or favorite field with the format of "name:asc, favorite:desc".

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/templates

Create a report template.

Request Body schema: application/json
name
required
string

Name of the report template

model
required
string (model)
Enum: "charging_sessions" "ocpp_messages" "alerts" "cdrs"

Endpoint data that is being downloaded

required
charging_session_filters (object) or ocpp_message_filters (object) or alerts_filters (object) or cdrs_report_filters (object) (filters)

Filters applied to the report. The objects will follow the same format as the one of the corresponding endpoint.

fields
Array of arrays

The only fields/columns that should be included in the report and report template. Order of columns is kept and reflected later the CSV file.

favorite
boolean
Default: false
category
string
description
string
range
string

Report template range in the format of 'last XX days'.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "model": "charging_sessions",
  • "filters": {
    },
  • "fields": [
    ],
  • "favorite": false,
  • "category": "string",
  • "description": "string",
  • "range": "Last 7 days"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/templates/<report_template_uuid>

Return a report template by id.

path Parameters
report_template_uuid
required
string <uuid> (uuid)
Example: 94b9ea2a-9ab0-4375-8ecd-e018f6cf4463

Report template UUID

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/templates/<report_template_uuid>

Update a report template by id.

path Parameters
report_template_uuid
required
string <uuid> (uuid)
Example: 94b9ea2a-9ab0-4375-8ecd-e018f6cf4463

Report template UUID

Request Body schema: application/json
name
string

Name of the report template

charging_session_filters (object) or ocpp_message_filters (object) or alerts_filters (object) or cdrs_report_filters (object) (filters)

Filters applied to the report. The objects will follow the same format as the one of the corresponding endpoint.

fields
Array of arrays
favorite
boolean
category
string
description
string
range
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "filters": {
    },
  • "fields": [
    ],
  • "favorite": false,
  • "category": "string",
  • "description": "string",
  • "range": "Last 7 days"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/reports/templates/categories

Return all available report templates categories.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 3
}

Solar Meterings

/v2/solar_meterings/

Send meter values from solar energy meter. Required for solar optimization functionality.

Request Body schema: application/json
networkId
required
string <uuid> (uuid)
Array of objects

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "solarMeterValues": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 2
}

/v2/solar_meterings/

List solar meter values for a network

query Parameters
network
required
string <uuid> (uuid)
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 5
}

Sub Networks

/v2/sub_networks/

Create a sub network. The parentSubNetworkId determines where the sub network is created in the topology, if null, the sub network will be attached directly to the network.

Request Body schema: application/json
name
required
string

Helps to identify your sub_network on the UI.

networkId
required
string <uuid>

UUID of the network.

parentSubNetworkId
string <uuid>

UUID of the parent sub_network, if null, the sub_network is directly attached to the network.

maxCapacity
required
number <float>

Maximum allowed power on this resource in kW (Kilowatt).

Responses

Request samples

Content type
application/json
{
  • "name": "Transformer 10",
  • "networkId": "c98b9db1-2194-4cf0-bfe1-490495fae58b",
  • "parentSubNetworkId": "c98b9db1-2194-4cf0-bfe1-490495fae58b",
  • "maxCapacity": 22
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/sub_networks/

List sub networks.

query Parameters
network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by network uuid.

network
string <uuid>
Example: network=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by sub_network uuid.

limit
integer
Default: 100
Example: limit=50

Pagination limit for query

offset
integer
Default: 0
Example: offset=3

Pagination offset for query

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/sub_networks/{id}

Get sub network details.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/sub_networks/{id}

Update a network.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
name
string

Helps to identify your sub_network on the UI.

parentSubNetworkId
string <uuid>

UUID of the parent sub_network, if null, the sub_network is directly attached to the network.

Responses

Request samples

Content type
application/json
{
  • "name": "Transformer 10",
  • "parentSubNetworkId": "c98b9db1-2194-4cf0-bfe1-490495fae58b"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/sub_networks/{id}

Delete a network, any children charger or sub network will be moved to the sub_network's parent sub network (or the network if the sub_network is directly attached to the network).

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

Users

/v2/users

query Parameters
search
string

This is a string search to find users based on their name or email address.

roles
Array of UUID

User roles. Supports multiple values e.g.roles=UUID&roles=UUID.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 3
}

/v2/users

Request Body schema: application/json
customer
string <uuid> (uuid)
name
string

Requiered when creating normal users.

password
required
string
firstName
string
lastName
string
email
string <email>

Requiered when creating oauth users.

phone
string^\+[1-9]\d{1,14}$
type
string
Enum: "admin" "user" "service" "read_only"
language
string
Enum: "en" "es"
oauth
boolean
Default: false

Set to true automatically and only on creation, if user supports OAuth based authentication.

favorite
boolean
Default: false

Used for setting favorite users when using the multi-organization option

isMetric
boolean
Default: true

Units that the user will see on the UI.

Responses

Request samples

Content type
application/json
{
  • "customer": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "name": "SteveSmith",
  • "password": "test",
  • "firstName": "Steve",
  • "lastName": "Smith",
  • "email": "steve@example.com",
  • "phone": "+14155552671",
  • "type": "admin",
  • "language": "es",
  • "oauth": false,
  • "favorite": false,
  • "isMetric": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/{user_uuid}

Request Body schema: application/json
name
string
password
string
firstName
string
lastName
string
email
string <email>
profileImageUrl
string <url>
phone
string^\+[1-9]\d{1,14}$
language
string
Enum: "en" "es"
favorite
boolean
Default: false

Used for setting favorite users when using the multi-organization option

isMetric
boolean
Default: true

Units that the user will see on the UI.

Responses

Request samples

Content type
application/json
{
  • "name": "SteveSmith",
  • "password": "test",
  • "firstName": "Steve",
  • "lastName": "Smith",
  • "email": "steve@example.com",
  • "profileImageUrl": "None",
  • "phone": "+14155552671",
  • "language": "es",
  • "favorite": false,
  • "isMetric": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/{user_uuid}

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/me

query Parameters
email
any

Used in multi-organization. When querying by email all the users under that email are returned.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/me

Request Body schema: application/json
name
string
password
string
firstName
string
lastName
string
email
string <email>
profileImageUrl
string <url>
phone
string^\+[1-9]\d{1,14}$
language
string
Enum: "en" "es"
favorite
boolean
Default: false

Used for setting favorite users when using the multi-organization option

isMetric
boolean
Default: true

Units that the user will see on the UI.

Responses

Request samples

Content type
application/json
{
  • "name": "SteveSmith",
  • "password": "test",
  • "firstName": "Steve",
  • "lastName": "Smith",
  • "email": "steve@example.com",
  • "profileImageUrl": "None",
  • "phone": "+14155552671",
  • "language": "es",
  • "favorite": false,
  • "isMetric": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/login

Request Body schema: application/json
name
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "SteveSmith",
  • "password": "test"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/users/{user_uuid}/switch

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

The UUID is the user you want to set to active as main.

Responses

Vehicles

/v2/vehicles/

Adds a vehicle.

Request Body schema: application/json
name
required
string

Display name of vehicle.

comments
string

free string input to store custom vehicle data

VIN
string or null
customerVehicleId
string or null

Vehicle ID used by customer or fleet operator

departureTime
string or null <date-time>

When the vehicle needs to stop charging and leave.

batteryCapacity
number <float>

How much energy can be stored in the vehicle's battery, in kWh (Kilowatt-hour).

location
string or null

Location of the vehicle

maxChargingPower
number <float>

In kW (Kilowatt).

stateOfCharge
number <float>

How much energy is now in the battery, in %.

targetStateOfCharge
number <float>
Default: 100

Up to what level we need to charge, in %.

group
string or null <string>

Group used to match routes with vehicles

insideDepot
string or null <uuid>

Indicates if a vehicle is currently within a network geofence radius.

make
string or null <string>

The vehicle make refers to the manufacturer or brand of a vehicle, such as Toyota, Ford, Honda, etc.

model
string or null <string>

The vehicle model represents a specific version or variant of a vehicle make. For example, the Toyota Camry, Ford Mustang, Honda Civic, etc.

year
int or null <int>

The vehicle year indicates the year in which a particular vehicle model was manufactured. It helps in identifying the specific version of a model, as vehicle designs can change over time.

licensePlate
string or null <string>

A license plate is a unique alphanumeric identifier assigned to a vehicle by a governmental authority. It serves as an official registration mark and helps in identifying and tracking vehicles.

Responses

Request samples

Content type
application/json
{
  • "name": "Vehicle 3",
  • "comments": "Battery life seems low. Call mechanic.",
  • "VIN": "5GZCZ43D13S812715",
  • "customerVehicleId": "Vehicle 3",
  • "departureTime": "2020-10-11T08:19:00+00:00",
  • "batteryCapacity": 75.5,
  • "location": "Brooklyn, NYC",
  • "maxChargingPower": 11.5,
  • "stateOfCharge": 80.5,
  • "targetStateOfCharge": 90,
  • "group": "MorningDeparturesGroup",
  • "insideDepot": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "make": "Chevy",
  • "model": "Volt",
  • "year": 2022,
  • "licensePlate": "ABC123"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/

List Vehicles

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

group
string

Filter vehicles by group.

updated
string <date-time>
Example: updated=2020-10-11T08:19:00+00:00

Returns objects updated after the specified timestamp.

search
string

String-based search based on a combination from vehicle name, licensePlate, VIN, idTagNames, group, make, model, year, or vehicle ID (UUID).

sort
string
Enum: "batteryCapacity:desc" "batteryCapacity:asc" "group:desc" "group:asc" "integrationId:desc" "integrationId:asc" "licensePlate:desc" "licensePlate:asc" "make:desc" "make:asc" "maxChargingPower:desc" "maxChargingPower:asc" "model:desc" "model:asc" "name:desc" "name:asc" "targetSOC:desc" "targetSOC:asc" "VIN:desc" "VIN:asc" "year:desc" "year:asc"

Sort by specific values.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/

Bulk update vehicles.

Request Body schema: application/json
ids
Array of strings <uuid> (uuid) [ items <uuid > ]
object
object

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "filters": {
    },
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 1
}

/v2/vehicles/{id}

A vehicle.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/

Update a vehicle. Updates to the departureTime, stateOfCharge and targetStateOfCharge fields can trigger reoptimization and send out new limits to your network.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Request Body schema: application/json
name
required
string

Display name of vehicle.

comments
string

free string input to store custom vehicle data

VIN
string or null
customerVehicleId
string or null

Vehicle ID used by customer or fleet operator

departureTime
string or null <date-time>

When the vehicle needs to stop charging and leave.

batteryCapacity
number <float>

How much energy can be stored in the vehicle's battery, in kWh (Kilowatt-hour).

location
string or null

Location of the vehicle

maxChargingPower
number <float>

In kW (Kilowatt).

stateOfCharge
number <float>

How much energy is now in the battery, in %.

targetStateOfCharge
number <float>
Default: 100

Up to what level we need to charge, in %.

group
string or null <string>

Group used to match routes with vehicles

insideDepot
string or null <uuid>

Indicates if a vehicle is currently within a network geofence radius.

make
string or null <string>

The vehicle make refers to the manufacturer or brand of a vehicle, such as Toyota, Ford, Honda, etc.

model
string or null <string>

The vehicle model represents a specific version or variant of a vehicle make. For example, the Toyota Camry, Ford Mustang, Honda Civic, etc.

year
int or null <int>

The vehicle year indicates the year in which a particular vehicle model was manufactured. It helps in identifying the specific version of a model, as vehicle designs can change over time.

licensePlate
string or null <string>

A license plate is a unique alphanumeric identifier assigned to a vehicle by a governmental authority. It serves as an official registration mark and helps in identifying and tracking vehicles.

Responses

Request samples

Content type
application/json
{
  • "name": "Vehicle 3",
  • "comments": "Battery life seems low. Call mechanic.",
  • "VIN": "5GZCZ43D13S812715",
  • "customerVehicleId": "Vehicle 3",
  • "departureTime": "2020-10-11T08:19:00+00:00",
  • "batteryCapacity": 75.5,
  • "location": "Brooklyn, NYC",
  • "maxChargingPower": 11.5,
  • "stateOfCharge": 80.5,
  • "targetStateOfCharge": 90,
  • "group": "MorningDeparturesGroup",
  • "insideDepot": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "make": "Chevy",
  • "model": "Volt",
  • "year": 2022,
  • "licensePlate": "ABC123"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/{id}

Delete a vehicle.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/{id}/telematics

Adds a vehicle telematics data. one of longitude and latitude, chargingState or stateOfCharge is required

Request Body schema: application/json
timestamp
required
string <date-time>

ISO 8601, timestamp of the telematics data.

stateOfCharge
number or null <float>

How much energy is now in the battery, in %.

latitude
number or null <float>

Vehicle location Latitude, + is North, - is South, required if longitude is set.

longitude
number or null <float>

Vehicle location Longitude, + is East, - is West, required if latitude is set.

plugConnected
boolean or null
dataConnected
boolean or null
batteryCapacity
number <float>

Vehicle's battery capacity in kWh

batteryPower
number <float>

Vehicle's battery power in kW

rangeRemaining
number <float>

remaining vehicle range in km

chargingState
any
Enum: "Charging" "ChargingAC" "ChargingDC" "NotCharging"

Charging state of the vehicle

chargingEnergy
number <float>

Charging energy in kWh

drivingEnergy
number <float>

Driving energy in kWh

regenEnergy
number <float>

Regen energy in kWh

otherEnergy
number <float>

Other energy in kWh

cabinTemperature
number <float>

Cabin temperature in Celsius

batteryTemperature
number <float>

Battery temperature in Celsius

chargingPower
number <float>

Charging power in kW

odometer
number <float>

Vehicle odometer in km

ignition
boolean or null

Vehicle ignition state

source
any
Enum: "thirdPartyTelematics" "chargePoint"

vehicle telematic source

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2020-10-11T08:19:00",
  • "stateOfCharge": 80.5,
  • "latitude": 32.2431,
  • "longitude": 115.793,
  • "plugConnected": true,
  • "dataConnected": true,
  • "batteryCapacity": 130,
  • "batteryPower": 50,
  • "rangeRemaining": 150.5,
  • "chargingState": "Charging",
  • "chargingEnergy": 100.5,
  • "drivingEnergy": 100.5,
  • "regenEnergy": 50.5,
  • "otherEnergy": 10.5,
  • "cabinTemperature": 22,
  • "batteryTemperature": 40,
  • "chargingPower": 40,
  • "odometer": 1000,
  • "ignition": true,
  • "source": "thirdPartyTelematics"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/{id}/telematics

A vehicle telematics data.

path Parameters
id
required
string <uuid> (uuid)
Example: 33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Resource ID.

query Parameters
start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/groups

Return a list of unique vehicle groups for the current customer

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "total": 1,
  • "data": [
    ]
}

/v2/vehicles/telematics/live

Get an aggregate of the most recent telematics data for all customer vehicles

query Parameters
latitude
any
Example: latitude=32.2431

Central point Latitude, + is North, - is South, required if longitude and radius are set.

longitude
any
Example: longitude=115.793

Central point Longitude, + is East, - is West, required if latitude and radius are set.

radius
any
Example: radius=450

Radius of the circle-shaped geofence around the central point. In meters.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/trips

Get an aggregate of the most recent data for all customer vehicle trips.

query Parameters
vehicleId
any
Example: vehicleId=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Vehicle Id. Supports multiple values e.g. vehicleId=uuid1&vehicleId=uuid2.

vehicleGroup
any
Example: vehicleGroup=vehicleGroupOne

Vehicle group name. Supports multiple values e.g. vehicleGroup=group1&vehicleGroup=group2.

start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

sort
string
Enum: "active:desc" "active:asc" "averageSpeed:desc" "averageSpeed:asc" "distance:desc" "distance:asc" "drivingDuration:desc" "drivingDuration:asc" "endStateOfCharge:desc" "endStateOfCharge:asc" "endTime:desc" "endTime:asc" "maxSpeed:desc" "maxSpeed:asc" "netEnergyUsed:desc" "netEnergyUsed:asc" "startStateOfCharge:desc" "startStateOfCharge:asc" "startTime:desc" "startTime:asc" "vehicleId:desc" "vehicleId:asc"

Sort by specific values.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/{id}/activity

A vehicle telematics data.

query Parameters
start
string <date-time> (start_datetime)
Default: "Current time"
Example: start=2020-10-11T08:19:00

Date-time interval limit: 7 days
Time interval start.

end
string <date-time> (end_datetime)
Default: "Current time + 24 hours"
Example: end=2020-10-11T09:19:00

Date-time interval limit: 7 days
Time interval end.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

offset
integer [ 0 .. 2147483647 ]

The number of items to skip in the result list.

sort
string
Enum: "activity:desc" "activity:asc" "distance:desc" "distance:asc" "duration:desc" "duration:asc" "energy:desc" "energy:asc" "endTime:desc" "endTime:asc" "startTime:desc" "startTime:asc"

Sort by specific values.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "total": 1
}

/v2/vehicles/csv

This is an endpoint used to create vehicles in bulk through a CSV file. The file must be a maximum of 600 kilobytes and have the following format Required—Vehicle Name,License Plate,VIN,IdTag(s),Vehicle Group,Target SoC,Make,Model,Year,Battery Capacity,Max Power,Departure Time.

Request Body schema: text/csv
vehicle_in
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    },
  • "total": 50
}

Views

/v2/views/charger_locations

Returns list of public chargers with their status, location, price, and connector information.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}