Teslavolts API (1.2.7)

Download TeslavoltsAPI specification:Download

Teslavolts offers Intelligent Charging AI-based optimization services that are accessible through an API for Charging Point Operators (CPOs), EV Fleet managers, and services developers. This innovative technology provides a comprehensive toolset designed to create optimized charging profiles for Electric Vehicle (EV) charging stations, enhancing efficiency and sustainability in the Intelligent Charging ecosystem.'

Introduction

Working with Teslavolts's API

Teslavolts API serves as the engine behind its Intelligent Charging software, fueling a cutting-edge layer of optimization for charging stations, networks, and electric fleets worldwide. This technology enables a significant expansion of electric vehicles on our roads, contributing to a global shift toward sustainable transportation. For instance, Teslavolts offers a REST API designed for load management, electric fleet charging, and the integration of public charging networks. This flexible API allows Teslavolts to seamlessly connect with any existing software system, utilizing standard HTTP methods such as GET, POST, PATCH, and DELETE. With these capabilities, Teslavolts stands at the forefront of advancing intelligent, efficient, and accessible charging solutions.

Authenticate with HTTP

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

A typical API request

Let's do one simple API request with Teslavolts. 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.teslavolts.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. Teslavolts 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 Teslavolts also without using webhooks. When the webhook event occurs, Teslavolts makes a POST request to the URL you have configured for your webhook. Teslavolts’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 Teslavolts 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": "Teslavolts Delivery Service"
  "X-Webhook-Signature": "676851448a4cda2f3c285ed2274867654c801e8a6394c351b77c713ab4ad20e4"
} """
# to validate that the payload was sent by Teslavolts 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

Teslavolts 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 Teslavolts into your app is simple, and you can follow these steps:

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

1. 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.Teslavolts.io/v2/charge_points/"
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

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

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

2. Post a network

Before using Teslavolts, 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.Teslavolts.io/v2/networks/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

3. 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.Teslavolts.io/v2/charge_points/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

4. 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.Teslavolts.io/v2/connectors/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

5. 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.Teslavolts.io/v2/charging_sessions/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

6. 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.Teslavolts.io/v2/optimizations/?network=3b87971f-e7ec-5a73-be26-cee0aafe75fe"
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Teslavolts 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.

7. Post meter values

In this step, we send a meter value from the connector to Teslavolts. Teslavolts 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.Teslavolts.io/v2/meter_values/"
response = requests.post(url, headers=headers, json=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

8. 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 Teslavolts sent after the POST
url = "https://api.Teslavolts.io/v2/charging_sessions/066dad20-d289-560b-9b67-fd9bb9f52057"
response = requests.delete(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

9. 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.Teslavolts.io/v2/vehicles/"
response = requests.post(url, headers=headers, data=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

10. 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.Teslavolts.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))

Teslavolts 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
}

11. 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.Teslavolts.io/v2/charging_sessions/"
response = requests.patch(url, headers=headers, data=payload)
print(json.dumps(response.json(), indent=4))

Teslavolts 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
}

12. 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.Teslavolts.io/v2/networks/3b87971f-e7ec-5a73-be26-cee0aafe75fe"

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

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

Teslavolts 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
}

Users

/v2/users

Responses

Response samples

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

/v2/users

Note: In order to create users for a customer other than the one logged in, request needs to specify the customer field on the request body. This is only available for admin role in Teslavolts's master customer, and its use is restricted to internal services and support.

Note: For other customers (different from Teslavolts's master customer), it will only require to be logged in with an admin account to POST users. Naturally, these new users will belong only to your own customer.

Request Body schema: application/json
customer
string <uuid> (uuid)
name
required
string
password
required
string
firstName
required
string
lastName
required
string
email
string <email>
phone
string^\+[1-9]\d{1,14}$
type
string
Enum: "admin" "user" "service" "read_only"
language
string
Enum: "en" "es"

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"
}

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

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"

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"
}

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
}

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": {
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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": {
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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
                  },
                  "Teslavolts-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": "Teslavolts-default-TxProfile",
          "TxDefaultProfile": "Teslavolts-default-TxDefaultProfile"
      },
      "integrations": {},
      "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"
          },
          "longship": {
              "base_url": "https://www.dummy-url.com",
              "tenant_key": {
                  "key": "Ocp-Apim-Subscription-Key",
                  "value": "dummyTenantKey"
              },
              "api_key": {
                  "key": "x-api-key",
                  "value": "dummyAPIKey"
              }
          }
      },
      "deliveryOptions": {
          "TxProfile": "Teslavolts-default-TxProfile",
          "TxDefaultProfile": "Teslavolts-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": "Teslavolts-default-TxProfile",
      "TxDefaultProfile": "Teslavolts-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/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
Enum: "off" "cms" "proxy"
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
Enum: "off" "cms" "proxy"
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
Enum: "off" "cms" "proxy"

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
Enum: "off" "cms" "proxy"

Responses

Request samples

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

Response samples

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

Capacities

/v2/capacities/

Create a maximum capacity time range for a network.

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

Responses

Request samples

Content type
application/json
{
  • "networkId": "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

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

Filter by network.

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

Search lower bound of the query. Defaults to current time in UTC.

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

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>

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

end
string <date-time>

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
}

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> <= 255 characters
networkId
required
string <uuid> (uuid)
allowAllIdTags
boolean or null

If 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 (ocpp_status)
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted"

Value from OCPP StatusNotification message (if available).

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

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.

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",
  • "source": "CMS",
  • "vendor": "Vendor Name",
  • "powerSplit": true
}

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

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

Filter by charger name

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)

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: custom_name, name, active, max_capacity, current_charging_load, last_session_started. 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)

vendor
string

Filter by charger vendor

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.

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> <= 255 characters
networkId
string <uuid> (uuid)
allowAllIdTags
boolean or null

If 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 (ocpp_status)
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted"

Value from OCPP StatusNotification message (if available).

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

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.

maxCapacity
number <float> >= 0

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

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",
  • "source": "CMS",
  • "vendor": "Vendor Name",
  • "powerSplit": true,
  • "maxCapacity": 22,
  • "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 when a vehicle is plugged in.

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)
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
integer (priority) [ 0 .. 5 ]

Priority of the charging session [0-5]. 0 means opt-out, i.e. the charging session will receive maximum power before sessions with non-zero priority are optimized. For non-zero priorities 1 is highest and 5 is lowest.”

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": 1,
  • "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)
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)
Example: connector=33fe5b42-f717-43f6-ba0a-eab4cae81bfa

Filter by connector IDs.

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

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

idTag
string
Example: idTag=FHH92JFNMSK93
transaction_id
integer
Example: transaction_id=92813645

Filter charging sessions by transaction ID

active
boolean
Default: true

Filter charging sessions by active status

priority
integer
Example: priority=1

Filter charging sessions by priority

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

Time interval start. Applies to sessionStart

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

Time interval end. Applies to sessionStart

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.

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 charging session or Close charging session. One of priority, meterStop, ocppTransactionStop, paymentInfo, energyToCharge or 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
integer (priority) [ 0 .. 5 ]

Priority of the charging session [0-5]. 0 means opt-out, i.e. the charging session will receive maximum power before sessions with non-zero priority are optimized. For non-zero priorities 1 is highest and 5 is lowest.”

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.

Responses

Request samples

Content type
application/json
{
  • "energyToCharge": 80,
  • "meterStop": 12.2,
  • "ocppTransactionStop": "2021-12-17T22:30:27.629927+00:00",
  • "paymentInfo": "string",
  • "priority": 1,
  • "remoteStopOnCompletion": true
}

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.

Responses

Response samples

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

Data exports

/v2/data_exports

Return all data exports for the user's customer.

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: "meter_values" "cdrs" "charging_sessions" "ocpp_messages"
Example: model=meter_values

Model retrieved by the data export

frequency
string (frequency)
Enum: "daily" "weekly" "monthly" "quarterly" "yearly" null
Example: frequency=daily

Frequency at which the data export runs

Responses

Response samples

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

/v2/data_exports

Create a data export job. For meter_values, cdrs, charging_sessions, the networkId is required. For ocpp_messages, networkId MUST be null, as it applies for all customer's chargers.

Request Body schema: application/json
networkId
string <uuid> (uuid)
frequency
string (frequency)
Enum: "daily" "weekly" "monthly" "quarterly" "yearly" null

Frequency at which the data export runs

model
string (model)
Enum: "meter_values" "cdrs" "charging_sessions" "ocpp_messages"

Model retrieved by the data export

scheduleDate
string <date-time> (datetime)

ISO 8601.

Responses

Request samples

Content type
application/json
{
  • "networkId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa",
  • "frequency": "daily",
  • "model": "meter_values",
  • "scheduleDate": "2020-10-11T08:19:00"
}

Response samples

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

/v2/data_exports/{data_export_uuid}

Return a data export job.

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/data_exports/{data_export_uuid}

Update a data export job

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

Resource ID.

Request Body schema: application/json
frequency
string (frequency)
Enum: "daily" "weekly" "monthly" "quarterly" "yearly" null

Frequency at which the data export runs

scheduleDate
string <date-time> (datetime)

ISO 8601.

Responses

Request samples

Content type
application/json
{
  • "frequency": "daily",
  • "scheduleDate": "2020-10-11T08:19:00"
}

Response samples

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

/v2/data_exports/{data_export_uuid}

Delete a data export job.

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

Resource ID.

Responses

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.

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

Responses

Request samples

Content type
application/json
{
  • "chargepointId": "33fe5b42-f717-43f6-ba0a-eab4cae81bfa"
}

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}/upload

Upload diagnostics to system.

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

Diagnostics UUID

Request Body schema: application/octet-stream
string <binary>

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

Meter values

/v2/meter_values/

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

  • Power.Active.Import with units W or kW
  • Energy.Active.Import.Register with units Wh or kWh

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.

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.

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,
  • "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 vehicle or connector 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
required
string <date-time> (datetime)
Example: start=2020-10-11T08:19:00

Time interval start.

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

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
}

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.

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 (schemas-model)
Value: "charging_sessions"

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) (filters)

Filters applied to the report. The objects will follow the same format as the one of the corresponding endpoint.

model
required
string (schemas-model)
Value: "charging_sessions"

Endpoint data that is being downloaded

name
required
string

Name of the report

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "model": "charging_sessions",
  • "name": "string"
}

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

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 (ocpp_status)
Enum: "Available" "Preparing" "Charging" "SuspendedEVSE" "SuspendedEV" "Finishing" "Reserved" "Faulted"

Value from OCPP StatusNotification message (if available).