Access IDs include RFID cards or vehicles. When a charger identifies who is initiating a charging session, it sends us an ID tag. This ID can be from one of the following sources:
RFID Card: A card that is scanned on the charger to authenticate the user before charging begins.
Vehicle: The MAC ID of a vehicle that is directly plugged into the charger.
GET /api/access-ids
Retrieve a list of all Access IDs.
Response
The JSON response will contain a data field with a list of access ids, and a pagination field containing pagination details.
{data:{id:number;ocppIdTag:string;type:string;// RFID | Vehiclename:string;authorizationStatus:string;// Authorized | RevokedauthorizedAt:string;// ISO 8601 formatrevokedAt:string|null;// ISO 8601 format or null. Set only if authorizationStatus is RevokedcreatedAt:string;// ISO 8601 formatupdatedAt:string;// ISO 8601 format // Only defined if the "type" is a vehicle:vehicle:{id:number;make:string|null;model:string|null;name:string;vin:string|null;}|null;}[];pagination:{hasNextPage:boolean;nextPageCursor:string|null;};};
Example request and response
Request:
Response:
GET /api/access-ids/{id}
Retrieve the details for a specific Access ID (RFID Card or Vehicle).
Response
Example request and response
Request:
Response:
POST /api/access-ids
Create a new access ID. An access ID can be of two types: RFID or Vehicle. When creating a vehicle access ID, you can either create a new vehicle by passing in the vehicle parameters, or associate the new access ID with an existing vehicle by passing a vehicleId.
A single vehicle can have multiple access IDs, which can be used to represent cases where:
A vehicle has multiple charging ports with different MAC IDs
A vehicle MAC ID has changed over time, and you wish to maintain the connection to old charging sessions
Request Body
Response
Example request for vehicle and response
Request:
Response:
Example request for RFID card and response
Request:
Response:
PATCH /api/access-ids/{id}
Update an Access ID (RFID Card or Vehicle).
Request Body
For optional fields, explicitly providing null will delete the value.
Response
Example request and response
Request:
Response:
PUT /api/access-ids/batch
Create or update up to 1000 access IDs in a single request. This endpoint is designed for syncing an entire fleet of vehicles or RFID cards with Flipturn.
The endpoint matches existing access IDs by ocppIdTag. If a matching access ID exists, it is updated; otherwise, a new one is created.
Vehicles are matched by name (case-insensitive). If no vehicle with the name exists, one is created automatically. Multiple access IDs with the same name are grouped onto the same vehicle.
Access IDs not included in the request are not affected, so an access ID will never be deleted from this endpoint.
Request Body
Edge cases
If multiple items in a single request share the same vehicle name but provide different vehicle details (make, model, vin), the first item's details are used for the vehicle.
If a vehicle already has telematics data, the vin field from the request is ignored to avoid overwriting telematics-sourced VIN data.
Response
Each item in the results array corresponds to the item at the same index in the request. Items that fail are returned with outcome: "error" and an error message; other items in the batch are still processed.
{
accessId: {
type: string; // RFID | Vehicle (required)
name: string; // (required)
ocppIdTag: string; // (required)
authorizationStatus: string; // Authorized | Revoked (optional: defaults to Authorized)
// For Vehicle type only, pass these to create a new vehicle (optional)
vehicle?: {
make: string; // (optional "type" param must be vehicle)
model: string; // (optional "type" param must be vehicle)
vin: string; // (optional "type" param must be vehicle)
}
// For Vehicle type only, pass a vehicleId to associate with an existing vehicle
vehicleId?: number; // (optional)
// Pass to associate with an existing Customer or create a new Customer. Creates a new customer
// if no existing customer is found with the same name, case insensitive. (optional)
customer?: {
name: string;
}
}
}
{
accessId: {
id: number;
ocppIdTag: string; // This value is normalized, and as such may not exactly match what was POSTed
type: string; // RFID | Vehicle
name: string;
authorizationStatus: string; // Authorized | Revoked
authorizedAt: string; // ISO 8601 format
revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
createdAt: string; // ISO 8601 format
updatedAt: string; // ISO 8601 format
vehicle: {
id: number;
make: string | null;
model: string | null;
name: string;
vin: string | null;
} | null;
customer: {
name: string;
} | null;
}
};
{
accessId: {
name: string;
authorizationStatus: string; // Authorized | Revoked
vehicle: {
make: string;
model: string;
vin: string;
},
customer: {
name: string; // (creates a new customer if no existing customer is found with the same name, case insensitive)
}
}
}
{
accessId: {
id: number;
ocppIdTag: string;
type: string; // RFID | Vehicle
name: string;
authorizationStatus: string; // Authorized | Revoked
authorizedAt: string; // ISO 8601 format
revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
createdAt: string; // ISO 8601 format
updatedAt: string; // ISO 8601 format
vehicle: {
id: number;
make: string | null;
model: string | null;
name: string;
vin: string | null;
} | null;
customer: {
name: string
} | null;
}
};
{
accessIds: {
ocppIdTag: string; // (required)
name: string; // (required)
type: string; // RFID | Vehicle (required)
authorizationStatus?: string; // Authorized | Revoked (optional: defaults to Authorized for new items)
// For Vehicle type only (optional). Providing this on an RFID-type item returns an error.
vehicle?: {
make?: string | null;
model?: string | null;
vin?: string | null;
}
// Associate with a customer. Creates a new customer if no existing customer
// is found with the same name (case-insensitive). (optional)
customer?: {
name: string;
}
}[] // Maximum 1000 items per request
}
{
results: {
ocppIdTag: string; // Normalized ocppIdTag
outcome: string; // created | updated | error
accessId?: {
id: number;
ocppIdTag: string;
type: string; // RFID | Vehicle
name: string;
authorizationStatus: string; // Authorized | Revoked
authorizedAt: string; // ISO 8601 format
revokedAt: string | null;
createdAt: string; // ISO 8601 format
updatedAt: string; // ISO 8601 format
vehicle: {
id: number;
make: string | null;
model: string | null;
name: string;
vin: string | null;
} | null;
customer: {
name: string;
} | null;
}; // Present when outcome is "created" or "updated"
error?: string; // Present when outcome is "error"
}[]
}
