OCPI Endpoints Reference: API Guide for 2.1.1 and 2.2.1

OCPI is a REST API protocol. Every interaction between a CPO and an eMSP -- or between either party and a roaming hub like GIREVE -- is a standard HTTP request carrying a JSON payload. There are no WebSocket connections, no binary frames, no persistent channels. If you understand REST, you understand the transport layer of OCPI. What makes OCPI distinct is its module-based architecture: each functional domain (locations, sessions, billing, authorization) has its own set of endpoints with clearly defined ownership between parties.

This reference covers every endpoint across all OCPI modules for versions 2.1.1 and 2.2.1. For each module, you will find the purpose, which party implements which endpoints, the full endpoint table, key data fields, and implementation notes. If you are new to OCPI as a protocol, start there first. This document assumes you understand the basics and need the endpoint-level detail.

For version-specific implementation validation, pair this reference with OCPI 2.1.1 testing and OCPI 2.2.1 testing.

Base URL Structure and Versioning

Every OCPI implementation exposes a single entry point: the versions endpoint. From there, all module endpoints are discovered dynamically. There are no hardcoded paths. The base URL structure follows this pattern:

https://api.example.com/ocpi/

From this root, the protocol defines two discovery endpoints that every implementation must support:

• GET /versions -- returns a list of supported OCPI versions with their URLs
• GET /versions/{version_id} -- returns the list of module endpoints for a specific version

A typical versions response looks like this:

{
  "status_code": 1000,
  "data": [
    {
      "version": "2.1.1",
      "url": "https://api.example.com/ocpi/2.1.1"
    },
    {
      "version": "2.2.1",
      "url": "https://api.example.com/ocpi/2.2.1"
    }
  ]
}

When you call the version-specific URL, you receive the full list of module endpoints that party supports:

{
  "status_code": 1000,
  "data": {
    "version": "2.1.1",
    "endpoints": [
      { "identifier": "credentials", "url": "https://api.example.com/ocpi/2.1.1/credentials" },
      { "identifier": "locations", "url": "https://api.example.com/ocpi/2.1.1/locations" },
      { "identifier": "sessions", "url": "https://api.example.com/ocpi/2.1.1/sessions" },
      { "identifier": "cdrs", "url": "https://api.example.com/ocpi/2.1.1/cdrs" },
      { "identifier": "tariffs", "url": "https://api.example.com/ocpi/2.1.1/tariffs" },
      { "identifier": "tokens", "url": "https://api.example.com/ocpi/2.1.1/tokens" },
      { "identifier": "commands", "url": "https://api.example.com/ocpi/2.1.1/commands" }
    ]
  }
}

This dynamic discovery is a core design principle. You never assume where a module lives. You always discover it through the version endpoint. This allows implementations to host modules on different servers, use different URL structures, or version independently.

Authentication and the Credentials Handshake

OCPI uses token-based authentication. Every HTTP request includes an Authorization header with a Token prefix:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qc09VG7I7d/WCg0koM=

These tokens are not JWTs. They are opaque strings, typically base64-encoded random bytes. The critical aspect is how they are exchanged: through the credentials handshake.

The Credentials Exchange Flow

The credentials module is the only module that uses a pre-shared token (TOKEN_A) for initial authentication. The flow works as follows:

Step 1: Out-of-band, Party A and Party B agree on a TOKEN_A. This is typically exchanged via email, a hub's admin portal, or a registration API.

Step 2: Party A calls GET /versions on Party B's platform, authenticating with TOKEN_A, to discover supported versions.

Step 3: Party A calls GET /versions/2.1.1 (or whichever version both support) to discover Party B's module endpoints.

Step 4: Party A sends POST /credentials to Party B, including:

• Party A's own credentials URL
• Party A's generated TOKEN_B (the token Party B will use to call Party A)
• Party A's business details (party_id, country_code, name, roles)

Step 5: Party B validates the request, stores TOKEN_B for future use, and responds with:

• Party B's generated TOKEN_C (the token Party A will use to call Party B going forward)
• Party B's business details

From this point forward, TOKEN_A is invalidated. Party A uses TOKEN_C to authenticate requests to Party B. Party B uses TOKEN_B to authenticate requests to Party A.

Credentials Module Endpoints

The PUT /credentials endpoint allows either party to rotate tokens at any time without disrupting the connection. This is a significant security advantage and should be done periodically in production deployments.

Locations Module

The Locations module is the backbone of OCPI. It contains the complete inventory of charge points, their physical locations, capabilities, and real-time status. Every roaming connection starts with location data exchange.

OCPI uses a three-level hierarchy: Location (a physical site) contains one or more EVSEs (individual charge points), each of which has one or more Connectors (physical sockets).

Implemented by: CPO (sender/owner of location data), eMSP (receiver)

CPO Endpoints (Sender Interface)

These endpoints are implemented by the CPO. The eMSP calls them to pull location data.

eMSP Endpoints (Receiver Interface)

These endpoints are implemented by the eMSP. The CPO calls them to push location updates.

Key Location Data Fields

Key EVSE Data Fields

Push vs Pull for Locations

In production, CPOs push EVSE status changes in real-time using PATCH requests. The eMSP uses GET /locations with date_from filtering for periodic full synchronization -- typically daily or weekly -- to catch any missed push updates. When a CPO sends a PATCH, it should include only the changed fields. A common implementation error is sending full objects via PATCH instead of partial updates, which defeats the purpose of the method.

Sessions Module

The Sessions module tracks active charging sessions in near-real-time. An eMSP uses session data to show drivers the status of their ongoing charge, including energy delivered, duration, and estimated cost.

Implemented by: CPO (sender/owner of session data), eMSP (receiver)

CPO Endpoints (Sender Interface)

eMSP Endpoints (Receiver Interface)

Key Session Data Fields

Implementation Notes

During an active session, the CPO should push session updates to the eMSP at regular intervals -- typically every 30 to 60 seconds. Each update includes the latest kwh value and total_cost. When the session ends, a final PATCH sets the status to COMPLETED and the end_datetime. The session object is then considered immutable. For billing, always rely on the CDR, not the final session object.

CDRs Module (Charge Detail Records)

CDRs are the billing backbone of OCPI. After a charging session completes, the CPO generates a CDR containing the definitive record of what was consumed and what it costs. CDRs are immutable once created -- they cannot be updated or deleted through OCPI.

Implemented by: CPO (sender), eMSP (receiver)

CPO Endpoints (Sender Interface)

eMSP Endpoints (Receiver Interface)

Key CDR Data Fields

Charging Periods and Dimensions

Each CDR contains an array of ChargingPeriod objects, which break the session into time-based segments. Each period has a start_date_time and an array of CdrDimension objects:

These dimensions map directly to tariff elements, enabling precise cost calculation. If you are building a billing system, the CDR's charging periods are the source of truth for invoice generation.

Tariffs Module

The Tariffs module defines pricing structures for charging sessions. CPOs publish their tariffs so eMSPs can display estimated costs to drivers before they start charging.

Implemented by: CPO (sender), eMSP (receiver)

CPO Endpoints (Sender Interface)

eMSP Endpoints (Receiver Interface)

Key Tariff Data Fields

Tariff Elements and Restrictions

Each TariffElement contains a list of PriceComponent objects and optional TariffRestrictions:

Price Components:

Tariff Restrictions (conditions under which the element applies):

This structure enables complex pricing models: different rates for peak vs off-peak hours, penalties for overstaying after charging completes, tiered energy pricing, and more.

Tokens Module

The Tokens module handles driver authorization. eMSPs push their driver tokens (RFID cards, app credentials) to CPOs so that authorization can happen locally without requiring a real-time API call for every charge attempt.

Implemented by: eMSP (sender/owner of token data), CPO (receiver)

Note the reversed ownership: unlike most modules where the CPO is the data owner, here the eMSP owns and pushes token data to the CPO.

eMSP Endpoints (Sender Interface)

CPO Endpoints (Receiver Interface)

Key Token Data Fields

Real-Time Authorization

The POST /tokens/{token_uid}/authorize endpoint is special. When a driver presents an RFID card at a charger, the CPO's backend can call this endpoint on the eMSP to get a real-time authorization decision. The eMSP responds with an AuthorizationInfo object containing ALLOWED, BLOCKED, EXPIRED, NO_CREDIT, or NOT_ALLOWED. This is used when the whitelist value is NEVER or when the token is not in the CPO's local cache.

Commands Module

The Commands module enables remote operations on charge points through the roaming chain. An eMSP can instruct a CPO to start a session, stop a session, reserve a charger, or unlock a connector -- all on behalf of the driver.

Implemented by: CPO (receiver of commands), eMSP (sender of commands)

CPO Endpoints (Receiver Interface)

eMSP Endpoints (Callback)

Command Request Fields

START_SESSION:

STOP_SESSION:

RESERVE_NOW:

UNLOCK_CONNECTOR:

Asynchronous Command Flow

Commands are asynchronous by design. The flow is:

1. eMSP sends POST /commands/START_SESSION to the CPO
2. CPO responds immediately with ACCEPTED or REJECTED (synchronous response indicating whether the command was received, not whether it succeeded)
3. CPO forwards the command to the charger via OCPP
4. When the charger responds, the CPO sends the final result (ACCEPTED, REJECTED, TIMEOUT, UNKNOWN_SESSION, etc.) to the response_url provided in the original request

This two-step flow is necessary because charger communication via OCPP can take several seconds. The eMSP must handle both the synchronous acknowledgment and the asynchronous callback.

ChargingProfiles Module (2.2.1 Only)

The ChargingProfiles module was introduced in OCPI 2.2.1 to enable smart charging through the roaming chain. It allows an eMSP or hub to set power limits on active charging sessions, enabling demand response, fleet management, and grid balancing use cases.

Implemented by: CPO (receiver), eMSP (sender)

CPO Endpoints (Receiver Interface)

eMSP Endpoints (Callback)

Charging Profile Structure

Each ChargingProfilePeriod specifies:

• start_period: Offset in seconds from start_date_time
• limit: Maximum power (W) or current (A) for this period

This module maps closely to OCPP's Smart Charging profile. The CPO translates the OCPI charging profile into an OCPP SetChargingProfile request sent to the charger.

HubClientInfo Module (2.2.1 Only)

The HubClientInfo module is used exclusively in hub-based topologies (like GIREVE or Hubject). It allows the hub to inform connected parties about the status and capabilities of other parties connected to the hub.

Implemented by: Hub (sender), CPO/eMSP (receiver)

Hub Endpoints (Sender Interface)

CPO/eMSP Endpoints (Receiver Interface)

Key HubClientInfo Data Fields

This module is primarily used for discovery. An eMSP can use it to know which CPOs are reachable through the hub and what their connection status is.

OCPI Data Types Reference

Several data types are shared across multiple modules. Understanding these is essential for correct implementation.

Common Enumerations

CdrToken Object

The CdrToken is a lightweight token reference embedded within CDRs and Sessions, distinct from the full Token object:

DisplayText Object

Used throughout OCPI for multilingual text content:

GeoLocation Object

Note that coordinates are strings, not floating-point numbers. This is intentional to avoid floating-point precision loss during serialization.

Error Handling and Status Codes

Every OCPI response includes a status_code field. This is distinct from the HTTP status code. The OCPI status code provides protocol-level information about the request outcome.

OCPI Status Code Ranges

Specific Status Codes

HTTP Status Codes

OCPI also uses standard HTTP status codes:

A critical implementation detail: always check both the HTTP status code AND the OCPI status code. A 200 HTTP response with an OCPI status code of 2001 means the request was received but contained invalid parameters. Many implementations incorrectly check only the HTTP code and miss protocol-level errors.

Pagination

All GET list endpoints support pagination through the following headers and parameters:

Request parameters: offset (starting index), limit (max items per page), date_from, date_to

Response headers: X-Total-Count (total number of objects), X-Limit (server-imposed max per page), Link (URL to next page)

Always respect the server's X-Limit header. If you request limit=1000 but the server returns X-Limit: 100, you must paginate with 100-item pages.

OCPI 2.1.1 vs 2.2.1: Key Differences

While the core architecture remains the same, OCPI 2.2.1 introduced several important changes:

New Modules in 2.2.1

• ChargingProfiles: Smart charging through the roaming chain (described above)
• HubClientInfo: Hub connection status information (described above)

Structural Changes

Module Identifier Changes

The module identifiers used in version endpoint discovery are the same across both versions: credentials, locations, sessions, cdrs, tariffs, tokens, commands. The 2.2.1 additions use chargingprofiles and hubclientinfo.

Data Model Changes

In 2.2.1, several objects gained additional fields for richer data exchange. The Location object added time_zone and publish fields. The Tariff object added the type field for categorizing pricing structures. The Token object refined the whitelist types and added group_id for corporate fleet management.

If you are implementing a new system, target 2.2.1 as the primary version. Most hubs and major CPOs/eMSPs support 2.2.1. Maintain 2.1.1 compatibility only if your roaming partners require it.

Frequently Asked Questions

How does OCPI differ from OCPP?

OCPP is the protocol between a charger and a backend system (CSMS). It uses WebSocket connections and handles charge point management, firmware updates, and local authorization. OCPI is the protocol between backend systems (CPO-to-eMSP or CPO-to-Hub). It uses standard REST APIs and handles roaming, data exchange, and inter-network billing. A typical deployment uses both: OCPP from charger to CPO backend, and OCPI from CPO backend to eMSP or hub.

Do I need to implement all OCPI modules?

No. The only mandatory module is Credentials. All other modules are optional. In practice, a minimal viable implementation typically includes Locations, Sessions, CDRs, and Tokens. Commands is highly recommended if you want to support remote start/stop from roaming partners. Tariffs is important for cost transparency.

How do roaming hubs like GIREVE fit into the endpoint structure?

A roaming hub acts as an intermediary. Instead of establishing direct peer-to-peer OCPI connections with every partner, you connect once to the hub. The hub then proxies requests to and from all other connected parties. From an endpoint perspective, your implementation is identical -- you implement the same sender/receiver interfaces. The only addition is the HubClientInfo module (2.2.1), which the hub uses to inform you about other connected parties.

What happens if a push update fails?

OCPI does not define a retry mechanism in the specification. If a push request fails (network error, 5xx response), the sending party should implement its own retry logic with exponential backoff. The pull mechanism serves as a safety net: the receiving party's periodic pull synchronization will eventually catch updates that were missed during push failures.

Can I use OCPI without a roaming hub?

Yes. OCPI supports direct peer-to-peer connections between a CPO and an eMSP. This is common in markets where a CPO has a small number of roaming partners. However, as the number of partners grows, the hub model becomes more efficient because it reduces the number of connections from O(n^2) to O(n).

What is the difference between PUT and PATCH in OCPI?

PUT replaces the entire object. The request body must contain all required fields. PATCH performs a partial update -- only the fields included in the request body are updated. In practice, use PUT when creating or fully replacing an object, and PATCH for incremental updates like status changes. A PATCH with a field set to null removes that optional field from the object.

OCPI's module-based, REST architecture makes it approachable for any team with HTTP API experience. The key to a successful implementation is getting the credential handshake right, implementing both push and pull modes for resilience, and testing thoroughly against real roaming partners or a hub's sandbox environment. For testing your OCPP charger integration that feeds data into your OCPI layer, an OCPP simulator can validate your entire charging and roaming chain end-to-end.