Changelog
Start typing to search…
Back to All

Welcome to Nectar v2.0

23 days ago by Allen Wang

Announcement of v2.0

We're excited to announce v2.0 of our API! Over the past months, we've listened to numerous requests, suggestions, and complaints from you all. Leveraging the learnings from these conversations, we've released a new version of our API. We are grateful to all of our supporters and customers who helped us get here!

The general themes of v2.0 are control and visibility. You will have greater control over what data is collected, how it is collected, and how it is organized. Previously, data was organized under companies and sites. Now they will also be organized under connections and a new object called meters. UsageData from utility invoices will not only be matched with a site, but also a meter whenever possible.

Think of meters as your typical electricity meter. It's at a location. It tracks a specific resource, has readings, and units. Each month a meter will produce a usageData point which is captured by Nectar. When we start organizing data by meters, we can more easily detect irregularities in data, provide more accurate location insights, and detect data gaps trivially.

The second major change was the introduction of jobs as a separate API resource. Previously, jobs was part of the document API endpoints and provided some visibility into the status of a document processing job. Now we're extending jobs to mean any asynchronous data job in Nectar, including automated ones from connected online accounts. So you'll have visibility into when your data is next being refreshed and also the documents you've uploaded. Currently, the jobs endpoint only returns document upload jobs, and we're working to extend its functionality.

V1.0 of the API will reach end of life on June 15th, 2025. So we encourage you to move to v2.0 as soon as possible to avoid any interruptions in service. If you need help with the migration, please feel free to reach out to me personally at [email protected].

Migration guide

The root URL for v2.0 of the API is https://external.nectarclimate.com/v2. After June 15th, 2025, the default external URL https://external.nectarclimate.com will become an alias of the v2.0 root.

Changes to the usageData endpoint

Major changes include additional endpoints, the introduction of identifiers objects and moving document level fields into the document subobject. Utility specific fields no longer exist in subobjects like electricityFields or waterFields and are instead flattened in the usageData object.

  • We use the term usageData instead of the more verbose meterSiteUsageData
  • Document level fields moved to a document subobject. E.g.auditTrailUrl -> document.auditTrailUrl, documentSourceType -> document.sourceType, utilityCompany -> document.utilityCompany, documentDate -> document.billDate, processedDate -> document.created, documentNotes -> document.notes, isFlagged -> document.isFlagged, totalDocumentCharges -> totalCharges.
  • Site level fields moved to a site subobject. E.g. siteId-> site.id, siteExternalId -> site.externalId, siteName -> site.name, siteAddress -> site.address
  • accountId, meterId, icp, podId, shopNumber etc. replace by identifiers
  • Addition of the meter object reference. Meter can then be used to get account level information, and fields like isTracked and accountIsTracked
  • Subobjects for datasourceType specific fields like electricityFields and waterFields have been flattened into the usageData object

Changes to the document endpoints

The document object remains largely the same. Previously, several document level fields were repeated. They were present at the document level and also at the document.meterSiteUsageData field level. Document fields remain only at the parent level. usageData field is now the updated usageData object as described above. Line items are now within the document

  • lineItems used to have its own endpoint. Now they appear with the rest of the metered data in the document
  • document uses the new usageData object. usageData.documentis not present due to redundancy.

Reorganization of jobs and document submission

Jobs have been reorganized to be its own section.

Webhooks

If you're using webhooks, there is a new version of v2.0 webhooks compatible with our new object definitions. Please review the webhooks guide and events in v2.0.

What else to look forward to v2.0

We've already paved the way for some exciting ideas ahead. With a new way of organizing data we hope to provide more valuable insights in the data directly through the API. Some of the potential ideas on the road map are listed below:

  • Better job tracking and immediate job triggering. e.g. an API endpoint to immediately trigger a refresh of data / historical data pull
  • Endpoints to allow for more strong control of meters, e.g. relating meters with identical identifiers to unify supply and delivery contracts
  • Programatic endpoint to generate phone numbers / emails to help with 2fa connections
  • Endpoints to expose data gaps and anomalies
  • More fine grained statuses for connections beyond the basic ones like PASSWORD_INCORRECT.

If you have any further questions or comments, please reach out to our team at [email protected].