Skip to main content
POST
/
connection
/
company
/
{company_id}
Create Basic Utility Account Connection
curl --request POST \
  --url https://external.nectarclimate.com/v2/connection/company/{company_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "url": "<string>",
  "username": "<string>",
  "password": "<string>",
  "sites": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "country": "AF",
  "workflowOwnerEmail": "[email protected]",
  "dataCollectionStartDate": "2023-12-25",
  "securityQuestions": [
    {}
  ]
}
'
[
  {
    "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

​
company_id
string<uuid>
required

ID of the company to retrieve utility account connections for.

Body

Serializer for Workflow instances for basic account connection.

​
url
string
required

Web address of the utility company's website. This page may be either the homepage or the login page for the utility company. This is where the integration will attempt to authenticate.

Required string length: 1 - 5000
​
username
string
required

Username for the utility account connection. This is used to authenticate with the utility provider.

Required string length: 1 - 200
​
password
string
required

Password for the utility account connection. This is used to authenticate with the utility provider. It will be encrypted before storage and never exposed publicly.

Required string length: 1 - 200
​
sites
string<uuid>[]
required

List of site UUIDs associated with the utility account connection. At least one site is required.

​
country
enum<string>
required

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

​
securityQuestions
object[] | null

Optional list of security questions and answers for the utility account connection. Format: [{"key": "", "value": ""}]. This is used to authenticate with utility providers that require security questions.

Response

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