Skip to main content
GET
/
connection
/
{connection_id}
/
details
Get an Utility Account Connection
curl --request GET \
  --url https://external.nectarclimate.com/v2.2/connection/{connection_id}/details \
  --header 'X-API-KEY: <api-key>'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "publicCompanyId": "<string>",
  "connectionMagicLinkSecret": "<string>",
  "statusLastUpdateTime": "2023-11-07T05:31:56Z",
  "statusFirstSeenTime": "2023-11-07T05:31:56Z",
  "statusErrorDetail": "<string>",
  "updated": "2023-11-07T05:31:56Z",
  "externalId": "<string>",
  "datasource": {
    "name": "<string>",
    "url": "<string>"
  },
  "accounts": [],
  "company": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "externalId": "<string>"
  },
  "url": "<string>",
  "status": "PENDING",
  "country": "AF",
  "initialSites": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "initialDatasourceTypes": [
    "ELECTRICITY"
  ],
  "username": "<string>",
  "workflowOwnerEmail": "[email protected]",
  "dataCollectionStartDate": "2023-12-25",
  "multiplyByOccupancy": true,
  "isActive": true
}

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.

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
connection_id
string<uuid>
required

ID of the connection to get.

Response

Utility account connection, including its current status and magic link secret for editing credentials.

​
id
string<uuid>
required

Unique identifier for the utility account connection.

​
created
string<date-time>
required

Timestamp when the utility account connection was created.

​
publicCompanyId
string
required

Deprecated — use the invitation system instead. Public ID of the company used in magic link URLs.

​
connectionMagicLinkSecret
string
required

Deprecated — use the invitation system instead. Fernet-encrypted secret for connection-level magic links.

​
statusLastUpdateTime
string<date-time> | null
required

When we recorded this status

​
statusFirstSeenTime
string<date-time> | null
required

When did we initially set this status

​
statusErrorDetail
string | null
required

Relevant details if it’s an error status

​
updated
string<date-time>

Timestamp when the utility account connection was last updated.

​
externalId
string | null

External identifier for the connection. Used to associate this connection in Nectar with a connection within your database.

​
datasource
object

Datasource / utility provider associated with the connection.

​
accounts
object[]

List of accounts associated with this connection, including which sites each account is linked to.

​
company
object

Company associated with the connection.

​
url
string | null

URL of the utility company's login website.

​
status
enum<string>

Observable connection status, read-only to API clients. DEACTIVATED means the connection has been deactivated via isActive=False. COMPANY_INACTIVE means the parent company was deactivated. All other values reflect the most recent scrape outcome. See the connection lifecycle docs for the full enum and what each value means.

  • PENDING - Pending
  • UNDER_INVESTIGATION - Under Investigation
  • CONNECTED - Connected
  • MFA_TOKEN_EXPIRED - Mfa Token Expired
  • PASSWORD_INCORRECT - Password Incorrect
  • NEW_PASSWORD_NEEDED - New Password Needed
  • ADDITIONAL_CREDENTIALS_NEEDED - Additional Credentials Needed
  • WEBSITE_DOWN - Website Down
  • NO_ACCOUNTS_FOUND - No Accounts Found
  • OTHER_ERROR - Other Error
  • COMPANY_INACTIVE - Company Inactive
  • DEACTIVATED - Deactivated
  • URL_INACCESSIBLE - Url Inaccessible
Available options:
PENDING,
UNDER_INVESTIGATION,
CONNECTED,
MFA_TOKEN_EXPIRED,
PASSWORD_INCORRECT,
NEW_PASSWORD_NEEDED,
ADDITIONAL_CREDENTIALS_NEEDED,
WEBSITE_DOWN,
NO_ACCOUNTS_FOUND,
OTHER_ERROR,
COMPANY_INACTIVE,
DEACTIVATED,
URL_INACCESSIBLE
​
country

Country of the utility company.

  • AF - Af
  • AL - Al
  • DZ - Dz
  • AS - As
  • AD - Ad
  • AO - Ao
  • AI - Ai
  • AQ - Aq
  • AG - Ag
  • AR - Ar
  • AM - Am
  • AW - Aw
  • AU - Au
  • AT - At
  • AZ - Az
  • BS - Bs
  • BH - Bh
  • BD - Bd
  • BB - Bb
  • BY - By
  • BE - Be
  • BZ - Bz
  • BJ - Bj
  • BM - Bm
  • BT - Bt
  • BO - Bo
  • BQ - Bq
  • BA - Ba
  • BW - Bw
  • BV - Bv
  • BR - Br
  • IO - Io
  • BN - Bn
  • BG - Bg
  • BF - Bf
  • BI - Bi
  • KH - Kh
  • CM - Cm
  • CA - Ca
  • CV - Cv
  • KY - Ky
  • CF - Cf
  • TD - Td
  • CL - Cl
  • CN - Cn
  • CX - Cx
  • CC - Cc
  • CO - Co
  • KM - Km
  • CG - Cg
  • CD - Cd
  • CK - Ck
  • CR - Cr
  • HR - Hr
  • CU - Cu
  • CW - Cw
  • CY - Cy
  • CZ - Cz
  • CI - Ci
  • DK - Dk
  • DJ - Dj
  • DM - Dm
  • DO - Do
  • EC - Ec
  • EG - Eg
  • SV - Sv
  • GQ - Gq
  • ER - Er
  • EE - Ee
  • ET - Et
  • FK - Fk
  • FO - Fo
  • FJ - Fj
  • FI - Fi
  • FR - Fr
  • GF - Gf
  • PF - Pf
  • TF - Tf
  • GA - Ga
  • GM - Gm
  • GE - Ge
  • DE - De
  • GH - Gh
  • GI - Gi
  • GR - Gr
  • GL - Gl
  • GD - Gd
  • GP - Gp
  • GU - Gu
  • GT - Gt
  • GG - Gg
  • GN - Gn
  • GW - Gw
  • GY - Gy
  • HT - Ht
  • HM - Hm
  • VA - Va
  • HN - Hn
  • HK - Hk
  • HU - Hu
  • IS - Is
  • IN - In
  • ID - Id
  • IR - Ir
  • IQ - Iq
  • IE - Ie
  • IM - Im
  • IL - Il
  • IT - It
  • JM - Jm
  • JP - Jp
  • JE - Je
  • JO - Jo
  • KZ - Kz
  • KE - Ke
  • KI - Ki
  • KP - Kp
  • KR - Kr
  • KW - Kw
  • KG - Kg
  • LA - La
  • LV - Lv
  • LB - Lb
  • LS - Ls
  • LR - Lr
  • LY - Ly
  • LI - Li
  • LT - Lt
  • LU - Lu
  • MO - Mo
  • MK - Mk
  • MG - Mg
  • MW - Mw
  • MY - My
  • MV - Mv
  • ML - Ml
  • MT - Mt
  • MH - Mh
  • MQ - Mq
  • MR - Mr
  • MU - Mu
  • YT - Yt
  • MX - Mx
  • FM - Fm
  • MD - Md
  • MC - Mc
  • MN - Mn
  • ME - Me
  • MS - Ms
  • MA - Ma
  • MZ - Mz
  • MM - Mm
  • NA - Na
  • NR - Nr
  • NP - Np
  • NL - Nl
  • NC - Nc
  • NZ - Nz
  • NI - Ni
  • NE - Ne
  • NG - Ng
  • NU - Nu
  • NF - Nf
  • MP - Mp
  • NO - No
  • OM - Om
  • PK - Pk
  • PW - Pw
  • PS - Ps
  • PA - Pa
  • PG - Pg
  • PY - Py
  • PE - Pe
  • PH - Ph
  • PN - Pn
  • PL - Pl
  • PT - Pt
  • PR - Pr
  • QA - Qa
  • RO - Ro
  • RU - Ru
  • RW - Rw
  • RE - Re
  • BL - Bl
  • SH - Sh
  • KN - Kn
  • LC - Lc
  • MF - Mf
  • PM - Pm
  • VC - Vc
  • WS - Ws
  • SM - Sm
  • ST - St
  • SA - Sa
  • SN - Sn
  • RS - Rs
  • SC - Sc
  • SL - Sl
  • SG - Sg
  • SX - Sx
  • SK - Sk
  • SI - Si
  • SB - Sb
  • SO - So
  • ZA - Za
  • GS - Gs
  • SS - Ss
  • ES - Es
  • LK - Lk
  • SD - Sd
  • SR - Sr
  • SJ - Sj
  • SZ - Sz
  • SE - Se
  • CH - Ch
  • SY - Sy
  • TW - Tw
  • TJ - Tj
  • TZ - Tz
  • TH - Th
  • TL - Tl
  • TG - Tg
  • TK - Tk
  • TO - To
  • TT - Tt
  • TN - Tn
  • TR - Tr
  • TM - Tm
  • TC - Tc
  • TV - Tv
  • UG - Ug
  • UA - Ua
  • AE - Ae
  • GB - Gb
  • US - Us
  • UM - Um
  • UY - Uy
  • UZ - Uz
  • VU - Vu
  • VE - Ve
  • VN - Vn
  • VG - Vg
  • VI - Vi
  • WF - Wf
  • EH - Eh
  • YE - Ye
  • ZM - Zm
  • ZW - Zw
  • AX - Ax
Available options:
AF,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
KH,
CM,
CA,
CV,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
HR,
CU,
CW,
CY,
CZ,
CI,
DK,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RO,
RU,
RW,
RE,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SZ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW,
AX
​
initialSites
string<uuid>[]

Initial sites associated with this connection. Initial sites are often useful to manually associate sites with the connection before the connection is validated or onboarded.

​
initialDatasourceTypes
enum<string>[]

Initial datasource types associated with this workflow. Initial datasource types are used to filter the workflows when the number of datasource types associated via accounts is 0.

Maximum array length: 10
  • ELECTRICITY - Electricity
  • GAS - Gas
  • WATER - Water
  • DISTRICT - District
  • WASTE - Waste
  • FUEL - Fuel
  • MISC - Misc
  • REFRIGERANT - Refrigerant
  • SOLAR - Solar
  • TELECOM - Telecom
Available options:
ELECTRICITY,
GAS,
WATER,
DISTRICT,
WASTE,
FUEL,
MISC,
REFRIGERANT,
SOLAR,
TELECOM
​
username
string | null

Username for the integration workflow.

​
workflowOwnerEmail
string<email> | null

Utility login / data owner email address. This person will receive notifications if data is missing or if the utility data connection is misconfigured.

​
dataCollectionStartDate
string<date> | null

Date when data collection for the workflow begins. This is the date from which Nectar will pull historical data. This field overrides the site and company level dataCollectionStartDate fields.

​
multiplyByOccupancy
boolean

Flag to indicate if data should be multiplied by occupancy.

​
isActive
boolean

Whether this connection is actively collecting data. When set to False, the connection stops collecting new data but all historical data is preserved, and the status field will reflect as DEACTIVATED. Set to True to reactivate data collection. This is the preferred way to deactivate a connection instead of deleting it.