> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with the API

> Authenticate, make your first request, and understand Nectar's data model.

<Tip>
  **For platform users**: See the [Getting Started guide](/platform/getting-started) for an
  introduction to the Nectar dashboard and core concepts.
</Tip>

## 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.

<Steps>
  <Step title="Open API keys">
    Go to **Settings > Organization > API Keys**.
  </Step>

  <Step title="Create key">
    Click **Create key**, then add a descriptive name (for example, `prod-sync-service` or
    `sandbox-integration-tests`).
  </Step>

  <Step title="Choose environment">
    Select **Sandbox** for testing or **Production** for live customer data.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## Make your first request

<Steps>
  <Step title="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](/developer-guide/api-versions) 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](/developer-guide/connection-invitations).
  </Step>

  <Step title="Test your API key">
    Verify your key is active by calling the **Ping** endpoint.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET 'https://external.nectarclimate.com/v2.2/ping' \
        -H 'X-API-Key: YOUR_SECRET_KEY'
      ```

      ```python Python theme={null}
      import requests

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

    A `200 OK` response confirms your key is valid.
  </Step>

  <Step title="List your companies">
    Retrieve all companies associated with your API key.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET 'https://external.nectarclimate.com/v2.2/company' \
        -H 'X-API-Key: YOUR_SECRET_KEY'
      ```

      ```python Python theme={null}
      import requests

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

    The response is an array of company objects.

    ```json Example response theme={null}
    [
      {
        "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](/developer-guide/pagination).
  </Step>
</Steps>

## 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

<Steps>
  <Step title="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.json`

    Postman generates a collection with all endpoints pre-populated.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Send a request">
    Open the **Ping** request and click **Send**. A `200 OK` confirms your key works.
  </Step>
</Steps>

### Use Swagger UI

Paste any schema URL into [Swagger Editor](https://editor.swagger.io) or [Swagger UI](https://petstore.swagger.io) 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:

```json 401 Unauthorized theme={null}
{
  "detail": "Authentication credentials were not provided."
}
```

```json 403 Forbidden theme={null}
{
  "detail": "You do not have permission to perform this action."
}
```

```json 400 Bad Request theme={null}
{
  "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](/api-reference).

| 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](/api-reference).

| 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](/api-reference).

| 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](/api-reference).

| 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](/api-reference).

| 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 [support@nectarclimate.com](mailto:support@nectarclimate.com) if the issue persists |
| `502` | Bad Gateway — request timed out (exceeded 10 seconds)                                                             |
| `503` | Service Unavailable — temporarily offline for maintenance                                                         |

## Next steps

<CardGroup cols={3}>
  <Card title="Developer guide home" icon="book-open" href="/developer-guide/for-developers">
    Recommended docs order for integration implementation
  </Card>

  <Card title="Sandbox testing" icon="flask" href="/developer-guide/sandbox-testing">
    Test with mock utility accounts and sample data
  </Card>

  <Card title="Connection invitations" icon="paper-plane" href="/developer-guide/connection-invitations">
    Embed Nectar's connection UI in your app
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer-guide/webhooks">
    Subscribe to real-time events for connections and data
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/developer-guide/pagination">
    Iterate through paginated API responses
  </Card>

  <Card title="Document upload" icon="file-arrow-up" href="/developer-guide/document-upload">
    Upload bills for processing via the API
  </Card>
</CardGroup>