Flip Energy API
    Flip Energy API
    • Overview
    • Important concepts
    • Authentication
    • Enrollment process
    • End-user app design
    • Monitoring / Telemetry
    • Control
    • Change log
    • Mobile App API
      • Devices
        • Create Device
        • Read Devices
        • Read Device
        • Update Device
        • Delete Device
      • Enrollments
        • Create Enrollment
        • Read Enrollments
        • Read Enrollment
        • Delete Enrollment
      • Events
        • Read Events
        • Read Event
        • Update Event Participation
      • Programs
        • Read Programs
        • Read Program
      • Sites
        • Read Site
        • Update Site
    • Cloud API
      • Sites
        • Get Site Token
        • Get Sites
      • Commissioning
        • Commission Site And Devices
      • Sessions
        • Sessions
      • Commands
        • Command Created
        • Update Command Status
      • Programs
        • Read Programs
      • Telemetry
        • Report Battery Telemetry
      • Webhooks
        • Overview
        • List of events
        • Webhook headers
        • Schemas
          • Command
          • Enrollment
          • Event

    End-user app design

    There are three ways you can enable end-users to manage their participation in VPPs:
    1.
    [Recommended] Embed our frameless whitelabel portal into your monitoring app;
    2.
    Build the UX directly into your existing monitoring app by leveraging our API;
    3.
    Use your pre-built whitelabel portal.
    In all cases, the site and device need to be commissioned before we can start working with them. Read on about the commissioning process.

    Commissioning#

    Commissioning is how you create the site and device in our systems.
    As part of your existing equipment commissioning process, you should add a call to our API to commission the equipment on our servers as well.
    To do so, from your cloud, call POST /v1/commission with the site and device info. The response will contain information about which programs the device is eligible to participate in, and, if the device can be automatically enrolled, information about the newly created enrollment.
    You do not need to add steps to the installer-facing commissioning flow. You simply need to add a backend process that forward the information you already have to Flip. In addition, note that all site fields are optional for this phase, and any missing information will be collected later.
    INFO
    About auto enrolling
    The ability to auto enroll homeowners in programs is limited to those programs that permit it. In addition, the homeowner should have previously agreed to be enrolled, for instance by agreeing to Terms & Conditions that describe that this may happen.

    Option 1: Embed our whitelabel portal#

    A great compromise between option 1 and 2, this approach lets you embed our pre-built whitelabel portal into your app. So you can control the branding while keeping integration work to a minimum. You do not need to separately commission the site and device with this option.

    How it works#

    We'll give you a unique URL to add as an iframe or WebView into your app. Add the following parameters to log in a specific user:
    NameDescription
    tokenA session token obtained by calling POST /v1/sessions
    The path will be /auth/session_token. So for example the iframe URL might be https://<your-custom-subdomain>.flip.energy/auth/session_token?token={token}

    Available Branding Parameters#

    The following parameters can be configured to tailor the app's appearance:
    alwaysShowBackButton: Determines whether the back button is always visible. By default, the back button is shown on mobile and hidden on desktop. When set to true, the back button is displayed on both mobile and desktop platforms.
    faviconFileName: Custom favicon displayed in the browser tab.
    fontName: Primary font used throughout the app.
    logoFileName: logo displayed in the app header.
    primaryButtonBackgroundColor: Background color for primary action buttons.
    primaryButtonBorderColor: Border color for primary action buttons.
    primaryButtonTextColor: Text color for primary action buttons.
    primaryTextColor: Default text color used in the app.
    secondaryButtonBackgroundColor: Background color for secondary action buttons.
    secondaryButtonBorderColor: Border color for secondary action buttons.
    secondaryButtonTextColor: Text color for secondary action buttons.
    secondaryTextColor: Secondary text color used in the app.
    If you would like to customize any of those, please ask the Flip team.

    Option 2: Build it yourself#

    You can use our Mobile App API in order to build a custom VPP management flow within your monitoring app. We recommend the following design.
    TIP
    Our API was designed for you to use it as a backend. In this respect, you don't need to copy any of the data we return in your own database.

    VPP tab#

    TIP
    From then on, and for all the API endpoints mentioned below, you can use site tokens.
    The VPP experience should be self-contained in a dedicated tab. Optionally you may decide to hide the tab if the homeowner does not actively participate in any VPPs and their utility does not offer any.
    In order to check if the homeowner is currently enrolled in a VPP, call GET /v1/site/{siteId}/enrollments with the site ID. If the response contains enrollment info, the user is enrolled and you should display the Manage enrollment flow.
    If there are no enrollments, you can check for programs. In order to do so, call GET /v1/site/{siteId}/programs with the homeowner's zip code and device type. If the response contains program info, programs are available and you should display the Program enrollment flow.
    TIP
    During testing, you can use zip codes 88801 and 88802 to fetch test programs. 88803 is an example of no results.

    Program enrollment#

    In this flow, you will want to display a list of the available programs and their descriptions. Allow users to tap on each program to display all their info. At the bottom of the info page, add an Enroll button.
    When they tap Enroll, you should call the POST /v1/site/{siteId}/enrollments endpoint with the site, program and appropriate device IDs. The enrollment will be set as PENDING, which could take a few days depending on the program. In the meantime, users should be given an option to cancel their enrollment via DEL /v1/site/{siteId}/enrollments/{id}.
    WARNING
    Prior to being able to enroll a homeowner, the site info needs to be provided to our system. Ideally, this would be done by the installer in the commissioning phase. If this wasn't done, you will need to give homeowners a way to enter the info manually and then submit it to PATCH /v1/sites/{id}.

    Manage enrollment#

    Once a homeowner has an enrollment in the ACTIVE state, they are officially enrolled in a program. They should be able to do the following:
    see past and upcoming events
    update their participation in current and upcoming events
    unenroll entirely from the program

    See past and upcoming events#

    All events can be found using the GET /v1/site/{siteId}/events endpoint.

    Update participation in current and upcoming events#

    When an event is in the IN_PROGRESS or UPCOMING state, users have the option to change their participation. They can either opt-out of the event, or update their reserve level, just for this event. To do so, use the PATCH /v1/site/{siteId}/event/{id} endpoint. If the event-specific reserve level in unset, it will default to that set by the program first, or otherwise the one set by the user.

    Unenroll entirely from the program#

    If the homeowner decides to, they should be able to unenroll from the program using DEL /v1/site/{siteId}/enrollments/{id}. Note that some programs have minimum time commitments, and therefore unenrollment might fail. Conversedly, they might be able to unenroll, but might be charged a penalty by the utility.

    Option 3: Use our standalone whitelabel portal#

    We've pre-built the entire experience in such a way that you can customize it with your own branding and domain. Logging in users works via oAuth 2.0. Please reach out if you'd like to use this option.
    Previous
    Enrollment process
    Next
    Monitoring / Telemetry
    Built with