Plugin SDK
Plugin SDK
Breadcrumbs

Getting Started

Get started using the HomeSeer JSON API

Authentication

For local network access, most endpoints don't require authentication. For remote access via the MyHS service, you'll need to provide credentials:

  1. Username and password:

    • Add user=YOUR_USERNAME&pass=YOUR_PASSWORD to the query string

    • Or include these credentials in the HTTP header

  2. OAuth token (for approved clients):

    • Add token=YOUR_TOKEN to the query string

Authentication is REQUIRED when accessing a system on a local network when the “No Password Required for Local (same subnet) Login” setting is UNCHECKED. This setting can be found on the NETWORK tab in SETUP.

Base URLs

  • Local network: http://YOUR_HOMESEER_IP/JSON

  • MyHS service: https://myhs.homeseer.com/json?licenseid=SYSEM_LICENSE_ID

When using MyHS to connect to your system, you MUST include the licenseid query parameter.

General Request Format 

https://BASE_URL/JSON?request=REQUEST_TYPE&param1=value1&param2=value2

Replace REQUEST_TYPE with the specific API call you want to make, and add any required parameters.


Common Workflows

Finding a System to Connect To on MyHS

When using the MyHS service, you'll first need to locate the specific HomeSeer system you want to interact with. See https://docs.homeseer.com/hspi/getsystems for more info on this request.

  1. Get available systems:

    GET https://myhs.homeseer.com/getsystems?user=YOUR_USERNAME&pass=YOUR_PASSWORD

  2. Parse the JSON response for the license of the system you would like to access.

  3. Use this license in subsequent requests to MyHS.

You can use the tunnel_ip of a system but we recommend you use myhs as the assigned tunnel server may change without warning.


Getting a List of Devices

To retrieve a list of all devices in your HomeSeer system call getstatus. See https://docs.homeseer.com/hspi/getstatus for more info on this request.

GET https://YOUR_BASE_URL/JSON?request=getstatus

This will return detailed information about all devices. You can filter results using additional parameters like location1, location2, or specific device references.


Reading the Status of a Specific Device

To get the status of a particular device, use its reference number. See https://docs.homeseer.com/hspi/getstatus for more info on this request.

GET https://YOUR_BASE_URL/JSON?request=getstatus&ref=DEVICE_REFERENCE_NUMBER

Replace DEVICE_REFERENCE_NUMBER with the actual reference number of the device you're interested in.


Controlling a Specific Feature of a Device

To control a device, you'll typically use the controldevicebyvalue request. See https://docs.homeseer.com/hspi/controldevicebyvalue for more info on this request.

GET https://YOUR_BASE_URL/JSON?request=controldevicebyvalue&ref=DEVICE_REFERENCE_NUMBER&value=DESIRED_VALUE

Replace DEVICE_REFERENCE_NUMBER with the device's reference number and DESIRED_VALUE with the control value you want to set (e.g., 0 for off, 1 for on, or other values depending on the device type).


Best Practices

  • Make sure the query parameters are URL encoded otherwise the calls may fail. Use HttpUtility.URLEncode with .Net.

  • To obtain a token for a user's system using OAuth we must add your client ID and secret to our server. To provide us with a client ID and secret or request that we provide one please email Support@homeseer.com.