Skip to main content
POST
/
invitation
/
company
/
{company_id}
Create Connection Invitation
curl --request POST \
  --url https://external.nectarclimate.com/v2/invitation/company/{company_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "allowedEmails": [
    "[email protected]"
  ],
  "expiresInSeconds": 61,
  "maxUses": 2,
  "sendEmail": false,
  "prefill": {
    "url": "<string>",
    "initialSites": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "utilityTypes": [
      "ELECTRICITY"
    ],
    "country": "AF",
    "connectionOwnerEmail": "[email protected]",
    "dataCollectionStartDate": "2023-12-25"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "token": "<string>",
  "invitationType": "<string>",
  "status": "<string>",
  "invitationUrl": "<string>",
  "companyId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "allowedEmails": [
    "[email protected]"
  ],
  "expiresAt": "2023-11-07T05:31:56Z",
  "maxUses": 123,
  "useCount": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "prefill": {
    "url": "<string>",
    "initialSites": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "utilityTypes": [
      "ELECTRICITY"
    ],
    "country": "AF",
    "connectionOwnerEmail": "[email protected]",
    "dataCollectionStartDate": "2023-12-25"
  },
  "createdConnections": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "datasourceName": "<string>",
      "status": "<string>",
      "created": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
company_id
string<uuid>
required

ID of the company to create the invitation for.

Body

Request body for creating an invitation that lets an external contributor connect a utility account.

​
allowedEmails
string<email>[]

Restrict the invitation to these email addresses. If empty, anyone with the link can use it. When set, the recipient must verify their email before proceeding.

Minimum string length: 1
​
expiresInSeconds
integer

Number of seconds until the invitation expires. Omit to create a non-expiring invitation.

Required range: x >= 60
​
maxUses
integer

Maximum number of times this invitation can be used to create a connection. Omit for unlimited uses.

Required range: x >= 1
​
sendEmail
boolean
default:false

If true and allowedEmails is non-empty, sends the invitation link to each email address. If false, the link is returned in the response for manual distribution.

​
prefill
object

Optional data to pre-populate in the connection form.

Response

An invitation that grants an external contributor access to create or update a connection.

​
id
string<uuid>
required

Unique identifier of the invitation.

​
token
string
required

Opaque token used in the invitation URL. This is the value embedded in invitationUrl.

​
invitationType
string
required

CREATE_CONNECTION — invitation to connect a new utility account. EDIT_CONNECTION — invitation to update credentials on an existing connection.

​
status
string
required

ACTIVE — can still be used. EXPIRED — past its expiration time. REVOKED — manually invalidated. FULFILLED — reached its maximum use count.

​
invitationUrl
string
required

Full URL to send to the recipient. Opening this link takes them to the connection form.

​
companyId
string<uuid>
required

The company this invitation belongs to.

​
connectionId
string<uuid> | null
required

For EDIT_CONNECTION invitations, the ID of the connection to update. Null for CREATE_CONNECTION invitations.

​
allowedEmails
string<email>[]
required

Email addresses allowed to use this invitation. Empty list means anyone with the link can use it.

​
expiresAt
string<date-time> | null
required

When the invitation expires. Null means it never expires.

​
maxUses
integer | null
required

Maximum number of times this invitation can be used. Null means unlimited.

​
useCount
integer
required

How many times this invitation has been used so far.

​
createdAt
string<date-time>
required

When the invitation was created.

​
prefill
object
required

Pre-populated form data for CREATE_CONNECTION invitations. Empty object for EDIT_CONNECTION invitations.

​
createdConnections
object[]
required

Connections that were created by recipients of this invitation. Only populated for CREATE_CONNECTION invitations; empty list for EDIT_CONNECTION.