Connection invitations

For platform users: See Invitations to understand the end-user experience.

Connection invitations replace the legacy Magic link integration. Invitations are the recommended path for all new integrations — they are database-backed, revocable, auditable, and support scoped email access. The magic-link endpoints are still available for backward compatibility but are marked deprecated in the OpenAPI spec.

Connection invitations let you expose Nectar’s utility connection UI to your end users. They handle multi-factor authentication and complex login workflows that can’t be completed through a basic API call — and unlike magic links, every invitation is tracked in Nectar’s database and can be revoked, expired, or scoped to specific email addresses.

How it works

Your server calls the Nectar API to create an invitation. The response includes an invitationUrl.
You share the URL with your end user — by email, in an embedded iframe, or as a direct link.
The user completes the connection flow (or credential update) through Nectar’s hosted UI.
Nectar maintains secure access to the utility account and continuously collects bills and usage data.
Your server receives connection.created.v2 and connection.updated.v2 webhook events as the connection progresses.

Each invitation is a row in Nectar’s database, so you can list, inspect, revoke, and audit them at any time.

Invitation types

Type	Purpose	Endpoint
Contributor	Create a new connection for a company	`POST /invitation/company/{company_id}`
Reconnect	Update credentials on an existing connection	`POST /invitation/connection/{connection_id}`

Both return an invitationUrl you can share with the recipient.

Create a contributor invitation

Use this when you want an external contributor to create a new utility connection.

Create the invitation

Call the create-invitation endpoint for the target company. The response contains invitationUrl and the invitation id.

curl -X POST 'https://external.nectarclimate.com/v2.2/invitation/company/{companyId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "allowedEmails": ["[email protected]"],
    "expiresInSeconds": 604800,
    "maxUses": 1,
    "sendEmail": true,
    "prefill": {
      "url": "https://www.coned.com",
      "country": "US",
      "initialSites": ["{siteId}"],
      "utilityTypes": ["ELECTRICITY"],
      "connectionOwnerEmail": "[email protected]"
    }
  }'

Key fields:

Field	Description
`allowedEmails`	Optional. If set, only these addresses can complete the invitation (email gate).
`expiresInSeconds`	Optional. When the invitation stops being usable. Omit for no expiration.
`maxUses`	Optional. Cap the number of times the invitation can be redeemed. Omit for unlimited.
`sendEmail`	If `true`, Nectar emails each address in `allowedEmails` with a pre-verified link.
`prefill`	Optional. Pre-fill the provider (by `datasourceId` or `url`), country, sites, utility types, owner email, and start date.

Share the invitation URL

The response’s invitationUrl follows this shape:

https://dash.nectarclimate.com/p/i/{token}

Share it however you like — in your own emails, chat, or an iframe in your product.

The /p/i/ prefix indicates a public (unauthenticated) page. The token is an opaque database-backed identifier — no encrypted payload is exposed in the URL.

Embed in an iframe (optional)

Display the invitation inside your product. Nectar’s connection UI currently requires desktop-sized dimensions.

<iframe
  src="https://dash.nectarclimate.com/p/i/{token}"
  width="1152"
  height="648"
  style="border: 0;"
></iframe>

Create a reconnect invitation

Use this when an existing connection enters an error state (PASSWORD_INCORRECT, MFA_TOKEN_EXPIRED, NEW_PASSWORD_NEEDED, etc.) and you want the account owner to update credentials or refresh MFA forwarding.

For MFA_TOKEN_EXPIRED, the reconnect wizard opens the MFA setup flow — not the password screen. It lets the end customer pick from the MFA recommendation ladder (upload bills, disable MFA on the portal, or configure one of the forwarding strategies). The shareable one-pager in MFA integration is written for end customers and can be forwarded directly.

Create the reconnect invitation

Call the reconnect endpoint for the existing connection.

curl -X POST 'https://external.nectarclimate.com/v2.2/invitation/connection/{connectionId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "allowedEmails": ["[email protected]"],
    "expiresInSeconds": 604800,
    "sendEmail": true
  }'

Share the reconnect URL

The returned invitationUrl uses the same /p/i/{token} format as contributor invitations. The recipient lands on the edit-credentials flow for the existing connection — all historical data, account mappings, and site associations are preserved.

Listing, inspecting, and revoking

# List connection invitations for a company (filter by status and type)
GET /v2.2/invitation/company/{company_id}?status=ACTIVE

# Get full detail for a single invitation, including the activity log
GET /v2.2/invitation/{invitation_id}

# Revoke an active invitation (idempotent)
POST /v2.2/invitation/{invitation_id}/revoke

Invitation statuses:

Status	Meaning
`ACTIVE`	The invitation can still be redeemed.
`EXPIRED`	Past `expiresAt`. The recipient sees an “expired” message.
`REVOKED`	Explicitly revoked by your team or via `/revoke`.
`FULFILLED`	All permitted uses have been consumed (`useCount == maxUses`).

The detail endpoint returns an event log — every view, email verification, and submission — so you can audit what happened with each invitation.

Prefilling data

The prefill object on contributor invitations supports:

Field	Description
`datasourceId`	UUID of a utility provider in the Nectar catalog. Locks the recipient to that provider. Discover IDs with `GET /v2.2/datasource`. Mutually exclusive with `url`.
`url`	Utility portal URL to preselect in the wizard. Use when the provider isn’t in the catalog. Mutually exclusive with `datasourceId`.
`country`	ISO country code (e.g., `US`, `GB`).
`initialSites`	Array of site UUIDs to pre-associate with the resulting connection.
`utilityTypes`	Array of commodity types (`ELECTRICITY`, `GAS`, `WATER`, `WASTE`, `FUEL`, …).
`connectionOwnerEmail`	Owner email used for notifications on the resulting connection.
`dataCollectionStartDate`	ISO date for how far back to collect bills.

Prefill data is stored in the invitation record and used to pre-populate the connection form — your recipient sees the values already filled in but can still change them.

Prefer datasourceId when the provider already exists in Nectar’s catalog — it guarantees the recipient lands on the correct provider configuration (including any MFA handling Nectar has set up for that utility). Fall back to url only when the provider isn’t in the catalog.

Find a datasource ID

Use the datasource search endpoint to look up a provider by name or URL. It returns a paginated list of { id, name, url } entries — pass id as prefill.datasourceId when creating an invitation.

curl -G 'https://external.nectarclimate.com/v2.2/datasource' \
  -H 'X-API-Key: YOUR_SECRET_KEY' \
  --data-urlencode 'search=coned'

Query parameters:

Parameter	Description
`search`	Optional. Case-insensitive substring match against the provider name or URL.
`page`	Optional. Page number (default `1`).
`pageSize`	Optional. Items per page (default `100`, max `500`).

If you can’t find a provider you expect to see, contact [email protected] — we can add it to the catalog.

Migration from magic links

If you have an existing integration using magic links, switch the endpoints you call — the embed pattern on the page is unchanged.

Legacy magic-link endpoint	Invitation replacement
`POST /connection/company/{company_id}/link`	`POST /invitation/company/{company_id}`
`POST /connection/{connection_id}` (edit link)	`POST /invitation/connection/{connection_id}`
(no equivalent — revocation not supported)	`POST /invitation/{invitation_id}/revoke`
(no equivalent — list not supported)	`GET /invitation/company/{company_id}`
(no equivalent — detail + events not supported)	`GET /invitation/{invitation_id}`

The old response magicLinkUrl is replaced with invitationUrl on the invitation responses. URLs now use https://dash.nectarclimate.com/p/i/{token} instead of the legacy p/connect/... path. Existing magic links continue to work — you do not need to migrate live links, only the endpoints your server calls when creating new links.

Customization

Nectar supports white-label branding of the invitation iframe, including custom fonts, colors, and language localization. See the White-label documentation or contact [email protected] for setup details.

Security

Invitation tokens are opaque random identifiers stored in Nectar’s database — they contain no payload and cannot be decoded. Authorization decisions (is it still active? is this email allowed?) happen server-side on every request, which is why revocation takes effect immediately.

Email gate. When allowedEmails is set, the recipient must verify ownership of one of those addresses (via a one-click email link) before the invitation is redeemable.
Expiration. expiresAt is enforced server-side.
Max uses. maxUses is enforced atomically; concurrent redemptions don’t race.
Audit trail. Every view, email verification, and submission is logged and surfaced on the invitation detail endpoint.

Next steps

MFA integration

Decision tree for MFA-protected utility accounts.

Webhooks

Get notified when a connection is created or updated.

Connection statuses

Understand the connection lifecycle.

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

How it works

Invitation types

Create a contributor invitation

Create a reconnect invitation

Listing, inspecting, and revoking

Prefilling data

Find a datasource ID

Migration from magic links

Customization

Security

Next steps

MFA integration

Webhooks

Connection statuses

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

​How it works

​Invitation types

​Create a contributor invitation

​Create a reconnect invitation

​Listing, inspecting, and revoking

​Prefilling data

​Find a datasource ID

​Migration from magic links

​Customization

​Security

​Next steps

MFA integration

Webhooks

Connection statuses

How it works

Invitation types

Create a contributor invitation

Create a reconnect invitation

Listing, inspecting, and revoking

Prefilling data

Find a datasource ID

Migration from magic links

Customization

Security

Next steps