Access IDs

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 | 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
    // 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:

curl "https://api.getflipturn.com/api/access-ids" -H "Authorization: Bearer {token}"

Response:

{
  "data": [
    {
      "id": 123,
      "ocppIdTag": "id-tag-1",
      "type": "Vehicle",
      "name": "Vehicle 1",
      "authorizationStatus": "Authorized",
      "authorizedAt": "2024-08-02T19:13:28.897Z",
      "revokedAt": null,
      "createdAt": "2024-08-02T19:13:28.897Z",
      "updatedAt": "2024-08-08T21:29:51.795Z",
      "vehicle": {
        "id": 20,
        "make": "Tesla",
        "model": "Model 3",
        "name": "Demo Tesla",
        "vin": "demo-vin-1"
      }
    },
    {
      "id": 124,
      "ocppIdTag": "rfid-card-1",
      "type": "RFID",
      "name": "RFID Card 1",
      "authorizationStatus": "Authorized",
      "authorizedAt": "2024-08-27T15:11:37.080Z",
      "revokedAt": null,
      "createdAt": "2024-08-08T16:21:17.191Z",
      "updatedAt": "2024-08-28T19:39:35.378Z",
      "vehicle": null
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "NDMyNDc2"
  }
}

GET /api/access-ids/{id}

Retrieve the details for a specific Access ID (RFID Card or Vehicle).

Response

{
  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;
  }
};

Example request and response

Request:

curl "https://api.getflipturn.com/api/access-ids/123" -H "Authorization: Bearer {token}"

Response:

{
  "accessId": {
    "id": 123,
    "ocppIdTag": "id-tag-1",
    "type": "Vehicle",
    "name": "Vehicle 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Demo Tesla",
      "vin": "demo-vin-1"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}

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:

1. A vehicle has multiple charging ports with different MAC IDs

2. A vehicle MAC ID has changed over time, and you wish to maintain the connection to old charging sessions

Request Body

{
  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;
    }
  }
}

Response

{
  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;
  }
};

Example request for vehicle and response

Request:

curl -X POST "https://api.getflipturn.com/api/access-ids" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "type": "Vehicle",
    "ocppIdTag": "test-ocpp-id-tag",
    "name": "Vehicle 1",
    "vehicle": {
      "vin": "demo-vehicle-vin",
      "make": "Tesla",
      "model": "Model 3"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'

Response:

{
  "accessId": {
    "id": 123,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "Vehicle",
    "name": "Vehicle 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Vehicle 1",
      "vin": "demo-vehicle-vin"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}

Example request for RFID card and response

Request:

curl -X POST "https://api.getflipturn.com/api/access-ids" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "type": "RFID",
    "ocppIdTag": "test-ocpp-id-tag",
    "name": "Card 1",
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'

Response:

{
  "accessId": {
    "id": 123,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "RFID",
    "name": "Card 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": null,
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}

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.

{
  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)
    }
  }
}

Response

{
  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;
  }
};

Example request and response

Request:

curl -X PATCH "https://api.getflipturn.com/api/access-ids/321" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "name": "Decommissioned Vehicle",
    "authorizationStatus": "Revoked",
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'

Response:

{
  "accessId": {
    "id": 321,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "Vehicle",
    "name": "Decommissioned Vehicle",
    "authorizationStatus": "Revoked",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": "2024-08-10T15:13:28.897Z",
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-10T15:13:28.897Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Vehicle 1",
      "vin": "demo-vehicle-vin"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}