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 a separate Nectar-signed secret passed as a URL parameter — see the Magic link integration cookbook.

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'

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'

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.

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
`datasource`	The utility provider for the connection
`status`	Connection status (e.g., `CONNECTED`, `INCORRECT_PASSWORD`)
`publicCompanyId`	Public company ID used for magic link integration
`connectionMagicLinkSecret`	Nectar-signed secret for magic link integration

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 — contact support 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

Sandbox testing

Test with mock utility accounts and sample data

Magic link integration

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

Error responses

Rate limiting

Data model reference

Company

Site

Connection

Document

UsageData

Error codes

Next steps

Developer guide home

Sandbox testing

Magic link integration

Webhooks

Pagination

Document upload

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

​Prerequisites

​API key setup in Settings

​Make your first request

​Error responses

​Rate limiting

​Data model reference

​Company

​Site

​Connection

​Document

​UsageData

​Error codes

​Next steps

Developer guide home

Sandbox testing

Magic link integration

Webhooks

Pagination

Document upload

Prerequisites

API key setup in Settings

Make your first request

Error responses

Rate limiting

Data model reference

Company

Site

Connection

Document

UsageData

Error codes

Next steps