Guides

Creating your first hosted consent

Learn how to add support for hosted consents into your application

Suggest Edits

🧑‍🍳

Recipes

Want something copy-paste-able? Check out the recipes below!

🏙️
Creating a UK Hosted Consent (Commercial)
Open Recipe
🏠
Creating a UK Hosted Consent (Residential)
Open Recipe

On the previous page we showed you an example use case that outlined three important steps in bold:

  1. You create a customer on Openvolt using the users information.
  2. You create a hosted consent on Openvolt and re-direct the user to the provided consent link.
  3. The user is prompted for all of the required information for the given consent flow and on completion is sent back to your application.
  4. You can then use this hosted consent to create meters on Openvolt to start accessing meter data on behalf of the user.

Customers

To create a hosted consent, we require you to have created a customer on Openvolt.

As Openvolt has no knowledge of your application and how you manage your customers, we require you to create a customer in Openvolt that can be used to represent a customer/user in your application. You can then use this customer to create hosted consents (and meters) on their behalf.

📘

Creating a customer

Check our out API docs to learn how to create customers.

https://docs.openvolt.com/reference/post_customers

Creating the consent

Once you have created a customer, you can use their customer id to create a hosted consent. Hosted consents have four pieces of required information:

  • customer_id
  • expiry
  • redirect_url
  • flow_type

Expiry

All consents must expire. We give you the ability to set the expiry date when creating a consent. We then use this expiry date when determining whether or not we should retrieve data for a given meter. given meter.

Note that in some countries/regions, regulations require that expiry dates cannot exceed a certain length of time (for example one year into the future). Where this is the case you will not be able to set an expiry date beyond the maximum limit.

Redirect URL

The redirect url is the URL you wish to see users redirected back to when they have completed the hosted consent flow, this should be a link back to your application where your user can complete their consent journey.

Flow Type

The Flow Type refers to the consent workflow that you will need the user to complete in order to access their smart meter data. This workflow will vary depending on the country in which the meter is located, the source of the data as well as whether the meter is in a commercial or residential premises. It’s important that you select the correct Flow Type, as failing to do so will mean Openvolt will be unable to retrieve the user’s smart meter data.

The current supported flow types are:

  • gb.commercial.blanket (Use this for UK commercial smart meters)
  • gb.residential.specific (Use this for UK residential smart meters)

Walkthrough

So let's create our hosted consent! In this instance we already have a customer and we want to create a UK residential consent - meaning this is typically the consent flow an individual would complete to authorise access to their home smart meter.

curl --request POST \
     --url https://api.openvolt.com/v1/hosted-consents \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <API KEY REDACTED>' \
     --data '
{
  "flow_type": "gb.domestic.specific",
  "customer_id": "659d5e5a01e72bc7add89a1e",
  "expiry": "2024-12-7",
  "redirect_url": "https://carboncanary.io"
}
'

This request give us the following response:

{
  "success": true,
  "data": {
    "object": "hosted-consent",
    "account": "6509cb067b832a3ac25ae02c",
    "customer": "659d5e5a01e72bc7add89a1e",
    "expiry": "2024-12-07T00:00:00.000Z",
    "redirect_url": "https://carboncanary.io",
    "flow_type": "gb.domestic.specific",
    "consentee_email_verified": false,
    "meter_numbers": [],
    "token": "a6c4683d-f7c8-4c4a-8569-33408f1a611c",
    "created_at": "2024-04-22T16:51:52.570Z",
    "hosted_consent_link": "https://consent.openvolt.com/662695a8241615b969377029?t=a6c4683d-f7c8-4c4a-8569-33408f1a611c",
    "valid": false,
    "id": "662695a8241615b969377029"
  }
}

Hosted Consent Link

The hosted_consent_link field will contain a URL you can use to redirect a customer to complete a hosted consent. When a user is directed to this link they will see the appropriate hosted consent flow (determined by the selected flow_type). In the example above we specified a UK Residential Consent Flow. When the user loads the URL they will see something similar to the following below (note, you can customize with your app’s brand colours and logo)

Approving a consent

After completing the consent flow, the user will be redirected back to your application. In the example above, the user would be returned to the redirect_url provided, which includes a consent_id URL parameter:

https://carboncanary.io/?consent_id=662695a8241615b969377029`

You should query the Openvolt api with the provided consent_id to retrieve details about it. Using the same example as above, we can query the returned consent_id to get information about its validity.

curl --request GET \
     --url https://api.openvolt.com/v1/hosted-consents/662695a8241615b969377029 \
     --header 'accept: application/json' \
     --header 'x-api-key: <API KEY REDACTED>'

{
  "object": "hosted-consent",
  "account": {
    // Account Information in here
  },
  "customer": {
    // Customer Information in here
  },
  "expiry": "2024-12-07T00:00:00.000Z",
  "redirect_url": "https://carboncanary.io",
  "flow_type": "gb.domestic.specific",
  "consentee_email_verified": false,
  "meter_numbers": [
    "11111111111"
  ],
  "token": "a6c4683d-f7c8-4c4a-8569-33408f1a611c",
  "created_at": "2024-04-22T16:51:52.570Z",
  "contextual_data": {
    "address": "23, HARDEAN COURT, RETFORD, DN25 8AB",
    "address_identifier": "23",
    "postcode": "DN25 8AB",
    "occupation_months": ">13",
    "found_mpan": "11111111111"
  },
  "consent_method": "digital-consent",
  "consentee_email": "[email protected]",
  "consentee_full_name": "Thomas Freeborough",
  "consented_at": "2024-04-22T17:26:35.307Z",
  "hosted_consent_version": "0.0.4",
  "updated_at": "2024-04-22T17:26:35.307Z",
  "hosted_consent_link": "https://consent.openvolt.com/662695a8241615b969377029?t=a6c4683d-f7c8-4c4a-8569-33408f1a611c",
  "valid": true,
  "id": "662695a8241615b969377029"
}

We would like to highlight a few properties on the hosted consent that could be useful to you.

valid

Indicates if this hosted consent can be attached to a meter. A hosted consent is considered valid if it has been completed AND has not expired or been revoked.

consented_at

A timestamp of the date + time in which the consent flow user approved this consent

meter_numbers

If you are creating a consent flow that captures specific meter numbers, they will be present here as an array of strings. You will only be allowed to attach this consent to a meter that is included in the meter_numbers field on the consent.

contextual_data

The contents of contextual data will vary depending on the flow_type that was chosen, but this can often include raw information that was collected as part of the consent flow which may be useful for your application. In the case above we collected the address that the user entered as part of the UK residential flow.

Attaching a consent to a meter

To attach a consent to a meter, all you need to do is simply call the meter create/update endpoint and pass the consent's id as hosted_consent_id. We will check you can assign this consent to the meter, and on success, we can begin the process of retrieving meter data for you.

curl --request PUT \
     --url https://api.openvolt.com/v1/meters/64106fcd8946e00aeaa8509f \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <API KEY REDACTED>' \
     --data '
{
  "hosted_consent_id": "662695a8241615b969377029"
}
'

Updated 8 months ago