Silicon Valley Clean Energy

Description: Silicon Valley Clean Energy (SVCE) is a Community Choice Aggregation (CCA) utility in the California bay area.

Website: https://data.svcleanenergy.org/

Utility ID: SVCE (this is the utility identifier you use in our API)

In order for you to request data from SVCE customers, you must register with SVCE as a third party company.

As part of their Innovation Onramp program, SVCE is using UtilityAPI's EE/DER Engagement Platform to allow third-party companies to request data access from SVCE customers. Authorizations use the Green Button OAuth process, which means that third-parties have to be pre-registered with SVCE so they can be assigned a client_id.

NOTE: When you register, you will be automatically put into "sandbox" mode. This means you can only request data from test accounts, not real SVCE customers. After you register, SVCE will review your registration and switch you to "live" mode (you will get an email when this happens).

After registering with SVCE as a third party, to request authorizations from SVCE customers and test accounts, you can use any of these methods:

Once a customer has authorized, you will see an Authorization appear on your dashboard and via both our JSON API and Green Button API.

When your first register as a third party, your registration status is set to Sandbox mode. This means you can only request data from test accounts, so you can try it out or start building an integration, but real customers won't be able to authorize data sharing with you yet. SVCE will review your registration, then you'll get an email letting you know that you can now switch your status to Live mode in your settings.

During the OAuth authorization flow, we offer multiple ways that customers can look up their SVCE account. To make things smoother for the customer, you can pre-fill these lookup identifiers (phone number, email, etc.) in the OAuth scope string if you already know it. We'll automatically try to find that user using your provided information so they can skip the lookup step of authentication and go directly to the OTP sending step. If we can't find that user automatically given your prefilled value, we'll fall back using the default authentication flow.

Scope parameter format:
auth-{type}[-{value}]

Full scope string example with authentication option (percent encoded):
scope=FB%3D4_16_51%3BAdditionalScope%3Dauth-phone-1111111111

Type Can Have Value? Description Scope String Example
account Yes Try to lookup the customer via their utility account number. auth-account-111111111-1
phone Yes Try to lookup the customer via the phone number they have on file at the utility. auth-phone-111-111-1111
account Yes Try to lookup the customer via the email they have on file at the utility. auth-email-uapi-test-residential%40example.com
address Yes Try to lookup the customer via their utility billing address. auth-address-333%20W%20EL%20CAMINO%20REAL%20STE%20600%2C%20SUNNYVALE%20CA%2094087

The SVCE OAuth authorization flow doesn't use usernames or passwords by default. Instead it asks the user to lookup their account via some identifier (e.g. phone number, address, etc.), then sends them a One-Time-Passcode (OTP) to verify their identity.

That means you can't use UtilityAPI's default test usernames to manually simulate a test scenario. Instead, below we have created test identifiers so you can simulate authorizing as an SVCE user under various test scenarios.

When you use these test identifiers, we won't actually send an OTP. Instead we will display it directly on the authentication page so you can enter it while you're testing. If you'd like to see what the sent OTP messages look like, use the OTP Testing guide.

Try one with your SVCE data share link
(you aren't logged into an account that has a registered SVCE client)

Phone Number Equivalent Test Scenario Description
111-111-1111 residential A residential customer with 1 electric meter and 1 gas meter.
222-222-2222 commercial A commercial customer with 4 electric meters and 1 gas meter.
333-333-3333 badlogin Simulate error where we couldn't find that customer.
Email Address Equivalent Test Scenario Description
uapi-test-residential@example.com residential A residential customer with 1 electric meter and 1 gas meter.
uapi-test-commercial@example.com commercial A commercial customer with 4 electric meters and 1 gas meter.
uapi-test-badlogin@example.com badlogin Simulate error where we couldn't find that customer.
Physical Address Equivalent Test Scenario Description
333 W EL CAMINO REAL STE 600, SUNNYVALE CA 94087 residential A residential customer with 1 electric meter and 1 gas meter.
333 W EL CAMINO REAL STE 700, SUNNYVALE CA 94087 commercial A commercial customer with 4 electric meters and 1 gas meter.
333 W EL CAMINO REAL STE 800, SUNNYVALE CA 94087 badlogin Simulate error where we couldn't find that customer.
Account Number Equivalent Test Scenario Description
111111111-1 residential A residential customer with 1 electric meter and 1 gas meter.
222222222-2 commercial A commercial customer with 4 electric meters and 1 gas meter.
333333333-3 badlogin Simulate error where we couldn't find that customer.

If you want to send a one-time passcode to a real phone number or email to see what it looks like, you can prefix a special string to your phone number or email during lookup time and we'll set that number as the test scenario's OTP contact method. NOTE: These are intended for manual testing and not for automated testing (since they will really send an OTP), so please use our test credentials or the /test-submit API for automated tests.

Format Equivalent Test Scenario Description
TEST_residential_<your_phone_number>
TEST_residential_<your_email>
residential A residential customer with 1 electric meter and 1 gas meter.
TEST_commercial_<your_phone_number>
TEST_commercial_<your_email>
commercial A commercial customer with 4 electric meters and 1 gas meter.
TEST_badlogin_<your_phone_number>
TEST_badlogin_<your_email>
badlogin Simulate error where we couldn't find that customer.

To demonstrate how you can integrate the GBC OAuth authorization process into your apps and websites, we offer a demo third party website that can be configured with any GBC client, so long as it has a specific redirect_uri added. We have also created public, sandbox-only GBC clients that you can try out (see table below).

Client ID Company Name Pre-configured Demo Link
SVCE_ccccccccc Test Company Link