Setup guide

Utility Data Sync connects your HubSpot contacts to your utility-data provider account. For each contact you opt in, the app creates a matching customer in your provider account from the contact's name, email, phone, address, and utility; tracks that customer's utility-connection progress; and writes the account, meter, tariff, and latest-bill details back onto the HubSpot contact record once they're available.

Install the app

1. Open the app's HubSpot Marketplace listing and click Install app (or Connect app).
2. Choose the HubSpot account you want to connect.
3. Review the requested permissions and click Connect app.
4. You'll be redirected to a confirmation page reading "Authorization complete. You can close this tab." The app is now installed.

Screenshot needed — Marketplace listing Install button

Screenshot needed — HubSpot account picker

Screenshot needed — scope approval screen

Screenshot needed — authorization confirmation page

Utility Data Sync requests three permissions:

On install, the app creates its custom contact properties in a dedicated Utility Data Sync property group. This happens in the background and usually finishes within a minute.

Connect your utility-data provider account

1. In HubSpot, go to Marketplace ▸ Connected apps ▸ My apps, click Utility Data Sync, then open the Settings tab.
2. Under Environment, choose Staging or Production, matching the provider account you want to sync with.
3. In API key, paste the API key from your provider dashboard exactly as shown. You don't need to encode or format it — the app encodes it for you and verifies it with the provider before saving.
4. Click Save. On success you'll see a "verified and saved" confirmation. If the key or environment is wrong, the page tells you immediately.

Screenshot needed — app Settings tab

Screenshot needed — Settings form in the Connected state

Your connection is stored against your HubSpot account, not a single install. If you reinstall the app later, you won't need to re-enter the key.

Use the app

Opt a contact in

On any contact record, check the Sync to Utility Provider property. That's the only manual step. The rest is automatic.

Screenshot needed — Sync to Utility Provider property checked on a contact

What happens automatically

1. Customer creation. Within about a minute the app creates a matching customer in your provider account and fills in Utility Customer Created? and Utility Provider Customer Id.
2. Onboarding. Until the customer finishes connecting their utility, the app records their Onboarding Link and Onboarding Token once, and keeps Bills Are Ready set to No.
3. Bill data. Once the provider reports bills are ready, the app writes the account, meter, tariff, and latest-bill fields onto the contact and sets Bills Are Ready to Yes. The contact is then fully synced and left alone.

A background reconciliation runs about every 15 minutes to catch anything missed and to advance contacts through the stages above.

The sync status card

Add the Utility Data Sync card to your contact record's right sidebar, under Customize ▸ Card library ▸ Card types: App. It shows the contact's current stage, the onboarding link, and the latest bill summary, and has a Sync now button that runs the sync for that contact immediately.

Screenshot needed — Utility Data Sync sidebar card on a contact record

Switching environments

If you change Environment on the Settings page, every opted-in contact is re-synced against the newly selected environment. A contact that was already created there before is reused, not duplicated. Nothing is deleted, so switching back and forth is safe.

Contact properties the app creates

All of these are grouped under Utility Data Sync. You only ever set the first one.

Data handling

When you opt a contact in, the app sends that contact's first name, last name, email address, phone number, street address, city, state, ZIP, and utility to your connected utility-data provider to create the customer record. It then reads that customer's onboarding, account, meter, and billing data back from the provider and stores it in the HubSpot contact properties listed above.

The app's backend stores only your HubSpot OAuth tokens and your provider API key, both encrypted at rest. It does not retain contact data of its own — contact data lives in HubSpot and in your provider account.

If a contact is deleted in HubSpot, or deleted under a GDPR or privacy request, the app stops syncing it. Data already written to your provider account is governed by your agreement with the provider and is not removed by the app.

For full details on how contact data is processed and stored, see the privacy policy.

Disconnect the app

Disconnecting the provider connection stops all syncing for the account. Contacts already synced keep their property values. No data is removed from HubSpot or from your provider account.

1. Go to Marketplace ▸ Connected apps ▸ My apps ▸ Utility Data Sync ▸ Settings.
2. Click Disconnect and confirm.

Screenshot needed — Disconnect button in the Settings tab

To reconnect later, re-enter your API key on the same page.

Uninstall the app

Uninstalling revokes the app's access to your HubSpot account and stops all syncing. The custom Utility Data Sync contact properties and their values remain on your contacts unless you delete them manually in HubSpot property settings. Your provider account and its data are untouched.

To uninstall, follow HubSpot's instructions for uninstalling an app.

Support

Questions or problems? Read the support page first — it covers the issues we see most often — or email dev@nidish.com.