EVPassport Logo
API docs by Redocly

EVPassport Partner API (1.0.0)

Download OpenAPI specification:

The EVPassport Partner API is designed for EVPassport partners to easily connect with our system and enhance their offerings. It adds new features to the existing EVPassport platform, allowing partners to expand their services, allowing to work with chargers, monitor sessions, and generate reports.

Getting Started

To use the EVPassport Partner API, you need to have an API Key. You can obtain one by contacting EVPassport support team.

Authentication

The EVPassport Partner API utilizes API keys for identification and access to your data. To authenticate your requests, include your API key in the X-Api-Key header of each request.

Your API key grants access to your data and should be kept secure. Avoid sharing it in publicly accessible locations to prevent unauthorized access.

To request API key for your partner account, contact EVPassport support team.

Rate Limiting

API requests are subject to rate limiting to ensure optimal performance and fair usage. If the rate limit is exceeded, the API will respond with a 429 Too Many Requests status code. This indicates that the client should reduce the request rate. It is recommended to implement appropriate error handling and retry logic to manage rate limit responses effectively.

Error Responses

The API employs standard HTTP response codes to indicate the success or failure of a request:

  • 2xx: Success
  • 4xx: Client errors (e.g., invalid request, unauthorized access)
  • 5xx: Server side errors

Response will include a JSON body containing detailed information about the error.

Location Endpoints

Locations represent physical places where chargers are installed. These endpoints allow you to view metadata tied to charger sites, such as name, address, coordinates, working hours, charging zones, and chargers on the site.

These endpoints allow you to:

  • List all Locations in your network
  • Get detailed information about a specific Location

Retrieve Locations list with filters

Returns a list of all Locations available to the authenticated account (Partner) with a set of filters. Information includes details about location name, country, city, address, post code, geo-position, working hours, charging zones.

Authorizations:
api_key
query Parameters
country
string
Enum: "AF" "AX" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "KH" "CM" "CA" "CV" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "XK" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MK" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SZ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW"

Country code filter.

city
string
Example: city=New York

Exact city name filter.

addressSearch
string non-empty
Example: addressSearch=Wilshire Blvd

Substring match on the address name filter. Matching is exact (case-insensitive; no fuzzy matching).

locationNameSearch
string non-empty
Example: locationNameSearch=Main Street Garage

Substring match on the location name filter. Matching is exact (case-insensitive; no fuzzy matching).

Responses

Response samples

Content type
application/json
{
  • "locations": [
    ],
  • "meta": {
    }
}

Get Location by ID

Returns detailed information for a single Location. Information include details about Location name, country, city, address, post code, geo-position, working hours, charging zones.

Authorizations:
api_key
path Parameters
locationId
required
integer >= 1
Example: 123

Numeric location identifier.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Hilton Miami Beach",
  • "geoposition": {
    },
  • "address": "6261 Collins Ave, Miami Beach, FL 33140, USA",
  • "city": "Miami Beach",
  • "country": "US",
  • "postCode": "33140",
  • "workingHours": {
    },
  • "lastUpdatedAt": "2025-07-04T10:42:36+00:00",
  • "chargingZones": [
    ]
}

Charger Endpoints

These endpoints allow you to retrieve information about physical EV Chargers, including their model, status, charging ports, and location.

These endpoints allow you to:

  • List all Chargers in your network
  • Get detailed information about specific Charger

Retrieve Chargers list with filters

Returns a list of all Chargers available to the authenticated account (Partner) with a set of filters. Information should include details about the Charger such as name, system status, network details, type, EVSEs (ports), connectors, location.

Authorizations:
api_key
query Parameters
status
string
Enum: "enabled" "disabled" "out of order" "demo"
Example: status=enabled

Charger system status filter.

name
string non-empty
Example: name=EVPassport Test Lab - Demo

Exact charger name filter.

locationId
integer >= 1
Example: locationId=4

Numeric location identifier filter.

Responses

Response samples

Content type
application/json
{
  • "chargers": [
    ],
  • "meta": {
    }
}

Get Charger by ID

Returns detailed information for a single Charger. Information should include details about Charger such as name, system status, network details, type, EVSEs (ports), connectors, location.

Authorizations:
api_key
path Parameters
chargerId
required
integer >= 1
Example: 123

Numeric charger identifier.

Responses

Response samples

Content type
application/json
{
  • "id": 14,
  • "name": "EVPassport Test Lab - Demo",
  • "type": "public",
  • "locationId": 1,
  • "chargingZoneId": 4,
  • "networkType": "cellular",
  • "status": "demo",
  • "lastBootNotification": {
    },
  • "networkStatus": "available",
  • "hardwareStatus": "available",
  • "lastUpdatedAt": "2025-02-19T11:22:44+00:00",
  • "createdAt": "2025-02-19T10:52:06+00:00",
  • "chargerPorts": [
    ]
}

Charger Port Endpoints

Charger Ports represent individual EVSE connectors (ie, J1772, CCS, Tesla/NACS). These endpoints let you view port details, operational statuses, power options, and manage charging sessions.

Use these endpoints to:

  • List all Charger Ports across your network
  • Get detailed information about specific Ports
  • Start and stop charging sessions
  • Retrieve the status and details of a specific charging session

Retrieve Charger Ports list with filters

Returns a list of Charger Ports available to the authenticated account (Partner) with a set of filters. Information should include details about Charger Ports (EVSEs), current type, power options, connectors, system status, operational status, charger and location identifiers.

Authorizations:
api_key
query Parameters
locationId
integer >= 1
Example: locationId=4

Numeric location identifier filter.

hardwareStatus
string
Enum: "available" "preparing" "charging" "suspendedEV" "suspendedEVSE" "finishing" "reserved" "unavailable" "faulted" "occupied"
Example: hardwareStatus=available

Filter by operational status reported by the charger port (EVSE).

Responses

Response samples

Content type
application/json
{
  • "chargerPorts": [
    ],
  • "meta": {
    }
}

Get Charger Port by ID

Returns detailed information for a single Charger Port. Information should include details about the Charger Port (EVSE), current type, power options, connectors, system status, operational status, charger and location identifiers.

Authorizations:
api_key
path Parameters
chargerPortId
required
integer >= 1
Example: 123

Numeric identifier of the charger port (EVSE).

Responses

Response samples

Content type
application/json
{
  • "id": 20,
  • "chargerId": 16,
  • "physicalReference": "6242",
  • "locationId": 2,
  • "currentType": "ac",
  • "status": "enabled",
  • "powerOptions": {
    },
  • "hardwareStatus": "available",
  • "connectors": [
    ],
  • "createdAt": "2025-04-10T09:46:06+00:00",
  • "lastUpdatedAt": "2025-05-21T12:12:59+00:00"
}

Start a charging session on a Charger Port

This endpoint allows you to start a charging session by passing the Charger Port identifier, returns the session identifier and partial statuses. This action is asynchronous and requires some time to process. You can check the session status by a separate call to /v1/charger-ports/session-status/{sessionId} by the received session ID.

Authorizations:
api_key
path Parameters
chargerPortId
required
integer >= 1
Example: 123

Numeric identifier of the charger port (EVSE).

Request Body schema: application/json

The request body in this API version is empty, planned for future use with new features.

object (startChargingRequestSchema)

Empty request body for starting a charging session. Reserved for future use.

Responses

Request samples

Content type
application/json

The request body is empty in the current API version.

{ }

Response samples

Content type
application/json

Example response for a successful charging session start

{
  • "success": true,
  • "sessionId": 236,
  • "authorizationId": 223
}

Stop a charging session

This endpoint allows you to stop a charging session by its identifier. This action is asynchronous and requires some time to process. In response, you will receive a short message with success status of the operation. You can check the session status by a separate call to /v1/charger-ports/session-status/{sessionId} by the received session ID.

Authorizations:
api_key
path Parameters
sessionId
required
integer >= 1
Example: 123

Unique identifier of the charging session.

Request Body schema: application/json

The request body to stop a charging session.

force
boolean
Default: false

If true, forces the charging session to stop regardless of the CP response.

Responses

Request samples

Content type
application/json

Example request to stop a charging session

{
  • "force": false
}

Response samples

Content type
application/json

Example response for a successful charging session stop

{
  • "success": true
}

Retrieve Charging Session Status

This endpoint gives you relevant Status information about a Charging Session by its identifier. You can check details of the charging session which include session status, error reasons (if any), charger and charger port identifiers, start and end time, energy usage, cost, payment type, payment status, etc.

Authorizations:
api_key
path Parameters
sessionId
required
integer >= 1
Example: 123

Unique identifier of the charging session.

Responses

Response samples

Content type
application/json
{
  • "id": "1",
  • "chargerPortId": 4,
  • "chargerId": 3,
  • "status": "finished",
  • "reason": "force_stop",
  • "userId": 7,
  • "startedAt": "2024-11-25T11:01:06+00:00",
  • "stoppedAt": "2024-11-25T11:20:32+00:00",
  • "socPercent": 86,
  • "totalAmount": {
    },
  • "currency": "USD",
  • "paymentType": "balance",
  • "terminalId": 4,
  • "paymentStatus": "pending",
  • "evsePhysicalReference": "cgs11s-1",
  • "priceBreakdown": [
    ],
  • "paymentStatusUpdatedAt": "2024-11-29T15:02:34+00:00",
  • "lastUpdatedAt": "2024-11-29T15:02:34+00:00",
  • "totalEnergyConsumption": 37194,
  • "billingStatus": "pending"
}

Report Endpoints

The Reports endpoints provide access to historical and real-time data from your chargers. These include charging session logs, fault events, charger status snapshots, and transaction records.

Use these endpoints to:

  • Retrieve charging sessions across your network
  • Retrieve fault events and errors from chargers
  • Retrieve a real-time snapshot of charger statuses across your network
  • Retrieve a detailed list of financial transactions related to charging sessions

Retrieve Sessions list with filters and pagination

Returns a list of Session data, including start and end times, energy delivered, payment amount, payment status, billing status, and price breakdown.

Authorizations:
api_key
query Parameters
startedAfter
string <date-time>
Example: startedAfter=2024-11-01T00:00:00Z

Filter out sessions that started after this datetime (ISO 8601), results will be returned in UTC. At least one of startedAfter/endedBefore must be provided.

endedBefore
string <date-time>
Example: endedBefore=2024-11-30T23:59:59Z

Filter out sessions that ended before this datetime (ISO 8601), results will be returned in UTC. At least one of startedAfter/endedBefore must be provided.

chargerId
integer >= 1
Example: chargerId=3

Filter out charging sessions on a certain Charger by its identifier.

status
string
Enum: "unknown" "pending" "active" "finished" "failed" "expired"
Example: status=finished

Filter out sessions by their status.

paymentStatus
string
Enum: "pending" "paid" "partially" "failed"
Example: paymentStatus=pending

Filter out sessions by payment status.

billingStatus
string
Enum: "pending" "suspended" "completed"
Example: billingStatus=pending

Filter out sessions by billing status.

limit
integer [ 1 .. 100 ]
Default: 100

Max number of results to return.

page
integer >= 1
Default: 1

The page number to fetch (defaults to 1).

Responses

Response samples

Content type
application/json
{
  • "chargingSessions": [
    ],
  • "pagination": {
    },
  • "meta": {
    }
}

Returns Charger Statuses list with filters and pagination

Returns a real-time snapshot of all Charger Statuses across your network.

Authorizations:
api_key
query Parameters
chargerId
integer >= 1
Example: chargerId=3

Filter out charging sessions on a certain Charger by its identifier.

locationId
integer >= 1
Example: locationId=4

Numeric location identifier filter.

limit
integer [ 1 .. 100 ]
Default: 100

Max number of results to return.

cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wNC0yMiAxNjoxNDowNSIsImlkIjoxMDEsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9

Pagination cursor for next/previous page, keep empty for first page.

Responses

Response samples

Content type
application/json
{
  • "chargerStatuses": [
    ],
  • "cursorPagination": {
    },
  • "meta": {
    }
}

Retrieve the charger port Downtime Periods list with filters and pagination

Returns a list of Downtime Periods on the charger ports such as power issues, hardware and network errors, system status, start and end time of the downtime periods, and their entry mode. Includes details required to identify location, charger, and port. Useful for diagnostics, support workflows, and maintenance reporting.

Authorizations:
api_key
query Parameters
startedAfter
string <date-time>
Example: startedAfter=2025-07-01T00:00:00Z

ISO 8601 formatted date filter. Lists only the faults started after this datetime, results will be returned in UTC. At least one of startedAfter/stoppedBefore must be provided.

stoppedBefore
string <date-time>
Example: stoppedBefore=2025-07-31T23:59:59Z

ISO 8601 formatted date filter. Lists only the faults ended before this datetime, results will be returned in UTC. At least one of startedAfter/stoppedBefore must be provided.

locationId
integer >= 1
Example: locationId=1

Filter out downtime periods of the ports at the specified location by ID.

entryMode
string
Enum: "manual" "automatic"
Example: entryMode=automatic

Filter out downtime periods by entry mode.

type
string
Enum: "downtime" "exempt"
Example: type=downtime

Filter out downtime periods by entry type.

limit
integer [ 1 .. 100 ]
Default: 100

Max number of results to return.

cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wNC0yMiAxNjoxNDowNSIsImlkIjoxMDEsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9

Pagination cursor for next/previous page, keep empty for first page.

Responses

Response samples

Content type
application/json
{
  • "downtimePeriods": [
    ],
  • "cursorPagination": {
    },
  • "meta": {
    }
}

Retrieve Transactions list with filters and pagination

Returns a detailed list of Transactions related to charging sessions, including session times, energy delivered, cost, payment method, status, billing type, failure reason (if any), charger and port identifiers, location data.

Authorizations:
api_key
query Parameters
createdAfter
string <date-time>
Example: createdAfter=2025-07-01T00:00:00Z

ISO 8601 formatted date filter. Lists only the transactions created after this datetime, results will be returned in UTC. At least one of createdAfter or createdBefore must be provided.

createdBefore
string <date-time>
Example: createdBefore=2025-07-31T23:59:59Z

ISO 8601 formatted date filter. Lists only the transactions created before this datetime, results will be returned in UTC. At least one of createdAfter or createdBefore must be provided.

status
string
Enum: "pending" "finalized" "failed" "reversed" "refunded" "authorized" "initialized"
Example: status=finalized

Filter out transaction by their status.

sessionId
integer >= 1
Example: sessionId=123

Filter out transactions by a specific session ID.

limit
integer [ 1 .. 100 ]
Default: 100

Max number of results to return.

page
integer >= 1
Default: 1

The page number to fetch (defaults to 1).

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pagination": {
    },
  • "meta": {
    }
}

Status Check Endpoints

Endpoints for checking the status of the API stack and the system

Status check endpoint

Check the status of the API and the system.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "message": "Lambda status check completed",
  • "environment": "vfihu",
  • "status": "Status of checked systems: []",
  • "lambdaVariables": {
    }
}