Identifiers

TandemDrive uses universally unique identifiers (UUIDs) for most data records. We use UUID version 7, as defined in RFC 9562. However, records created before July 1, 2023, may have been assigned UUID version 4.

In addition to the TandemDrive-generated identifiers, you can assign your own identifiers to certain types of data. These are called external references, as they originate outside of TandemDrive. External references must be unique, though they can be left empty if not needed. Note that these external_reference fields are case-sensitive.

To view TandemDrive-generated identifiers in the TandemDrive Console, press Shift + Y.

Identifier or prefixed external reference

To simplify API usage without requiring storage of TandemDrive identifiers in your client system, several endpoints accept parameters that can either be a TandemDrive identifier or an external reference. When using an external reference, it must be prefixed with the string ext_ref. — that is, the literal string ext_ref followed by a period (.). This prefix helps distinguish external references.

Identifier or external reference in request body

Similar to the URL parameters, some request bodies can refer to entities using either an .._id or an .._external_reference property. If both options are available in the request body specification, you must provide exactly one of them.

In the following two examples, both creating a billing_address, the reference to a specific party can be specified using either party_external_reference or party_id:

{
  "party_external_reference": "ABC-123",
  "country": "NL",
  "external_reference": "ABC-123",
  "locality": "Amsterdam",
  "valid_from": "2022-06-01T12:00:00+02:00"
}

{
  "party_id": "2479037a-21d1-4c09-827b-5922b8a16a80",
  "country": "NL",
  "external_reference": "ABC-123",
  "locality": "Amsterdam",
  "valid_from": "2022-06-01T12:00:00+02:00"
}

eMobility Identifiers

For the official definition of EVCO ID (also known as eMA ID) and EVSE ID, please refer to the IDACS e-Mobility Identifiers document, d.d. September 2023.

For machine-to-machine communication, IDACS strongly advise against using separators in identifiers like EVSE and EVCO IDs. Separators should only be used to improve human readability in a user interface.

Our API accepts IDs with or without separators. To align with IDACS guidelines, API responses will be updated to return both the original value and a normalized version.

EVCO ID (EV Contract ID), also known as eMA ID

This identifier represents an EV Contract or Electric Mobility Account (EMA). It should not be confused with the Token UID.

For tokens currently issued by TandemDrive, this identifier uniquely represents each token, to avoid revealing the relationship between tokens and end-customer contracts to roaming partners. TandemDrive adheres to the eMA-ID standard, incorporating a check-digit in all issued tokens. For details on its syntax, please refer to the IDACS document mentioned above.

For EVCO IDs issued by external platforms, these requirements may not apply, though compliance with the eMA-ID standard is recommended.

This identifier is sometimes visible to the end user, unlike the Token UID, which is often not displayed.

Examples of syntactically valid EVCO IDs which comply with eMA-ID:

• NLABCC11222344X
• NL-TDR-CA1B2C3D4-E

Token UID

The Token UID is a unique identifier used by charging systems to recognize a specific charging token.

It’s crucial to distinguish the UID from the EVCO ID / eMA ID.

• For RFID Tokens (like a key fob or card), the UID is the serial number physically read by the RFID scanner at the charge point.

  For RFID tokens (NFC / smartcards), the RFID UID typically serves as the Token UID, following the ISO/IEC 14443 standard. Refer to the “AN10927 MIFARE product and handling of UIDs” document published by NXP for more information about NFC UIDs (ISO/IEC 14443).

• For ISO 15118 Tokens (used for “Plug & Charge”), the UID is the same as the eMA ID, but without any separators.

• For virtual Tokens (used for remote start/stop), the UID can be randomly generated. Some CPMSs may not support UIDs longer than 20 characters.

Please be aware that this field is case-insensitive. Only printable ASCII characters, excluding spaces, are allowed. Specifically, all characters in these strings must have Unicode code points ranging from U+0021 to U+007E, inclusive.

EVSE ID

The EVSE ID is a reusable identifier for a charging station (EVSE). For example if a charging station is physically replaced or revised, the replacement may retain the same EVSE ID. For details on its syntax, please refer to the IDACS document mentioned above.

This is different from the EVSE UID.

Examples of syntactically valid EVSE IDs:

• NLABCE987ABC654DEF
• NL*TDR*E1234567*890

EVSE UID

The EVSE UID provides a unique, permanent identifier for an EVSE across all locations associated with the same CPO ID. It cannot be changed, modified, or renamed. This identifier is intended for technical purposes and should not be confused with the more user-friendly EVSE ID.

EVSE UIDs must be handled in a case-insensitive manner (as per OCPI 2.2 and later versions). Only printable ASCII characters, excluding spaces, are allowed. Specifically, all characters in these strings must have Unicode code points ranging from U+0021 to U+007E, inclusive.