Start here
Use this order for the fastest implementation path:- Get your API key
- Make your first API request
- Run sandbox testing
- Implement webhooks
- Add magic link integration (optional)
- Use API Reference for endpoint details
API key setup in Settings
Create keys in Settings > Organization > API Keys.Recommended key setup
| Environment | Recommendation | Why |
|---|---|---|
| Sandbox | Create one key per test app/integration | Isolate test traffic and avoid shared-secret confusion |
| Production | Create separate keys per service | Safer rotation and scoped blast radius |
Rotation without downtime
Choose your API version
| Version | Status | Guidance |
|---|---|---|
| v2.2 | Recommended | Use this for all new integrations |
| v2.1 | Supported | Maintain existing integrations, plan migration |
| v2.0 | Legacy support | Use only for older integrations that cannot migrate yet |
Common implementation tracks
API getting started
Authentication, first request, and data model basics.
Sandbox testing
Validate behavior with non-production data and workflows.
Webhooks
Build event-driven synchronization with signature verification.
Magic link integration
Embed Nectar connection flows in your product experience.
Related pages
- Data model overview — understand the relationships between companies, sites, accounts, meters, and bills
- Connection statuses — handle connection lifecycle events in your integration
- Methodology — how Nectar processes, calendarizes, and attributes bill data
- Getting started (platform) — platform walkthrough for non-developer users on your team
Developer FAQ
My API call returns 401. What should I check first?
My API call returns 401. What should I check first?
Confirm the
X-API-Key header is present, your key is active, and you are using the correct
environment key (sandbox vs production).How do I test that a key is valid quickly?
How do I test that a key is valid quickly?
Call
/ping on your target API version. A 200 response confirms the key is accepted.What causes 403 or 404 when authentication is valid?
What causes 403 or 404 when authentication is valid?
Usually scope, object visibility, or incorrect resource identifiers. Verify the company context
and object IDs your integration is requesting.
What should I do for webhook retries and idempotency?
What should I do for webhook retries and idempotency?
Treat webhook deliveries as at-least-once and build idempotent handlers keyed by event ID. Retry
transient failures and log processed IDs.
How should I handle expired magic links?
How should I handle expired magic links?
Detect expiry in your UI flow and request a freshly generated link from your backend before
retrying the embedded session.