Getting started with the API

For platform users: See the Getting Started guide for an introduction to the Nectar dashboard and core concepts.

Prerequisites

A valid Nectar API key created in Settings > Organization > API Keys

API key setup in Settings

Create your API key from the Nectar dashboard before making requests.

Open API keys

Go to Settings > Organization > API Keys.

Create key

Click Create key, then add a descriptive name (for example, prod-sync-service or sandbox-integration-tests).

Choose environment

Select Sandbox for testing or Production for live customer data.

Copy and store the secret

The key value is shown once. Copy it immediately to your secret manager. Do not commit it to source control or share it in chat/email.

Rotate keys safely by creating a new key, deploying it, validating traffic, and only then deleting the old key.

Make your first request

Set up authentication

All API requests require the X-API-Key header with your secret key.

API version	Base URL	Status
v2.2	`https://external.nectarclimate.com/v2.2`	Recommended for new integrations
v2.1	`https://external.nectarclimate.com/v2.1`	Supported
v2.0	`https://external.nectarclimate.com/v2`	Supported for legacy integrations

For all new integrations, start on v2.2. See API version differences for migration details.Secret keys are always passed as a request header. Iframe integrations use an opaque invitation token in the URL — see Connection invitations.

Test your API key

Verify your key is active by calling the Ping endpoint.

curl -X GET 'https://external.nectarclimate.com/v2.2/ping' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

import requests

response = requests.get(
    "https://external.nectarclimate.com/v2.2/ping",
    headers={"X-API-Key": "YOUR_SECRET_KEY"},
)
print(response.json())

A 200 OK response confirms your key is valid.

List your companies

Retrieve all companies associated with your API key.

curl -X GET 'https://external.nectarclimate.com/v2.2/company' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

import requests

response = requests.get(
    "https://external.nectarclimate.com/v2.2/company",
    headers={"X-API-Key": "YOUR_SECRET_KEY"},
)
companies = response.json()
print(companies)

The response is an array of company objects.

Example response

[
  {
    "id": "91c21c6b-5f3f-4d5f-9fb9-02530ef4b13c",
    "name": "Greenfield Motors",
    "externalId": "gm-001"
  },
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Metro Health System",
    "externalId": null
  }
]

Each company contains sites, connections, and documents. See the data model below for the full hierarchy. Other endpoints like documents and usage data return paginated responses.

Explore the API with Postman or Swagger

You can import the Nectar OpenAPI schema directly into any OpenAPI-compatible client such as Postman, Insomnia, or Swagger UI to browse endpoints, read request and response schemas, and send test requests without writing code.

Download the schema

API version	Schema URL	Status
v2.2	`https://docs.nectarclimate.com/api-reference/openapi-v2-2.json`	Recommended for new integrations
v2.1	`https://docs.nectarclimate.com/api-reference/openapi-v2-1.json`	Supported
v2.0	`https://docs.nectarclimate.com/api-reference/openapi-v2.json`	Supported for legacy integrations

Start with v2.2 for any new integration.

Import into Postman

Open Postman and import the schema

In Postman, click Import, then paste the v2.2 schema URL: https://docs.nectarclimate.com/api-reference/openapi-v2-2.jsonPostman generates a collection with all endpoints pre-populated.

Add your API key

In the generated collection, open Variables and set X-API-Key to your secret key. Alternatively, add it as a collection-level header under Authorization.

Send a request

Open the Ping request and click Send. A 200 OK confirms your key works.

Use Swagger UI

Paste any schema URL into Swagger Editor or Swagger UI to browse the full endpoint reference interactively in your browser. You can also use the API Reference tab in these docs to explore all endpoints.

Use Insomnia

In Insomnia, click Create > Import, choose From URL, and paste the schema URL. Set the X-API-Key header on the collection’s environment before sending requests.

Error responses

When a request fails, the API returns a JSON error body with a detail field:

401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

400 Bad Request

{
  "detail": "Invalid input.",
  "errors": {
    "name": ["This field is required."]
  }
}

Rate limiting

The Nectar API does not currently enforce hard rate limits. However, you should design your integration to handle 429 Too Many Requests responses gracefully — if the API ever returns a 429, wait and retry with exponential backoff. As a best practice, avoid sending more than 10 concurrent requests.

Data model reference

Each API key is associated with a collection of Company objects. The hierarchy flows from Company down through Sites, Connections, Documents, and UsageData.

Company

A Company is the top-level entity associated with multiple Sites. Each company can have configurations that control how much historical data to process and what types of data to collect. See the Companies API.

Key field	Description
`externalId`	String identifier you set via the API to map the company to your own system

Site

A Site represents a physical address associated with a Company. Each site can have multiple connections, documents, and usage data records. The address must be accurate — Nectar matches processed data to the site with the closest address. See the Sites API.

Key field	Description
`externalId`	String identifier you set via the API to map the site to your own system
`address`	Complete address including state and zip code (Nectar can process unstructured text addresses)

Connection

A Connection represents a secure integration between Nectar and a utility provider. A single connection can cover multiple data types (e.g., Electricity and Gas) and meters across different sites. Nectar identifies providers by their website root URLs. See the Utility Account Connections API.

Key field	Description
`externalId`	String identifier you set via the API to map the connection to your own system
`datasource`	The utility provider for the connection
`status`	Connection status (e.g., `CONNECTED`, `INCORRECT_PASSWORD`)
`publicCompanyId`	Public company ID (used by legacy magic link integrations)
`connectionMagicLinkSecret`	Nectar-signed secret (used by legacy magic link integrations)

Document

A Document represents a processed invoice or utility bill, with associated UsageData and LineItems. Documents are automatically downloaded from connected accounts on a regular basis. PDFs and PNGs can also be submitted for processing via the document upload endpoint. See the Documents API.

Key field	Description
`usageData`	Meters and utility usage records
`auditTrailUrl`	Link to an auditable data trail on the Nectar dashboard
`url`	Pre-signed S3 URL of the raw document (expires in 24 hours)
`lineItems`	Individual line items on the document

UsageData

UsageData contains utility consumption data for a specific meter over a specific time period, ultimately associated with a Site. UsageData can be queried by company, sites, or connection. The API also supports filtering by date range and utility type. See the Usage Data API.

Key field	Description
`site`	ID of the site the usage is recorded for
`identifiers`	Account ID, meter ID, electric choice ID, etc.
`usage`	Consumption value present on the bill
`usageUnits`	Units of the usage value

Error codes

The Nectar API returns standard HTTP status codes.

Code	Description
`200`	OK — request was successful
`201`	Created — object was created and saved
`204`	No Content — object was deleted successfully
`400`	Bad Request — request could not be parsed or is invalid
`401`	Unauthorized — API key is missing or incorrect
`403`	Forbidden — resource is restricted or does not exist
`404`	Not Found — resource does not exist
`429`	Too Many Requests — rate limit exceeded, try again later
`500`	Internal Server Error — email [email protected] if the issue persists
`502`	Bad Gateway — request timed out (exceeded 10 seconds)
`503`	Service Unavailable — temporarily offline for maintenance

Next steps

Developer guide home

Recommended docs order for integration implementation

Sandbox testing

Test with mock utility accounts and sample data

Connection invitations

Embed Nectar’s connection UI in your app

Webhooks

Subscribe to real-time events for connections and data

Pagination

Iterate through paginated API responses

Document upload

Upload bills for processing via the API

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Prerequisites

API key setup in Settings

Make your first request

Explore the API with Postman or Swagger

Download the schema

Import into Postman

Use Swagger UI

Use Insomnia

Error responses

Rate limiting

Data model reference

Company

Site

Connection

Document

UsageData

Error codes

Next steps

Developer guide home

Sandbox testing

Connection invitations

Webhooks

Pagination

Document upload

​Prerequisites

​API key setup in Settings

​Make your first request

​Explore the API with Postman or Swagger

​Download the schema

​Import into Postman

​Use Swagger UI

​Use Insomnia

​Error responses

​Rate limiting

​Data model reference

​Company

​Site

​Connection

​Document

​UsageData

​Error codes

​Next steps

Developer guide home

Sandbox testing

Connection invitations

Webhooks

Pagination

Document upload

Prerequisites

API key setup in Settings

Make your first request

Explore the API with Postman or Swagger

Download the schema

Import into Postman

Use Swagger UI

Use Insomnia

Error responses

Rate limiting

Data model reference

Company

Site

Connection

Document

UsageData

Error codes

Next steps