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

# Sandbox testing

> Test the Nectar API with sandboxed utility accounts and mock data.

<Tip>
  **For platform users**: You can also create sandboxed connections through the [connection
  wizard](/platform/data-input/connection-wizard) in the dashboard.
</Tip>

To help your team get familiar with the API and data models, Nectar provides a sandboxed utility account that generates mock data on connection. The examples below use **v2.2**, which is recommended for all new integrations.

## Sandbox credentials

Use the following credentials when creating a sandbox connection. Any other username/password combination will result in an `INCORRECT_PASSWORD` status.

| Field                | Value                                        |
| -------------------- | -------------------------------------------- |
| Utility provider URL | `https://nectarclimate.com`                  |
| Username             | `nectar-sandbox-username`                    |
| Password             | `nectar-sandbox-password`                    |
| Sites                | An array of site IDs (at least 1, at most 3) |
| Country              | `US` (or any two-letter country code)        |

## Create a sandboxed connection

<Steps>
  <Step title="Create a company (if needed)">
    If you don't already have a company, create one via the API. You'll need the company `id` for subsequent requests.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://external.nectarclimate.com/v2.2/company' \
        -H 'X-API-Key: YOUR_SECRET_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "name": "Sandbox Test Company",
          "externalId": "sandbox-test-001"
        }'
      ```

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

      response = requests.post(
          "https://external.nectarclimate.com/v2.2/company",
          headers={
              "X-API-Key": "YOUR_SECRET_KEY",
              "Content-Type": "application/json",
          },
          json={
              "name": "Sandbox Test Company",
              "externalId": "sandbox-test-001",
          },
      )
      company = response.json()
      print(company["id"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Create sites">
    Create at least one site under your company. The site `id` is required when creating the connection.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://external.nectarclimate.com/v2.2/company/{companyId}/site' \
        -H 'X-API-Key: YOUR_SECRET_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "name": "Test Facility",
          "address": "123 Main St, San Francisco, CA 94105",
          "externalId": "site-001"
        }'
      ```

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

      response = requests.post(
          f"https://external.nectarclimate.com/v2.2/company/{company_id}/site",
          headers={
              "X-API-Key": "YOUR_SECRET_KEY",
              "Content-Type": "application/json",
          },
          json={
              "name": "Test Facility",
              "address": "123 Main St, San Francisco, CA 94105",
              "externalId": "site-001",
          },
      )
      site = response.json()
      print(site["id"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Create the sandbox connection">
    Create a utility connection using the sandbox credentials. Since the sandbox uses basic username/password authentication, it can be connected directly via the API.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://external.nectarclimate.com/v2.2/company/{companyId}/connection' \
        -H 'X-API-Key: YOUR_SECRET_KEY' \
        -H 'Content-Type: application/json' \
        -d '{
          "url": "https://nectarclimate.com",
          "username": "nectar-sandbox-username",
          "password": "nectar-sandbox-password",
          "sites": ["{siteId}"]
        }'
      ```

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

      response = requests.post(
          f"https://external.nectarclimate.com/v2.2/company/{company_id}/connection",
          headers={
              "X-API-Key": "YOUR_SECRET_KEY",
              "Content-Type": "application/json",
          },
          json={
              "url": "https://nectarclimate.com",
              "username": "nectar-sandbox-username",
              "password": "nectar-sandbox-password",
              "sites": [site_id],
          },
      )
      connection = response.json()
      print(connection["id"], connection["status"])
      ```
    </CodeGroup>

    The response returns the connection `id` and validated `status`. You can look up all connections for a company at any time via `GET /company/{companyId}/connection`.
  </Step>

  <Step title="Query the generated data">
    Once connected with valid sandbox credentials, sample documents and usage data are populated asynchronously (up to 30 seconds). Query the data using the connection ID.

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

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

      response = requests.get(
          f"https://external.nectarclimate.com/v2.2/company/{company_id}/connection/{connection_id}/document",
          headers={"X-API-Key": "YOUR_SECRET_KEY"},
      )
      documents = response.json()
      print(documents)
      ```
    </CodeGroup>
  </Step>
</Steps>

## Using sandbox with invitations

The sandbox account can also be connected via a [connection invitation](/developer-guide/connection-invitations). After creating an invitation through the API, use `https://nectarclimate.com` as the utility provider URL when prompted, then enter the sandbox credentials above.

This is useful for testing the full end-user connection flow in your application. See [Connection invitations](/developer-guide/connection-invitations) for instructions on creating and embedding invitations.

## Next steps

<CardGroup cols={3}>
  <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">
    Get notified when connections and data change
  </Card>

  <Card title="Connection statuses" icon="circle-info" href="/developer-guide/connection-statuses">
    Understand connection lifecycle states
  </Card>
</CardGroup>