Sites

GET /api/sites

Retrieve a list of an organization's sites, chargers, and ports, as well as their most recent status and details about any ongoing charging sessions.

This endpoint has no parameters, and returns all sites, chargers, and ports each time.

Response

The JSON response will contain a data field, which represents a nested list of sites, chargers, and charging ports.

{
  data: {
    id: number;
    name: string;
    address: string | null;
    timezone: string; // IANA format
    organization: {
      id: number;
      name: string;
    },
    chargers: {
      id: number;
      name: string;
      manufacturer: string | null;
      model: string | null;
      serialNumber: string | null;
      firmwareVersion: string | null;
      latitude: number | null;
      longitude: number | null;
      externalId: string | null;
      ocppId: string | null;

      // null if the charger has never connected to Flipturn
      connectionStatus: {
        status: string; // e.g. "Connected", "Disconnected"
        timestamp: string; // ISO 8601 format
      } | null;
      numberOfPorts: number;
      ports: {
        id: number;
        name: string;
        portNumber: number;
        maximumPowerKw: number | null;
        // null if the port has never sent an OCPP status
        ocppStatus: {
          status: string; // e.g. "Available", "Charging", "Faulted"
          timestamp: string; // ISO 8601 format
          errorCode: string; // OCPP error code, e.g. "NoError", "ConnectorLockFailure"
          vendorErrorCode: string | null; // Vendor-specific error code
          info: string | null; // Additional error information
        } | null;

        // Information about any ongoing charging session -- will be null if no charging session is
        // currently happening on this charger
        currentChargingSession: {
          id: number;
          startTime: string; // ISO 8601 format
          socStartPercent: number | null;
          energyDeliveredKwh: number;
          ocppIdTag: string | null;
          ocppTransactionId: number | null;
          // Latest meter readings from the charging session
          latestReadings: {
            powerKw: {
              value: number;
              timestamp: string; // ISO 8601 format
            } | null;
            currentA: {
              value: number;
              timestamp: string; // ISO 8601 format
            } | null;
            socPercent: {
              value: number;
              timestamp: string; // ISO 8601 format
            } | null;
            voltage: {
              value: number;
              timestamp: string; // ISO 8601 format
            } | null;
          };
          vehicle: {
            id: number;
            make: string | null;
            model: string | null;
            name: string;
            vin: string | null;
          } | null;
          rfid: {
            id: number;
            name: string | null;
          } | null;
          customer: {
            name: string;
          } | null;
        } | null;
      }[];
    }[];
  }[];
}

Example request and response

Request:

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

Response:

{
  "data": [{
    "id": 1,
    "name": "Site 1",
    "address": "1234 Fake St, Long Beach, CA 90802",
    "timezone": "America/Los_Angeles",
    "organization": {
      "name": "Flipturn Demo Organization",
      "id": 1
    },
    "chargers": [
      {
        "id": 1,
        "manufacturer": "ABB",
        "model": "AC Wall Box",
        "name": "Test Charger",
        "serialNumber": "1234-5678",
        "firmwareVersion": "1.5.4.4",
        "externalId": "STATION-001",
        "ocppId": "CHARGER-001",
        "connectionStatus": {
          "status": "Connected",
          "timestamp": "2025-01-01T12:00:00.000Z"
        },
        "numberOfPorts": 1,
        "ports": [
          {
            "id": 1,
            "maximumPowerKw": 180,
            "name": "Test Port",
            "portNumber": 1,
            "ocppStatus": {
              "status": "Available",
              "timestamp": "2025-01-01T12:00:00.000Z",
              "errorCode": "NoError",
              "vendorErrorCode": null,
              "info": null
            },
            "currentChargingSession": {
              "id": 123,
              "startTime": "2025-01-01T11:30:00.000Z",
              "socStartPercent": 20,
              "energyDeliveredKwh": 10.5,
              "ocppIdTag": "test-tag",
              "ocppTransactionId": 456,
              "latestReadings": {
                "powerKw": {
                  "value": 50,
                  "timestamp": "2025-01-01T11:45:00.000Z"
                },
                "currentA": {
                  "value": 100,
                  "timestamp": "2025-01-01T11:45:00.000Z"
                },
                "socPercent": {
                  "value": 35,
                  "timestamp": "2025-01-01T11:45:00.000Z"
                },
                "voltage": {
                  "value": 400,
                  "timestamp": "2025-01-01T11:45:00.000Z"
                }
              },
              "vehicle": {
                "id": 22541553,
                "make": "Make",
                "model": "Model",
                "name": "9876",
                "vin": "demo-vin-0"
              },
              "rfid": null,
              "customer": {
                "name": "Test Customer"
              }
            }
          }
        ]
      }
    ]
  }]
}