Skip to main content
GET
/
connection
/
{connection_id}
/
details
Get an Utility Account Connection
curl --request GET \
  --url https://external.nectarclimate.com/v2/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",
  "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
}

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
connection_id
string<uuid>
required

ID of the connection to get.

Response

Serializer for Workflow instances with magic link.

This serializer extends the shared helper serializer to have a consisten schema with webhook paylods.

​
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

Public exposed ID of the company requesting the magic link. This ID may be exposed to unauthenticated users when displaying the magic link, so a seprate ID is used.

​
connectionMagicLinkSecret
string
required

Secret key used for magic link validation 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.

​
datasource
object

Datasource / utility provider associated with the connection.

​
accounts
object[]

List of site relations associated with the workflow and the account ids for those sites.

​
company
object

Company associated with the connection.

​
url
string | null

URL of the utility company's login website.

​
status
enum<string>

Current status of the workflow. See enum for more details.

  • 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
  • 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,
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.