Platform Documentation

Integrations connect NEQTO.ai to external APIs and brokers. NEQTO.ai opens the connection using the service URL and credentials you provide. A pull integration brings data into NEQTO.ai, while a push integration sends data out. Custom integrations support TLS-secured HTTPS, WSS, and MQTTS connections.

Where to find integrations

Open Integrations from the account navigation or from an application’s sidebar. The default application shows every integration in the account. A non-default application shows only the integrations linked to it. You also need the appropriate View Integrations permission for that account or application.

Create a custom integration

A Custom integration is the one you configure yourself. Its wizard walks five screens: Type, Protocol, Credentials, Settings, and Verify.

• 1
  Open Integrations and select the + (Add Integration) button. On the Type screen, choose Custom to enter your own service URL and credentials. For a service listed on its own card, use the instructions under Prebuilt connectors instead. With Custom you own the provider’s contract, so if their API changes the integration is yours to adjust.

  A ? sits beside the choices that need explaining: each connector card, each protocol, Direction, Authentication method and Name. Select it for a short explanation of what the option does and when to pick it.

  

• 2
  On the Protocol screen, choose the TLS transport. Match it to what the provider documents:

  • MQTTS holds a connection open and exchanges messages on topics, which suits a broker or gateway that streams continuously. Choose it when the other service speaks MQTT.
  • HTTPS makes one request per exchange. It is the simplest to configure and to debug, and it is what most provider APIs offer. Choose it for a REST or webhook API.
  • WSS keeps one connection open and carries messages in both directions. Choose it when the provider documents a WebSocket endpoint.

  

• 3
  On the Credentials screen, set the direction (Pull, Push, or Pull & Push), enter the pull and/or push URL, optionally add custom headers, then pick an authentication method and enter its credentials. Pull and Push use separate URLs when you choose both directions. See the table below for the fields required by each authentication method.

  Pull means NEQTO.ai calls your service and asks for data: on a schedule when the integration has a pull interval, and whenever you pull a sample. A Custom integration starts without an interval; set one in its Edit settings to pull on a schedule. See Custom pull schedules below. Push means NEQTO.ai sends data out to your service. Both need an endpoint NEQTO.ai can reach on the public internet. The authentication method is how NEQTO.ai proves who it is to that service, so the provider decides which one to use: check their API documentation. A wrong choice fails at the connection test rather than silently.

  

• 4
  On the Settings screen, give the integration a name and an optional description, then choose Create. Integration names must be unique within the account, and the name identifies this connection in the list, in alerts, and wherever its devices appear, so one that says which system and which site it serves saves guessing later. It can be changed at any time.

  The integration starts in Draft status: you can pull a manual sample while it is a draft, but scheduled pulls and pushes do not run until you turn it on.

  

• 5
  The wizard moves to Verify. See Verify: test and activate.

Draft an integration with AI

The wizard opens with a field reading Describe the service you would like to integrate. Describe the service you want to connect and the assistant fills the screens it can work out, leaving you to check them and continue. Fields it inferred are marked, and anything you typed yourself is kept. See the Ask AI guide for how drafting behaves everywhere it appears.

Authentication methods

Six methods are available. The choice changes what you enter and how NEQTO.ai sends it, and every secret is encrypted on save and never shown again.

MQTT username for token-based authentication

Over MQTTS, the broker asks for a username when the connection opens. A token can serve as the password, but not the username. So when the protocol is MQTTS and the authentication method is API key, Bearer token, OAuth2 (client credentials) or OAuth2 (authorization code), the Credentials screen adds an MQTT username field. Enter the username the broker expects. The token becomes the password. The field is required, and it appears both in the create wizard and in the row’s Edit credentials action, so you can add one to an existing integration without rebuilding it.

Basic auth is unaffected: it already collects a username and password, and those are what the broker receives. Mutual TLS (mTLS) authenticates the connection itself and asks for no username.

Prebuilt connectors

A prebuilt connector appears on the Type screen as its own card. NEQTO.ai supplies its protocol, request format, and platform credentials. The wizard asks only for the account, authorization, or location that the provider needs.

The prebuilt connectors are ENERGY STAR Portfolio Manager and Weather. Use Custom for other services.

Free and Starter do not include prebuilt connectors such as ENERGY STAR Portfolio Manager and Weather. Custom integrations are available on every plan.

ENERGY STAR Portfolio Manager

This connector pulls annual ENERGY STAR scores, energy, emissions, and water metrics for properties shared from your Portfolio Manager account. NEQTO.ai uses a platform-managed Portfolio Manager account, so you do not enter that account’s username or password in the integration. Setup has three parts: prepare the property in Portfolio Manager, connect your Portfolio Manager account to NEQTO.ai, then share the property with the platform account.

Prepare the property in Portfolio Manager

NEQTO.ai reads the metrics Portfolio Manager has already calculated. Portfolio Manager only calculates them for a property that has a meter with 12 full calendar months of bills, ending with the most recently completed month. A property without that data connects and shares normally but produces no values, so finish this part first.

• 1
  Sign in to Portfolio Manager. On MyPortfolio, choose Add a Property.

  

• 2
  Pick the property type, the number of buildings, and whether the building is existing or still under construction, then choose Get Started. On Basic Property Information, enter the name, address, year built, Gross Floor Area, and the percentage of floor space that is occupied.

  

• 3
  On How is it used?, fill in the property use details for the building type and choose Add Property. Fields marked with a star feed the 1 to 100 ENERGY STAR score. Use a default is acceptable for values you do not know.

  

• 4
  Open the property’s Energy tab and choose Add energy use information. Tick each energy source the building uses and how many meters it has, then choose Get Started. For each meter set the Units and the Date Meter became Active, then Create Meters. Confirm that the meters account for the property’s total energy use.

  

• 5
  On Manage Bills, add one entry per month for at least the last 12 full calendar months and choose Save Bills. Each entry runs from the first to the last day of a month, and the newest entry ends on the last day of the previous month. Bills that run mid-month to mid-month need 13 entries to cover 12 full months.

  

Connect your Portfolio Manager account

• 1
  In NEQTO.ai, on the Type screen, choose ENERGY STAR Portfolio Manager. The Connect step displays a one-use connection code and its expiration time.
• 2
  Follow the link to your own Portfolio Manager account. Open Contacts, choose Add New Contacts/Connections, search for the platform account named in the wizard, and select Connect. Paste the code into the Neqto Connection Code field and send the request. The wizard detects and accepts the connection automatically. If the code expires, generate a new one.

  

  

  

  

• 3
  If your organization has already verified a Portfolio Manager account, the Connect step lists it instead of issuing a code. Select the account whose properties you want, or choose Connect another account. A Portfolio Manager account can belong to only one NEQTO.ai organization.

  

• 4
  The Settings step opens with the verified account shown as a read-only line. Until that account has shared a property, the Properties section shows a waiting notice instead of a list. Leave the wizard open and share the property in Portfolio Manager, as described next.

  

Share the property with the platform account

Each property you want to sync is shared from inside Portfolio Manager at the Exchange Data permission level. Read-only access is enough: NEQTO.ai only reads metrics and never writes to your property or meters.

• 1
  In Portfolio Manager, open the Sharing tab and choose Share with your Utility or Service Provider for exchanging data. Do not use Share (or Edit Access to) a Property, which is for sharing with other Portfolio Manager users.
• 2
  Under Select Web Services Provider, choose the platform account. Only connected contacts appear in that list, so finish the connection first. Under Select Properties, tick the properties to sync and apply the selection.
• 3
  Under Choose Permissions, select Bulk Sharing, then Exchange Data Read Only Access, and choose Authorize Exchange.

  

• 4
  NEQTO.ai accepts the share automatically, usually within seconds. Portfolio Manager records it on the Sharing tab as accepted by the platform.

  

Finish the integration in NEQTO.ai

• 1
  Back in the wizard, step Back and Next to refresh the Settings step. The shared property now appears under Properties. Name the integration and tick the properties to sync. Leaving every property unchecked includes every property this account shares now or later. You can select up to 200 specific properties instead.
• 2
  Choose at least one metric, select US customary (EPA) or Metric units, and set the sync interval in whole minutes. The default is 1,440 minutes. Your plan may require a longer interval. Each reported value keeps the unit supplied by ENERGY STAR. Choose Create.

  

• 3
  The integration appears in the list as a draft. Turn on its Status switch, then from its actions menu choose Create device(s) from sample and Pull sample. NEQTO.ai proposes one device per property, named after the property, with a field for each metric Portfolio Manager reports and the unit it reports it in. Review the proposal and choose Create device.

  

• 4
  The first successful pull changes Pending activation to Active, and the device count shows one device per property. From here the devices behave like any other: dashboards, alerts, and exports all work, and each scheduled sync refreshes the values.

  

The connector can pull these eight metrics:

• ENERGY STAR score
• Site and source energy use intensity (EUI)
• Site energy total and source energy total
• Total location-based greenhouse gas emissions and emissions intensity
• Water use total

Weather

The Weather connector pulls current conditions for one location on a schedule and creates a device for them. Weather readings can then be used beside your own data in dashboards, alerts, and analytics.

• 1
  On the Type screen, choose Weather. The wizard goes straight to Settings. There is no protocol to pick and no credential to supply.
• 2
  Name the integration, then set the location. Latitude runs from −90 to 90 and Longitude from −180 to 180. Location name is optional and is only a label. Conditions are fetched by coordinates, so the name never changes what is observed.
• 3
  Set the Sync interval in minutes, then choose Test. It fetches the current conditions for those coordinates and lists them, so you can confirm you have the right place before saving. Match the interval to how often the source actually updates: polling faster than the provider publishes gains nothing, and your plan sets the shortest interval allowed. If the prefilled value is shorter than your plan permits, creating the integration fails with The pull interval is shorter than your plan allows. Raise the number and try again.

  

• 4
  Choose Create. Along with the integration, NEQTO.ai creates its weather device, with the standard weather attributes already mapped.
• 5
  The wizard moves to Verify, where you can test the connection and turn the integration on. You can also close the wizard and turn it on from its row later — scheduled updates do not start while the integration is a draft.

Every scheduled sync brings in the same eight variables:

• Temperature and apparent temperature (what it feels like)
• Relative humidity
• Precipitation
• Wind speed and wind direction
• Surface pressure
• Cloud cover

If the automatic device setup does not complete, the integration is still created. Open its actions menu and choose Create device(s) from sample to finish the job by hand.

Pull data and create devices

For a Custom pull integration, Create device(s) from sample makes an immediate request to the external service. HTTPS uses GET. WSS waits for the first message after the connection opens. MQTTS subscribes to the topic in the URL path, or to all topics when the URL has no path. In every case, the first payload must be a single JSON object no larger than 1 MB.

From a sample to a device

• 1
  Open the integration’s actions menu, choose Create device(s) from sample, then choose Pull sample. For a Custom integration, the AI inspects the JSON structure and proposes fields. Prebuilt connectors use their known provider fields instead.
• 2
  Review the proposed device name and fields. You can include or exclude fields, rename them, and correct their units. Changes are saved with the proposal, so you can close the dialog and return later. Select the trash button to reject a proposal without creating a device.
• 3
  Select Create device for each proposal you want. NEQTO.ai creates the device and its selected Attributes, and links it to the same applications as the integration. Devices created this way are labeled Integration in Devices & Data.

A Custom integration without a device identifier creates one device from its sample. When the account’s metadata mapping defines an identifier field, that value becomes the Device’s external ID. Later payloads must carry the same identifier value to reach that Device. NEQTO.ai freezes the identifier path when you confirm the first Device, so changing the account metadata mapping later does not reroute that integration.

Push data to an integration

A Custom integration set to Push or Pull & Push sends a JSON payload to your service. The protocol you picked decides what happens on the wire.

A Custom integration with direction Push or Pull & Push can send a JSON payload to the external service. The serialized payload can be up to 64 KiB. NEQTO.ai applies the integration’s saved authentication and custom headers.

An alert’s Payload push action can target an HTTPS or MQTTS integration that supports push and is Active or Pending activation. To call a webhook when an alert fires, create a Custom HTTPS integration with the webhook URL as its Push URL, then select that integration in the alert’s Payload Push tab and save the alert. This creates the alert target’s Action. Only then can you open that Action’s Dry run dialog, review it, select Approve in the dialog, and return to the list to Enable it. Dry run is the required UI path to Approve; creating the integration alone does not create an Action. The webhook receives a JSON POST when the enabled target’s alert fires. Alert payload push does not support WSS. See the Alerts guide for payload templates, target approval, and destination rules.

Verify: test and activate

Verify is the wizard’s last screen, headed Test and activate. It does three things in order: check the connection, turn the integration on, and watch for the first data.

Test the connection

Choose Test connection to run it. A pass reports The connection works, and the button becomes Test again, so you can correct something and retest without leaving the wizard. A failure reports The connection test failed and the reason, such as Authentication rejected by the endpoint.

On a Custom integration this is the same check as Test connection on its row, so see that section for what each outcome means, including the credential probe that follows a successful connection. On a prebuilt connector the test asks the provider for a real sample instead, with no credential probe. That test is only on this screen; the row does not offer it.

When the provider must approve access

An integration that uses OAuth2 (authorization code) needs your approval at the provider’s website. Until you approve access, the Verify test reports Provider authorization required, and Activate integration does not appear.

The integration is already saved as a Draft. Finish from the integrations list:

• 1
  Choose Close to leave the wizard.
• 2
  Open the integration’s row menu and choose Connect. NEQTO.ai sends you to the provider’s sign-in page.

  

• 3
  Sign in and approve the request. The provider returns you to the integrations list.
• 4
  Choose Test connection on the same row menu, then turn on the switch in the row’s Status column. A pull integration also needs Create device(s) from sample before its readings are stored.

Connect requires the Edit Integrations permission. If your role lacks it, Verify asks you to have someone with that permission finish these steps.

Activate the integration

Activate integration appears only after the test passes, below the line Activation starts collecting data. It is a separate step from the test above. Choosing it asks for confirmation — Yes, activate it or Not yet — so you can check a connection without committing to it.

Activating does not by itself make the integration Active. The status shows Pending activation, with a note that the connection is not live yet and is activated once the first exchange with the provider succeeds. If activation itself fails, the screen reports The integration could not be activated. Its status is unchanged. and offers the button again.

Wait for the first data

The screen then watches for readings, showing Waiting for the first data… while it looks, and reports what it finds. None of the states below is an error.

When you are working inside an application, once devices exist a What next row offers Create alert and Create dashboard. Outside an application the row does not appear. Each opens that flow with the new devices already selected. The Alerts and Dashboards guides cover what to do there.

Integration status

A new integration starts as Draft. Turning it on changes the status to Pending activation. Its first successful pull or push changes the status to Active. Testing an integration, Custom or prebuilt, never changes its status, and neither does Create device(s) from sample; see Verify: test and activate.

Read the Status column

A status that needs explaining carries an icon next to its switch. Hover it for the sentence. A Disabled row shows the reason NEQTO.ai recorded when it was deactivated, so you know what to check. A Pending activation row explains that it activates on the next successful pull or push.

Test connection

Test connection on a Custom integration’s actions menu opens a connection with the stored credentials but does not pull or push data. Prebuilt connectors do not offer this action because NEQTO.ai manages their endpoints and credentials. For HTTPS, any response other than 401 or 403 passes the reachability test. Even a 404 passes, although it may mean the URL points to the wrong resource. WSS and MQTTS must complete their protocol handshakes. For an integration with both directions, this initial test uses the pull URL.

After a successful connection test, NEQTO.ai probes the configured endpoint or endpoints with a deliberately invalid version of the credential. This checks whether the selected authentication method changes the response. Other controls, such as custom headers or network access rules, may still protect the service. The test has four possible outcomes:

Edit and delete integrations

Both start from a row’s actions menu. Editing credentials replaces only the secrets you type, and deleting is permanent.

Open a row’s actions menu and choose Edit settings to change its name and description. Edit credentials is available for Custom integrations and replaces only the secret values you enter. Prebuilt connectors keep their provider credentials under platform control.

Edit settings shows Direction only when more than one direction is available. Prebuilt connectors always pull. Custom integrations use the URLs set at creation, which you cannot change in the edit screens. An integration created as Pull & Push has both URLs and can switch between all three directions. One created as Pull or Push keeps that direction.

Permissions

NEQTO.ai checks account permissions on the account-level page and application permissions inside an application. A missing permission may hide the control or reject the request.

Example: pull from your own service

Use a service you control when testing the Custom pull flow so you can inspect its response and repeat the request.

• 1
  Expose one HTTPS URL that returns a single JSON object of current readings. A flat response makes the proposed fields easier to review, although nested fields are supported.

  {
    "meter_id": "MTR-114",
    "power_kw": 8.4,
    "energy_kwh": 15230.7,
    "temperature_c": 41.2
  }

• 2
  Create the integration: type Custom, protocol HTTPS, direction Pull, that URL, and whichever authentication method your service expects. Then run Test connection to check reachability. A conclusive credential result also confirms whether the endpoint accepts the stored credential and rejects the altered one.
• 3
  Open Create device(s) from sample, pull a sample, and confirm the proposed fields. That creates the device. Later manual samples use the same endpoint. To pull on a schedule, set a Sync interval in the row’s Edit settings, as explained above.

Troubleshooting

Each message below names what NEQTO.ai could not do and what to change before you try again.

Limits and security

The caps and network rules that apply to every integration.