Getting started

Prerequisites

To get started, make sure that you've completed the following requested a valid API key from the Nectar platform with a paid or sandboxed account.

How we recommend you start

1. Start by reading this document to understand key concepts in Nectar's data schema and API authentication.
2. Make sure you have a functional API key by testing the Ping Test Endpoint.
3. Find your use case in the guides
   1. Connect and access your customers' utility connections (coming soon)
   2. Submit utility documents to Nectar for processing (coming soon)

If you choose to not follow the guide, you'll need to use the API to create a company and its associated sites first. Then you can connect utility accounts or use Nectar's Sandboxed Utility Accounts. Finally, query the data using the Usage Data API or the Documents API.

For any further questions, please check the full API Documentation or get in touch with us at [email protected]. We're happy to help.

Data models and schema

Each API key corresponds to a user in the Nectar database. For most API users (carbon accounting platforms and environmental consultants), this key is provisioned to one user and used by your entire team. Each key is associated with a collection of company objects. And each company has a list of sites which corresponds to facilities. And each facility can have a number of utility connection objects. Finally utility data is stored in our database under documents. Each document can have a number of line items or meters stored in meterSiteUsageData objects. The API documentation documents how to read, create, update, and delete objects of each type.

Company

A Company represents an organization and is associated with multiple Site objects. Each company can have various configurations that control how much historical data to process and what types of data to process. Each company has an external id that can be set to help in the integration process (e.g. to associate a company in the Nectar API with an account in your climate software solution). See Companies API.

Key Fields: externalId string identifier set by you via the API to associate company with an external id or name, relevantDataTypes - list of data types allowed for the company (e.g. Electricity, Water).

Site

A Site represents a facility or location associated with a company. Each site can have multiple utility connections, documents, and meterSiteUsageData associated with it. Each site has an external id that can be set to help in the integration process to associate it with a site in your database. Importantly, the address of a site needs to be accurate since data that is processed on Nectar is associated with the site with the address that is the closest match. See Sites API.

Key Fields: externalId - string identifier set by you via the API to associate site with an external id or name,
address: complete string address of the location including state and zipcode (Nectar can process unstructured text addresses).

Connection

A Connection (Utility Connection) represents a secure integration between Nectar and a utility provider. Each connection is associated with a list of data types and sites (e.g. a single utility account can be for both Electricity and Gas, and it can contain meters from different sites). Note that Nectar identifies utility providers by their website root urls. From the utility company's home or login url, Nectar extracts the root and searches for the closest match. See Utility Account Connections API.

Key Fields: datasource: the utility provider for the connection, status: status of the connection (e.g. connected, incorrect_password, etc.), publicCompanyId: the public company id field used for magic link integration, connectionMagicLinkSecret: the Nectar signed secret containing information about the utility connection used for magic link integration.

Document

The Document model represents an invoice or document processed, capturing detailed utility data in associated MeterSiteUsageData. Documents are automatically downloaded from connected utility connections on a regular basis. Pdf and png documents can also be submitted to Nectar for processing via the Submit Document Endpoint. When documents are uploaded, they are processed asynchronously and their status can be tracked via the Get Job Status Endpoint. See more in the Documents API.

Key Fields: meterSiteUsageData - associated line items or meters and utility usage, auditTrailUrl - link to an auditable data trail on dash.nectarclimate.com, url: publicly accessible pre-signed s3 url of the raw document that expires in 24 hours, processedDate - date the document was successfully processed by Nectar.

MeterSiteUsageData

Exactly what the name says: the MeterSiteUsageData model contains utility data for a specific meter over a specific time period, which is ultimately associated with a site. Like Documents, MeterSiteUsageData can be queried by their associated company, sites, or utility connection in the Usage Data API. The API also allows filtering by dates and utility types.

Key Fields: siteId - the id of the site that the usage is recorded for, accountId - the account id for this meter provisioned by the utility company, usage - the usage for the utility present on the bill, usageUnits - the units of the usage present.

Root URL

Nectar external API’s root URL is https://external.nectarclimate.com/. To test your API key, make your first request using the ping endpoint.

curl --location --request GET 'https://external.nectarclimate.com/ping' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'

Authorization

On your Nectar Settings page, you can find your api keys in the integration section. To activate your API key you'll need to contact a member of our team at [email protected].

Requests made to external.nectarclimate.com to fetch up-to-date utility data require <YOUR_SECRET_KEY>. Iframe integrations require a nectar signed secret to validate the authenticity of the request. Secret keys will always be passed through headers, while nectar signed secrets will be passed as url params.

The API secret key needs to be in a header of the form: X-API-Key: <YOUR_SECRET_KEY>.

Errors

The Nectar API returns standard HTTP error codes.