> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meter organization

> How Nectar organizes meters, accounts, and sites for API consumers.

This guide explains how meters, accounts, and sites relate in the external data model.

***

## Entity hierarchy

```mermaid theme={null}
flowchart TD
    subgraph Collection
        Connection --> Account1[Account]
        Connection --> Account2[Account]
    end

    subgraph Organization
        Account1 --> Meter1[Meter]
        Account1 --> Meter2[Meter]
        Account2 --> Meter3[Meter]

        Site1[Site] --> Meter1
        Site1 --> Meter2
        Site2[Site] --> Meter3
    end

    subgraph Data
        Meter1 --> Usage1[UsageData]
        Meter2 --> Usage2[UsageData]
        Meter3 --> Usage3[UsageData]
    end
```

### Relationships

| Entity               | Related via | Cardinality |
| -------------------- | ----------- | ----------- |
| Connection → Account | Discovery   | 1:many      |
| Account → Meter      | Ownership   | 1:many      |
| Site → Meter         | Assignment  | 1:many      |
| Meter → UsageData    | Recording   | 1:many      |

***

## Meter matching algorithm

When a document is processed, Nectar associates extracted usage and charges with meter records using document evidence.

### Matching criteria priority

1. **Identifier alignment** — Highest-confidence association
2. **Normalized identifier handling** — Minor formatting differences are tolerated
3. **Address and account context** — Supplemental matching signals
4. **New meter creation** — Used when no existing meter can be confidently matched

### Configuration

Matching behavior is configurable by Nectar to improve consistency across utility formats and regions.

***

## Meter identifiers

Each meter can have multiple **identifiers** — typed key-value pairs that Nectar uses for bill matching and display. Identifiers are extracted from utility documents during processing and stored on the meter record.

### Identifier types

Identifiers are categorized by type. Common types include:

| Type              | Description                                     | Example           |
| ----------------- | ----------------------------------------------- | ----------------- |
| `METER`           | Physical meter serial number                    | MTR-A12345        |
| `ACCOUNT`         | Utility account number                          | 12345-678-9       |
| `POD`             | Point of Delivery (EU/UK)                       | IT001E12345678    |
| `NMI`             | National Meter Identifier (Australia)           | 6305000123        |
| `ESI`             | Electric Service Identifier (Texas)             | 10443720000000000 |
| `ELECTRIC_CHOICE` | Competitive retail electricity                  | 1234567890        |
| `PREMISE`         | Premise or service location                     | PREM-98765        |
| `MPR`             | Meter Point Reference (UK gas)                  | 1234567           |
| `ICP`             | Installation Control Point (New Zealand)        | 0001234567AB123   |
| `MIRN`            | Meter Installation Registration Number (AU gas) | 52100123456       |

### How identifiers are used

Identifiers serve two purposes:

1. **Bill matching** — When a document is processed, extracted identifier values are compared against identifiers stored on each meter in the company. The meter whose identifiers match the document is linked to the usage data. All extracted identifiers must be present on the meter, and any extra identifiers on the meter must appear somewhere in the document text.

2. **Display (Primary ID)** — The platform resolves a single identifier value to display for each meter using a priority system. This displayed value is called the **Primary ID**. The resolution checks account-level preferences first, then falls back to a standard type ordering (`METER` > `POD` > `ELECTRIC_CHOICE` > `PREMISE` > `SUBMETER` > `ESI` > `CHOICE_ID` > `SUB_ACCOUNT` > `ACCOUNT` > `SUMMARY_ACCOUNT` > `MPR` > `ICP` > `NMI` > `MIRN`), then any available identifier.

### Account identifier preferences

Each account can configure a **primary identifier type** and **secondary identifier type**. These control which identifier is displayed as the Primary ID for all meters under that account. For example, setting the primary identifier type to `ACCOUNT` means the account number is shown instead of the meter serial number.

***

## Account organization

### Account states

| Status          | Value                     | Analytics inclusion |
| --------------- | ------------------------- | ------------------- |
| **Detected**    | Discovered, not confirmed | Excluded            |
| **Onboarded**   | Confirmed and active      | Included            |
| **Old account** | Previously active         | Historical only     |
| **Duplicate**   | Linked to active account  | Excluded            |
| **Inactive**    | Manually deactivated      | Excluded            |

### Active account linking

When utility providers consolidate or restructure accounts, Nectar links related records so reporting reflects the primary active account.

Subaccounts link to the active account:

```mermaid theme={null}
flowchart LR
    SubAccount1[Sub-account A] --> ActiveAccount[Active Account]
    SubAccount2[Sub-account B] --> ActiveAccount
    ActiveAccount --> Meter[Meters]
```

In analytics and exports, this helps prevent duplicate counting.

***

## Site assignment

### Assignment methods

1. **Address matching** — During meter creation
2. **Account inheritance** — From account's other meters
3. **Manual assignment** — User-specified

### Multi-site accounts

An account can have meters at multiple sites. This commonly happens when a single utility login covers buildings at different addresses. Each meter is assigned to its own site based on address matching, while the account itself stays linked to the connection that discovered it.

```mermaid theme={null}
flowchart TD
    Account[Account #12345] --> MeterA[Meter A — Electricity]
    Account --> MeterB[Meter B — Electricity]
    MeterA --> SiteX[Site: 100 Main St]
    MeterB --> SiteY[Site: 200 Oak Ave]
```

In analytics and exports, each meter's data rolls up to its assigned site — not to the account's site.

### Unassigned meters

Meters without site assignments:

* Included in company-wide analytics
* Excluded from site-specific views
* Listed in "Unassigned" section

***

## Meter tracking flags

### Tracked

Controls inclusion in active analytics:

| State   | Meaning             | Analytics |
| ------- | ------------------- | --------- |
| `True`  | Actively monitored  | Included  |
| `False` | Historical/inactive | Excluded  |

### Duplicate

Marks duplicate meters:

Duplicates are excluded from active analytics to avoid double counting.

### Tags

Meters can be assigned **tags** — company-defined labels for filtering and organization. Tags are managed per company and can be assigned individually or in bulk. Each tag has an `id` and a `name`. The `tags` field on the meter response returns the list of assigned tags.

***

## Site archiving

Sites can be archived to stop future active reporting while preserving historical records.

### Archive behavior

When a site is archived:

* Site is considered archived
* Meters excluded from active analytics
* Bills after the date excluded from reporting
* Historical data preserved

***

## Duplicate handling

### Duplicate detection

Meters are marked as duplicate when:

* Same identifier appears multiple times
* Same service point covered by different connections

### Duplicate accounts

When accounts are duplicated:

* Mark one as the active primary account
* Set `duplicate` status on others
* Data flows through the active account

### Excluded contributors

In aggregation queries, these are excluded:

| Reason            | Query filter                                              |
| ----------------- | --------------------------------------------------------- |
| Untracked         | Excluded from active analytics                            |
| Duplicate meter   | Excluded to prevent double counting                       |
| Superseded bill   | Historical superseded versions ignored in current rollups |
| Duplicate account | Data reported through the active account                  |

***

## Implied metering

For sewer when not directly metered:
Nectar can derive sewer-related usage from available utility data, depending on company configuration.

### Creation logic

When enabled, derived values are created from relevant utility records and labeled accordingly.

### Marking

Implied records are flagged as implied in downstream reporting, so you can distinguish them from directly metered data in analytics and exports.

***

## Mirror sites

Mirror sites are used for data completeness estimation. When a site is configured with a mirror, it uses the mirror site's data as a proxy for missing periods. This is useful when a new site has no historical data but a similar building nearby can serve as a reasonable estimate until actual bills arrive.

***

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference">
    Explore the meter and account endpoints
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer-guide/webhooks">
    Get notified when meters are created
  </Card>
</CardGroup>