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

The wizard walks four screens: Type, Protocol, Credentials, and Settings. A Custom integration is the one you configure yourself, and it lands in Draft status until you turn it on.

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

  

• 2
  On the Protocol screen, choose the TLS transport: HTTPS, WSS, or MQTTS.

  

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

  

• 4
  On the Settings screen, give the integration a name and an optional description, then finish. Integration names must be unique within the account. The new 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.

  

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 available prebuilt connectors are ENERGY STAR Portfolio Manager and Weather. Use Custom for other services.

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.

• 1
  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 more than one Portfolio Manager account, select the account whose properties you want. You can also choose Connect another account. A Portfolio Manager account can belong to only one NEQTO.ai organization.
• 4
  On Settings, name the integration and choose properties. Leaving every property unchecked includes every property this account shares now or later. You can select up to 200 specific properties instead. If no property has been shared yet, you can still create the integration. It waits until the property owner shares one with the platform account, and NEQTO.ai accepts the share automatically.
• 5
  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.
• 6
  Create the integration. From its actions menu, choose Create device(s) from sample. NEQTO.ai proposes one device per property. Review and confirm each proposal, then turn on the integration. Its first successful pull changes Pending activation to Active.

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, analytics, and maps.

• 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 (your plan sets the shortest one allowed), 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.

  

• 4
  Choose Create. Along with the integration, NEQTO.ai creates its weather device, with the standard weather attributes already mapped.
• 5
  Back on the Integrations list, turn on the new integration. It shows Pending activation until the first scheduled pull succeeds, then changes to Active. 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. Alert payload push does not support WSS. See the Alerts guide for payload templates and target rules.

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. A connection test does not activate the integration because it sends no data.

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 to change its name and description. Custom integrations also let you change direction. Edit credentials is available for Custom integrations and replaces only the secret values you enter. Prebuilt connectors keep their provider credentials under platform control.

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. Recurring pulls require a pull interval in the integration configuration, 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.