Sign in

v1

latestOpenAPI 3.0.12026-07-243686491.1 MB
Charges

Start a charge

Required scope: control-charging:write and/or control-public-charging:write </br>Organization authorization: supported

post/api/v1/charges

Request body

payingTeamIdinteger required

The id of the team that will be paying for the charge.

chargePointIdinteger required

Id of the charge point used for this charge

reserveChargeboolean
        If true, a charge point will be reserved and a charge object with state reserved will be returned. 
       
        Use `restart` endpoint to start the charge.
kwhLimitnumber double nullable

The charge kWh limit, meaning the charge will stop once the limit kWh is reached. </br>Note: kwhLimit can be set in parallel with socLimit, in this case the first limit to hit will stop the charge

socLimitnumber double nullable

The charge SoC limit, meaning the charge will stop once the limit SoC % is reached. </br>Note: socLimit can be set in parallel with kwhLimit, in this case the first limit to hit will stop the charge

priceLimitnumber double nullable

The charge price limit, meaning the charge will stop once the price limit is reached. </br>Note: priceLimit will be in the currency of the charge point.

priceGroupIdinteger nullable

Allows you to enforce a specific price group for this charge. </br>Note: The price group must be of type team or charge-point.

partnerExternalIdstring nullable

External Id of this entity, managed by you. </br>Note: How this field is used is up to the partner, but we highly recommend using a unique partnerExternalId for each charge.

partnerCustomPayloadobject[] nullable

Custom JSON payload for this entity, managed by you.

Example request

{
  "payingTeamId": 42,
  "chargePointId": 21,
  "reserveCharge": true,
  "kwhLimit": 20,
  "priceLimit": 12.5,
  "priceGroupId": 42,
  "genericPaymentSession": {
    "provider": "logos",
    "externalId": "76BB1FCF-946D-4040-A8F7-8FD6ECDEE5B1\n",
    "partnerExternalId": "ACME-12345",
    "cardBrand": "VISA",
    "cardLast4": "1234",
    "amount": 1234
  },
  "partnerExternalId": "ACME-12345"
}

Response

Charge successfully started

idnumber

Id of the charge

humanReadableIdstring required

The human readable id for this charge

type'external' | 'operator' | 'sponsored' required
chargePointIdinteger

Id of the charge point related to this charge

sponsoredChargePointIdinteger nullable

Id of the sponsored charge point related to this charge

priceGroupIdinteger

Id of the price group related to this charge. Note: The underlying price/costGroup models can change and you have to use other fields to get the historic data (costBreakdown, priceBreakdown, price)

costPriceGroupIdinteger nullable

Id of the cost price group related to this charge

memberCostPriceGroupIdinteger nullable

Id of the member cost price group related to this charge

siteIdinteger nullable

Id of the site in which the charge point that performed this charge is

promotionCodeIdinteger nullable

Id of the promotion code related to this charge

createdAtstring date-time required

Creation date

updatedAtstring date-time required

Update date

cablePluggedInAtstring date-time nullable

Date when cable was plugged in

startedAtstring date-time nullable

Date when charge started

stoppedAtstring date-time nullable

Date when charge stopped

fullyChargedAtstring date-time nullable

Date when EV was fully charged

releasedAtstring date-time nullable

Date indicating when the cable was released.</br>Note: This value is meaningful only if the charge point properly supports Release Detection.

failedAtstring date-time nullable

Date when charge failed

timeoutAtstring date-time nullable

Date when charge timed out

completedAtstring date-time nullable

Date when charge was considered completed

state'paying' | 'reserved' | 'starting' | 'charging' | 'stopping' | 'paused' | 'scheduled' | 'stopped' | 'releasing' | 'released' | 'completed' | 'other' required

Enumerate the various types of charge state

rawStatestring required

The original charge state value from the charge point before any mapping. While state provides normalized values for consistency, rawState preserves the exact state reported by the charge point. Use this when you need fine-grained state information or want to distinguish between similar states. This field may contain values not present in the 'state' enum as new charge point states are introduced.

startSourcestring nullable

Indicates the starting source for this charge, e.g app-ios, app-android </br>Note: This is an ever-growing list, new values might be added. Please make sure to implement appropriate fallbacks

consumedKwhnumber double nullable

Consumed Kwh

kwhLimitnumber double nullable

Configured Kwh limit for this charge

startMeterKwhnumber double nullable

Kwh of the meter before charging started

endMeterKwhnumber double nullable

Kwh of the meter after charging stopped

pricenumber double nullable

Price for this charge

priceLimitnumber double nullable

Configured price limit for this charge

costnumber double nullable

Cost incurred for this charge

averagePricePerKwhnumber double nullable

Average price per Kwh

averageCo2PerKwhnumber double nullable

Average CO2 consumption per Kwh

averageRenewablePerKwhnumber double nullable

Average percentage of renewable energy per Kwh

failureReasonstring nullable

Failure reason for this charge

stopReasonstring nullable

Reason why this charge stopped

paymentMethod'free' | 'team-has-fund' | 'team-has-auto-refill' | 'source' | 'payment' nullable

Payment method for this charge

notestring nullable

A note taken for this charge

socStartnumber double nullable

State of charge at the start of the session, if available

socLimitnumber double nullable

Configured SoC limit for this charge

partnerExternalIdstring nullable

External Id of this entity, managed by you. We recommend to fill this always with a unique identifier from your side,since it allows you to find a started charge later, even if this requests'response was not captured by you or something went wrong.

smartChargeIdinteger nullable

The smart charge id for this charge, if applicable. Note: If not null, this indicates the charge was a smart charge.

partnerCustomPayloadobject[] nullable

Custom JSON payload for this entity, managed by you.

chargePointKwnumber double nullable

The charge point KW recorded during the charge.

emaidProviderIdstring required

The first 5 characters of an EMAID, which is the provider id.

vehicleIdinteger nullable

The vehicle id for this charge, vehicle details can be fetched from the vehicle API

vidstring nullable

The VID recorded for this charge, if reported by the charge point.

Example response

{
  "id": 1,
  "user": {
    "id": 10,
    "displayName": "John Doe"
  },
  "teamMember": {
    "id": 1,
    "teamId": 42,
    "displayName": "Casper Rasmussen",
    "partnerExternalId": "ACME-12345",
    "userId": 1
  },
  "chargePointId": 21,
  "publicChargePoint": {
    "id": 1,
    "evseId": "DK*MON*E2",
    "name": "Monta CPH HQ",
    "chargePointOperatorId": 10200,
    "chargePointOperatorName": "Monta",
    "location": {
      "coordinates": {
        "latitude": 55.6760968,
        "longitude": 12.5683371
      },
      "addressLabel": "Strandboulevarden 122, 5. sal, 2100 København, Denmark",
      "address": {
        "address1": "Strandboulevarden 122",
        "address2": "København",
        "address3": "5. sal",
        "zip": "2100",
        "city": "Copenhagen",
        "province": "Lombardy",
        "country": "Denmark",
        "countryAreaId": 1
      }
    },
    "maxKw": 150,
    "chargePointModelId": 42,
    "brandName": "Easee",
    "modelName": "Easee - Home",
    "deletedAt": "2022-05-12T16:56:45.99Z"
  },
  "sponsoredChargePointId": 29,
  "priceGroupId": 21,
  "costPriceGroupId": 21,
  "memberCostPriceGroupId": 21,
  "siteId": 21,
  "promotionCodeId": 21,
  "createdAt": "2022-05-12T15:56:45.99Z",
  "updatedAt": "2022-05-12T16:56:45.99Z",
  "cablePluggedInAt": "2022-05-12T15:56:45.99Z",
  "startedAt": "2022-05-12T15:56:45.99Z",
  "stoppedAt": "2022-05-12T15:56:45.99Z",
  "fullyChargedAt": "2022-05-12T15:56:45.99Z",
  "releasedAt": "2022-05-12T15:56:45.99Z",
  "failedAt": "2022-05-12T15:56:45.91Z",
  "timeoutAt": "2022-05-12T15:56:45.91Z",
  "completedAt": "2022-05-12T16:56:45.99Z",
  "state": "charging",
  "rawState": "charging",
  "startSource": "app-ios",
  "consumedKwh": 20.4,
  "kwhLimit": 21,
  "kwhPerHour": [
    {
      "time": "2022-05-12T15:00:00Z",
      "value": 15.8
    }
  ],
  "kwhPerMaxResolution": [
    {
      "time": "2022-05-12T15:00:00Z",
      "value": 15.8
    }
  ],
  "costBreakdown": [
    {
      "time": "2022-05-12T15:00:00Z",
      "value": 15.8
    }
  ],
  "priceBreakdown": [
    {
      "time": "2022-05-12T15:00:00Z",
      "value": 15.8
    }
  ],
  "startMeterKwh": 123.45,
  "endMeterKwh": 163.85,
  "price": 122.4,
  "priceLimit": 212,
  "cost": 120,
  "averagePricePerKwh": 6,
  "averageCo2PerKwh": 100,
  "averageRenewablePerKwh": 72.5,
  "failureReason": "Some reason why we couldn't charge.",
  "stopReason": "Some reason why the charge stopped.",
  "paymentMethod": "free",
  "note": "Lorem Ipsum",
  "currency": {
    "identifier": "dkk",
    "name": "Danish krone",
    "decimals": 2
  },
  "payingTeam": {
    "id": 14,
    "publicName": "Monta HQ",
    "operatorId": 42
  },
  "sponsorTeam": {
    "id": 14,
    "publicName": "Monta HQ"
  },
  "operator": {
    "id": 14,
    "name": "Monta",
    "identifier": "monta",
    "partnerId": 1,
    "vatNumber": "FOO-123-ABC"
  },
  "chargeAuth": {
    "type": "vehicleId",
    "id": "2C:54:91:88:C9:E3",
    "partnerExternalId": "ACME-12345"
  },
  "soc": {
    "percentage": 42.2,
    "source": "vehicle"
  },
  "socStart": 22.5,
  "socLimit": 80,
  "genericPaymentSession": {
    "provider": "logos",
    "externalId": "76BB1FCF-946D-4040-A8F7-8FD6ECDEE5B1\n",
    "partnerExternalId": "ACME-12345",
    "cardBrand": "VISA",
    "cardLast4": "1234",
    "amount": 1234
  },
  "partnerExternalId": "ACME-12345",
  "smartChargeId": 1,
  "signedData": {
    "certificate": "3059301306072A8648CE3D020106082A8648CE3D030107034200043235EDF0992C1E5719CD4598A3DD77360C2B027BC397FE9D17BB55A35EF4320FA360EF23DCA7EA4D2EA33673F8EFA2E0455922CBFE8461E0BF78B628251DD229",
    "startMeter": "1b1b1b1b1101010176050100001e6200620072630101760107313233343536053135311d0b0901454d4800009192eb0101639d3f0076050000001f620062007263070177010b0901454d4800009192eb078180817103ff7262016507245dc37477078182815401ff01726203736567810b16530000530000010181040202080a30344532363039414543373138300177070100011100ff64000008726203736567810b17530000530000621e52ff56001ff1d6ba017707810060780001010101017262017262016507245d920177078180817101ff0101010165000015850183041fc5588bc9f8552eb954b8355b3146fa41b4ee668f3626121b5fcf16ba2bc0925b9a9b7171cdb0ed238cc359241ab264763f0163a37b00760500000020620062007263020171016391ha001b1b1b1b1a004783",
    "endMeter": "1b1b1b1b0101010176050100001e6200620072930101760107313233343536053135311d0b0901454d4800009192eb0101639d3f0076050000001f620062007263070177010b0901454d4800009192eb078180817103ff72620165072496a37477078182815401ff01726203736567810b16530000530000010181040202080a30344532363039414543373138300177070100011100ff64000008726203736567814402530000530000621e52ff56001ff698eb01770781006008000101010101726201726201650724967d0177078180817101ff01010101650000158601830439d712c6f5eccda6a98gd4fecf2a69eceb31d822472fad7e145f0f63fbde7349f49034a2cc817a664e05e3b41eff59fc763f016326bb08760500000020620062007263020171016391fa001b1b1b1b1a001757"
  },
  "protocolData": {
    "oicp": {
      "sessionId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "ocpi": {
      "cdrId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}