utilityAccounts: Search Utility Service Accounts by Address

The utilityAccounts query searches existing utility service accounts by street address, account number, or both. Use it to verify that a customer’s service location exists in the utility’s system and to retrieve account details — such as account status and TDU code — before submitting an enrollment.

Parameters

At least one of street or accountNumber is required. If you omit both, the API returns the error: "No street address or account number specified for utility accounts search".

String

Street address line 1 of the service location. Required if accountNumber is not provided.

String

The utility account number associated with the service location. Required if street is not provided.

String

Second address line, matched exactly against the value the utility has on file.Most accounts have no second line, and supplying one that does not match the stored value returns zero results rather than a looser match. Omit it unless you already know the utility’s exact string. Apartment and unit numbers usually live inside street, in whatever format the utility recorded them, so pass those as part of street.

String

City of the service location.

String

Two-letter U.S. state code (for example, "TX").

String

Five-digit ZIP code of the service location.

Boolean

Filter results to business accounts (true) or residential accounts (false). Omit to return all matching accounts regardless of account type.

Example

{
  utilityAccounts(
    street: "901 BAGBY ST"
    city: "HOUSTON"
    state: "TX"
    zipCode: "77002"
  ) {
    id
    accountNumber
    utilityCode
    isBusiness
    accountStatus
    displayAddress
    serviceAddress {
      street
      street2
      city
      state
      zipCode
    }
  }
}

{
  "data": {
    "utilityAccounts": [
      {
        "id": "v2-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "accountNumber": "1000000000000000000000",
        "utilityCode": "CNP",
        "isBusiness": true,
        "accountStatus": "ACTIVE",
        "displayAddress": "901 BAGBY ST, HOUSTON, TX",
        "serviceAddress": {
          "street": "901 BAGBY ST",
          "street2": "",
          "city": "HOUSTON",
          "state": "TX",
          "zipCode": "77002"
        }
      }
    ]
  }
}

id and accountNumber above are masked. Real values are a v2- prefix followed by 32 hex characters, and a 22-digit ESID. Everything else is exactly what this query returns today.

A partial street matches every unit at that address. 901 BAGBY ST returns one account, but a street with many units can return dozens. Narrow with zipCode and isBusiness, and read the street value back to see how the utility spelled the unit before querying for it.

Response fields

Unique identifier for the service account (for example, "v2-CB1C1D302FC4B19F58D4F89F775AAFD6").

String

The utility-assigned account number. May be null for some accounts.

AccountStatus

Current status of the account. Possible values:

ACTIVE — The account is energized and in service.
INACTIVE — The account exists but is not currently in service.
DE_ENERGIZED — Service has been disconnected at this location.

String

The TDU or utility code associated with this account (for example, "AEPCC").

Boolean

true if this is a business account; false if it is a residential account.

String

A pre-formatted, human-readable version of the full service address. May be null for some accounts.

Address

The structured service address for this account.

Show serviceAddress fields

String

Street address line 1.

String

Street address line 2 (for example, suite or unit). May be null.

String

City name.

String

Two-letter state code (for example, "TX").

String

Five-digit ZIP code.

Integrate with PowerHQ

Plan Data API

Core Concepts

Queries

Playground

Reference

utilityAccounts: Search Utility Service Accounts by Address

Parameters

Example

Response fields

​Parameters

​Example

​Response fields

Parameters

Example

Response fields