A property is one of many that can be associated with a given Customer. A property is a construct at an individual ICP level (Installation Control Point) which uniquely identifies an address of consumption on the New Zealand power grid.

Prerequisites

Before you can follow this guide, you will need:

To be able to make a request in your programming language of choice, our API reference has example requests using multiple common languages and libraries, just look for the "Language" dropdown at the top of the page.
Your subscription key (32 alphanumerical combination key).

Supported Requests

Using your language of choice, make a GET request to the https://api.ahiko.io/customer/v1/customers/{customer_id}/properties endpoint, with the following headers:

Authorization: Bearer {{user access token}}
ahiko-app-id {{application subscription key}}

Where the {{application subscription key}} is replaced with your application subscription key.

Creating a Customers Property - POST

Used to create a customer's property consisting of 2 key pieces of information:

customer_id : string The unique identifier of the associated customer
icp : string The unique property identifier belonging to the customer

Any query will generate an associated response that will look like:

{
  "success": true,
  "data": {
    "customer_id": "customer_123456",
    "property_id": "property_78910"
  }
}

Let's break this response down:

customer_id : string The unique identifier of the associated customer
property_id : string The unique property identifier of the created property

Behind the scenes an engine will work to verify and enrich the ICP with the necessary ICP details. See more below leveraging the GET.

Getting a Customers Property - GET

Used to obtain a customer's property. The 2 key parameters required are:

customer_id : string The unique identifier of the associated customer
property_id : string The unique property identifier of the created property

Handling the Response

The Ahiko API returns standard HTTP response codes.
Below are the most common error codes and their reasons:

200 Everything is OK. The response is included in the body.
404 The url does not exist. Check you have entered the url correctly.
403 You are not allowed to access this resource. Make sure you have a valid user access token with the correct permissions. Also make sure you have set the Authorization header correctly (note the American spelling).

You should treat any response code that is greater than 399 as an error.

The Ahiko API uses JSON to encode responses. Most languages have libraries to encode and decode JSON.

Successful API Response

A successful API response will look like:

{
  "success": true,
  "data": {
    "customer_id": "customer_123456",
    "property_id": "property_78910",
    "icp": "0005834930RN094",
    "network_reporting_region": "17",
    "cache_smart_meter": true,
    "cache_meter_active": true,
    "property_lifecycle": "verified",
    "cache_flow_directions": [
      "injection",
      "extraction"
    ]
  }
}

Let's break this response down:

success is true. That means that the request was successful
data is the payload which contains a body of:
- customer_id : string The unique identifier of the associated customer
- property_id : string The unique property identifier of the created property
- icp : string The unique property icp
- network_reporting_region : string The unique property icp. Generated by the enrichment shortly after the property is created, if the property becomes verified.
- cache_smart_meter : string True or False if the property has a smart meter on site. Generated by the enrichment shortly after the property is created, if the property becomes verified.
- cache_meter_active : boolean True or False if the property has an active meter on site. Generated by the enrichment shortly after the property is created, if the property becomes verified.
- property_lifecycle : string (enum:[verified|unverified]) When you first create a property it's ICP and intelligence about it's ICP is unverified. A background engine connects to the Electricity Authority platform to enrich the property with the appropriate data.
- cache_flow_directions : list[string] (enum:[injection|extraction]) A list of at least 1 and at most 2 flow directions that indicates whether the energy is being extracted (traditional consumption) or injected (i.e. solar).

Attach Usage a Customer's Property - PATCH

Once you have uploaded a usage snapshot leveraging the usage API you can then associate it with a property by patching the property with the snapshot's usage id:

usage_snapshot_id : string

The associated response will look like:

{
  "success": true,
}

Attach Insight Plan Comparison to a Customer's Property - POST

When you have leverage the insight comparison API it will associate a comparison report with a property via this endpoint, you can also manually associate a comparison report by just calling this endpoint directly:

comparison_saga_id : string

The associated response will look like:

{
  "success": true,
  "data": {
    "customer_id": "customer_123456",
    "property_id": "property_78910",
    "comparison_saga_id": "comparison_saga_1234"
  }
}