Zaptec Charge History API

openapi: 3.2.0
info:
  title: Zaptec Charge History API
  version: v1
servers:
- url: https://api.zaptec.com
tags:
- name: ChargeHistory
paths:
  /api/chargehistory:
    get:
      tags:
      - ChargeHistory
      summary: Completed sessions (deprecated)
      description: '**Deprecated**: Use `GET /api/sessions/archived` instead.

        This endpoint is being phased out with the following timeline:

        - From **2026-08-01**, closed sessions older than two years are no longer returned.

        - From **2027-01-01**, closed sessions are removed / endpoint sunset.

        Retrieves all completed charge sessions accessible by the current user, matching the provided filters.

        Default page size: 50. Max: 100.'
      operationId: api_chargehistory_get
      parameters:
      - name: InstallationId
        in: query
        schema:
          type: string
          format: uuid
      - name: UserId
        in: query
        schema:
          type: string
          format: uuid
      - name: ChargerId
        in: query
        schema:
          type: string
          format: uuid
      - name: From
        in: query
        schema:
          type: string
          format: date-time
      - name: To
        in: query
        schema:
          type: string
          format: date-time
      - name: GroupBy
        in: query
        description: '0 = group by charger (default), 1 = group by calendar day, 2 = group by user.


          0 = Charger


          1 = Day


          2 = User'
        schema:
          $ref: '#/components/schemas/AggregateGroup'
      - name: DetailLevel
        in: query
        description: 'Bitflag: 0 = session summary (default), 1 = include detailed session energy data.


          0 = Summary


          1 = EnergyDetails'
        schema:
          $ref: '#/components/schemas/DetailLevelFlags'
      - name: SortProperty
        in: query
        description: Name of the property used to sort the result.
        schema:
          type: string
      - name: SortDescending
        in: query
        description: Set to true to sort items in descending order.
        schema:
          type: boolean
      - name: PageSize
        in: query
        description: Number of items to return per page.
        schema:
          type: integer
          format: int32
      - name: PageIndex
        in: query
        description: The page index to return, first page is 0.
        schema:
          type: integer
          format: int32
      - name: IncludeDisabled
        in: query
        description: If true, and your user has access, include disabled objects.
        schema:
          type: boolean
      - name: Exclude
        in: query
        description: Get or set a list of item Id's that will be excluded from the result.
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: PageInfoOnly
        in: query
        description: Returns only information about pages and no data info.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/SessionListModelPagedData'
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListModelPagedData'
            text/json:
              schema:
                $ref: '#/components/schemas/SessionListModelPagedData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      deprecated: true
      security:
      - ory_auth: []
  /api/chargehistory/installationreport:
    get:
      tags:
      - ChargeHistory
      summary: Usage report (deprecated)
      description: '**Deprecated**: Use the POST version instead.

        Retrieves a usage report based on the provided filters (requires installation owner permissions).

        GET requests are limited to a 2048-character URL length and may fail if exceeded.

        `FromDate` and `EndDate` without an offset are read as wall-clock time in the installation''s time zone.

        With an offset or a `Z` suffix they are read as the instant they denote.'
      operationId: api_chargehistory_installationreport_get
      parameters:
      - name: FromDate
        in: query
        schema:
          type: string
          format: date-time
      - name: EndDate
        in: query
        schema:
          type: string
          format: date-time
      - name: InstallationId
        in: query
        schema:
          type: string
          format: uuid
      - name: UserIds
        in: query
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: ChargerIds
        in: query
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: GroupBy
        in: query
        description: '


          0 = User


          1 = Charger


          2 = ChargeCardName'
        schema:
          $ref: '#/components/schemas/GroupByOptions'
      - name: ReportFormat
        in: query
        description: '


          0 = Summary


          1 = Detailed'
        schema:
          $ref: '#/components/schemas/ReportFormatOptions'
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      deprecated: true
      security:
      - ory_auth: []
    post:
      tags:
      - ChargeHistory
      summary: Usage report
      description: 'Retrieves a usage report based on the provided filters (requires installation owner permissions).

        `FromDate` and `EndDate` without an offset are read as wall-clock time in the installation''s time zone.

        With an offset or a `Z` suffix they are read as the instant they denote.'
      operationId: api_chargehistory_installationreport_post
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/InstallationChargeHistoryModel'
          application/json:
            schema:
              $ref: '#/components/schemas/InstallationChargeHistoryModel'
          text/json:
            schema:
              $ref: '#/components/schemas/InstallationChargeHistoryModel'
          application/*+json:
            schema:
              $ref: '#/components/schemas/InstallationChargeHistoryModel'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CustomTotalChargerReportModel'
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTotalChargerReportModel'
            text/json:
              schema:
                $ref: '#/components/schemas/CustomTotalChargerReportModel'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - ory_auth: []
components:
  schemas:
    GroupByOptions:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: '


        0 = User


        1 = Charger


        2 = ChargeCardName'
      format: int32
      x-enumNames:
      - User
      - Charger
      - ChargeCardName
    DetailLevelFlags:
      enum:
      - 0
      - 1
      type: integer
      description: 'Determines the detail level to return.


        0 = Summary


        1 = EnergyDetails'
      format: int32
      x-enumNames:
      - Summary
      - EnergyDetails
      x-enumFlags: true
    ReportFormatOptions:
      enum:
      - 0
      - 1
      type: integer
      description: '


        0 = Summary


        1 = Detailed'
      format: int32
      x-enumNames:
      - Summary
      - Detailed
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    SessionListModelPagedData:
      type: object
      properties:
        pages:
          type: integer
          format: int32
        totalCount:
          type: integer
          description: Total number of rows across all pages.
          format: int32
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SessionListModel'
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
    CommitMetadata:
      enum:
      - 0
      - 1
      - 2
      - 4
      - 8
      - 16
      - 32
      - 64
      - 128
      type: integer
      description: '


        0 = None


        1 = Online


        2 = Offline


        4 = ReliableClock


        8 = StoppedByRFID


        16 = Signed


        32 = Void


        64 = Aborted


        128 = OcppNative'
      format: int32
      x-enumNames:
      - None
      - Online
      - Offline
      - ReliableClock
      - StoppedByRFID
      - Signed
      - Void
      - Aborted
      - OcppNative
      x-enumFlags: true
    CustomTotalChargerReportModel:
      type: object
      properties:
        installationName:
          type:
          - string
          - 'null'
        installationAddress:
          type:
          - string
          - 'null'
        installationZipCode:
          type:
          - string
          - 'null'
        installationCity:
          type:
          - string
          - 'null'
        installationTimeZone:
          type:
          - string
          - 'null'
        groupedBy:
          type:
          - string
          - 'null'
        fromdate:
          type: string
          format: date-time
        enddate:
          type: string
          format: date-time
        totalUserChargerReportModel:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TotalUserChargerReportModel'
      additionalProperties: false
    AggregateGroup:
      enum:
      - 0
      - 1
      - 2
      type: integer
      description: '0 = group by charger (default), 1 = group by calendar day, 2 = group by user.


        0 = Charger


        1 = Day


        2 = User'
      format: int32
      x-enumNames:
      - Charger
      - Day
      - User
    SessionEnergyDetailsModel:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        energy:
          type: number
          format: double
      additionalProperties: false
    InstallationChargeHistoryModel:
      type: object
      properties:
        fromDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        installationId:
          type:
          - string
          - 'null'
          format: uuid
        userIds:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
        chargerIds:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
        groupBy:
          $ref: '#/components/schemas/GroupByOptions'
        reportFormat:
          $ref: '#/components/schemas/ReportFormatOptions'
      additionalProperties: false
    SessionListModel:
      type: object
      properties:
        id:
          type: string
          description: Unique session identifier.
          format: uuid
        deviceId:
          type:
          - string
          - 'null'
          description: The serial number of the charging station.
        startDateTime:
          type: string
          description: "Session start time.\n\nTime of session authorization. Usually corresponds within a few seconds to the \nconnection time, but can in some cases be delayed if users does not authorize \nimmediately."
          format: date-time
        endDateTime:
          type:
          - string
          - 'null'
          description: "For chargers with firmware >= 3.2, this property indicates when the session was\nclosed by the cloud solution. For sessions recorded when the charging station was \nonline, this is usually identical to the time of disconnect. For offline sessions,\nthis is not the case as the session may be received by our backend a long time after\nthe actual charge took place. For charging stations with firmware >= 3.2 you\nshould use the Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.CommitEndDateTime to get the actual end time of the \nsession.\n\nFor charging stations with firmware < 3.2, this property indicates the time when \nthe session was closed. Please note that Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.StartDateTime, \nZaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.EndDateTime and Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.Energy may be inaccurate in some scenarios \nwhen using these firmware versions. For accurate session handling it is recommended \nto use firmware >= 3.2 and Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.CommitEndDateTime."
          format: date-time
        energy:
          type: number
          description: Energy delivered during the session in kWh.
          format: double
        commitMetadata:
          $ref: '#/components/schemas/CommitMetadata'
        commitEndDateTime:
          type:
          - string
          - 'null'
          description: 'This is only supported for charging stations with firmware >= 3.2 and indicates

            the actual end time of the session. In most cases equal to the time of disconnect.'
          format: date-time
        userFullName:
          type:
          - string
          - 'null'
          description: "The full name of the authorized user, or null if unauthorized or authorized by \n3rd party."
        chargerId:
          type:
          - string
          - 'null'
          description: The charge point unique identifier.
          format: uuid
        deviceName:
          type:
          - string
          - 'null'
          description: The charge point name.
        userEmail:
          type:
          - string
          - 'null'
          description: 'The email of the authorized user, or null if unauthorized or authorized by

            3rd party.'
        userId:
          type:
          - string
          - 'null'
          description: 'Get the unique identifier for the authorized user, or null if unauthorized or

            authorized by 3rd party.'
          format: uuid
        tokenName:
          type:
          - string
          - 'null'
          description: The RFID token used to authorize the session.
        externalId:
          type:
          - string
          - 'null'
          description: 'The external identifier for the session if authorized by 3rd party (e.g. transactionId

            from OCPP), or null if not authorized by 3rd party.'
        externallyEnded:
          type: boolean
          description: Indicates when the session was finalized with 3rd party.
        energyDetails:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SessionEnergyDetailsModel'
        chargerFirmwareVersion:
          type:
          - object
          - 'null'
          properties:
            Major:
              type: integer
              format: int32
            Minor:
              type: integer
              format: int32
            Build:
              type: integer
              format: int32
            Revision:
              type: integer
              format: int32
            MajorRevision:
              type: integer
              format: int32
            MinorRevision:
              type: integer
              format: int32
          description: "The firmware version of the charger at the time of execution, or null for legacy \nsessions executed before firmware version was tracked."
        signedSession:
          type:
          - string
          - 'null'
          description: An OCMF signed session for supported charging stations.
        signedSessionEichrecht:
          type:
          - string
          - 'null'
          description: An OCMF signed session in compliance with the German Eichrecht regulations.
        replacedBySessionId:
          type:
          - string
          - 'null'
          description: 'In some cases a session has to be corrected after it''s been created. Since session

            start is notified to 3rd parties when session is created, we need to replace sessions

            to correct this. This property indicates what session is replacing the current one.

            Replaced sessions will also be marked as Zaptec.ZapCloud.Domain.Entities.CommitMetadata.Void

            in Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.CommitMetadata, and will have no duration or energy.'
          format: uuid
        userUserName:
          type:
          - string
          - 'null'
          description: 'Property is deprecated and an alias for Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.UserEmail.

            Please use Zaptec.ZapCloud.WebAPI.Models.Sessions.SessionModel.UserEmail instead.'
          deprecated: true
      additionalProperties: false
    TotalUserChargerReportUserModel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type:
          - string
          - 'null'
        fullName:
          type:
          - string
          - 'null'
      additionalProperties: false
    TotalUserChargerReportModel:
      type: object
      properties:
        groupAsString:
          type:
          - string
          - 'null'
        userDetails:
          $ref: '#/components/schemas/TotalUserChargerReportUserModel'
        totalChargeSessionCount:
          type: number
          format: double
        totalChargeSessionEnergy:
          type: number
          format: double
        totalChargeSessionDuration:
          type: number
          format: double
      additionalProperties: false
  securitySchemes:
    ory_auth:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.zaptec.com/oauth/token
          scopes: {}