What you’ll learn

In this quickstart, you’ll learn:

• How to create a Bayou Energy account

• How to generate a key to be used in the API

• How to create customers through the API and then onboard them

• How to access your customers’ utility bill data

🍿 Before trying yourself, you can also watch the below video to preview the interactive quick start experience available once you’ve created an account.

1. Create your account on Bayou Energy

Visit the sign up page to create your company account and fill in the form. Your company color and logo are required, as they will appear on your onboarding form and will be visible to your users. Bayou provides two environments, Live and Test. For this Quickstart Guide, we will use the Test environment.

2. Create your API Key

After signing up, you will be redirected to your company dashboard. From there, visit your Settings page, and then click on the API Keys button. Or directly visit the API Keys page.

Click on “Generate a new key”. Your key is now ready to be used! Treat this key as you would any other password and save it somewhere safe, as it will be displayed only once.

You can revoke it at any time on the API Keys page.

3. Create your customers

We are now going to use curl to create a new customer and generate his onboarding link. Run the below command in your terminal. You will need to replace 20_4fe83........610 with the API Key you just generated, but please keep the “:” at the end of the command.

curl https://staging.bayou.energy/api/v1/customers -XPOST -H "Content-Type: application/json" --data '{"email": "m.scott@dundermifflin.com", "utility": "speculoos_power"}' -u 20_4fe83........610:

speculoos_power is the name of the fake utility we use at Bayou to allow our users to test their integration with our platform. It behaves like a real utility but generates only fake bills and can be controlled from your company dashboard.

If you want to test with a real utility, check out the list of possible values for this field on our API Documentation.

The command should return a JSON object similar to this one:

{
   “id”: 9999,
   “external_id”: null,
   “email”: “m.scott@dundermifflin.com”,
   “first_name”: null,
   “last_name”: null,
   “phone_number”: null,
   “address_line_1”: null,
   “address_line_2”: null,
   “city”: null,
   “state”: null,
   “zipcode”: null,
   “utility”: “speculoos_power”,
   “account_number”: null,
   “onboarding_link”: “https://staging.bayou.energy/companies/9999/onboard/4e14541f...0d2bc”,
   “has_accepted_terms_on”: null
}

The field named onboarding_link is the link that you can send to that customer. It allows the customer provide permission to share their utility account with you.

Let’s visit the onboarding link for the customer we just created and act as if we were them:

We land on the data sharing agreement page. After we accept the terms and click on Continue, we are invited to fill in our utility account credentials. As the customer was created with the speculoos_power utility, we are asked for those credentials.

Speculoos comes with the following set of valid fake credentials you can use at any time to test the platform:

Email: iamvalid@bayou.energy

Password: validpassword

Fill in those, submit the form and voilà! Your customer is now onboarded.

4. How to access your customers’ data

You can now create fake bills for that customer and retrieve them through our API.

Go back to your company dashboard, and then visit your Settings page. From there, click on Speculoos Power Administration Panel, or click on this link to access the page directly.

You should see the customer you just created on this page, because it is linked to the fake utility Speculoos Power.

Click on the customer to open the Bill Generation tool.

The form to create a new bill is pre-filled with default values. Once you are satisfied with the values for your new bill, click on “Create a fake bill”.

You will now be able to retrieve that bill through the API by running the following curl command. Don’t forget to replace 20_4fe83........610 with your API Key and 9999 with the customer id (you can retrieve it in the returned JSON from the command we used to create the customer).

curl https://staging.bayou.energy/api/v1/customers/9999/bills -u 20_4fe83........610:

Please visit the API documentation for more details about that API call.

The command should return a JSON array with objects representing bills similar to this one:

 [
   {
      “external_id”: null,
      “id”: 9999,
      “customer_id”: 9999,
      “customer_external_id”:null,
      “billed_on”: ”2022-10-11”,
      “past_due”: false,
      “outstanding_balance”: 0,
      “billing_period_from”: ”2022-08-01”,
      “billing_period_to”: ”2022-08-30”,
      “utility”: ”speculoos_power”,
      “account_number”: ”100000000000001”,
      “electricity_consumption”: 536,
      “delivery_charge”: 4030,
      “supply_charge”: 6040,
      “community_solar_bill_credit”: 5010,
      “total_amount”: 5060,
      “file_url”:”https://bayou-static-staging.s3.amazonaws.com/bill_files/utilities/static/sample_bill.pdf?AWSAccessKeyId=AKIA...&Expires=1665503456”
   }
]