Get Records

In Zoho IoT, a record is an entity which stores all the combined information of a particular model or module, which is acquired from various sources. The records API allows the user to get, create, update, delete, or search records.


Purpose

To retrieve the records that match your search criteria.

Endpoints

CopiedGET/{module_api_name}

GET/{module_api_name}/{record_id}

Request Details
 

Request URL

{api-domain}/iot/{version}/{module_api_name}

To get specific record:
https://{api-domain}/iot/{version}/{module_api_name}/{record_id}

Note: "api-domain" must be replaced with your application domain e.g. "app1234xxxx.zohoiot.in"  
 
 

Supported modules

Devices, Assets, Locations, Alarms, Datapoints, Products, Manufacturers, Vendors, Certificates, Policies, Commands, and Users.


Custom modules

For custom modules, use their respective API names in the request URL. Use the below scope for custom module APIs.

Zoho IOT.modules.ALL
 

Headers

Authorization: Zoho-oauthtoken {{oauth}}


Scope

scope=ZohoIOT.modules.{module_name}.{operation_type}
or
scope=ZohoIOT.modules.ALL


Possible module names

devices, assets, locations, alarms, datapoints, products, manufacturers, vendors, certificates, policies, commands, users.


Possible operation types

ALL - Full access to the record
READ - Get records from the module


Parameters

Param name, type, mandatory

  • per_page - int,optional

    To get the list of records available per page. The default and the maximum possible value is 20 and 200 respectively. 
    Possible values: Positive integer values only.

  • entity_id,long, optional

    To retrieve specific records based on their unique entity ID.
    Possible values: Valid unique IDs of records. Example: 2000000098001

  • relation_id,long, optional

    To retrieve specific records based on their unique relation ID.
    Possible values: Valid unique relation IDs of records. Example: 2000000077228

  • page,integer

    To get the list of records from the respective pages. The default value is 1
    Possible values: Positive integer values only.

  • cvid,long, optional

    To get the list of records based on custom views. Note that you cannot use this param with the "sort_by" param.You can get custom view id from Custom View Meta API
    Possible values: {custom_view_id}.

  • filter,JSONObject, optional

    To get the list of records based on the filter options.
    Possible values : Positive integer values only.

  • model_idlong, optional

    To get the list of records based on the model.
    Possible values: Valid unique model IDs of records. Example: 2000000077228

  • fields,string, optional

    To get the list of records for the specified field names.
    Possible valuesField API names as comma separated values.

  • sort_order,string, optional

    To sort the available list of records in either ascending or descending order.
    Possible values: asc ascending order, desc - descending order. The default value is 'desc'.

  • sort_by,string

    To sort the records based on the fields
    id, Created_Time, and Modified_Time.The default value is 'id'. Note that you cannot use this param with the "cvid" param.

Sample Request: First API Call

CurlDelugeJavaPythonJavaScript
Copiedcurl --location -g '{{api-domain}}/iot/v1/devices?per_page=10&page=1' \
--header 'Authorization: Zoho-oauthtoken {{oauth}}' \
--header 'Content-Type: application/json'

// "api-domain" must be replaced with your application domain e.g. "app1234xxxx.zohoiot.in"


CopiedRequest 
response = invokeurl
[
	url :"https://app71372*****.zohoiot.in/iot/v1/devices?fields=name,status"
	type :GET
	connection:"iot_conn"
];
info response;


// "api-domain" must be replaced with your application domain e.g. "app1234xxxx.zohoiot.in"
// connection must be set to the IoT connection configured in your application. Refer Connections document for details.


Copiedimport java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class GetRecords
  {
    public static void main(String[] args) throws Exception {
        // User Inputs
        String api = "https://app71372t****.zohoiot.in/iot/v1/devices?fields=name,status";
        String access_token = "Zoho-oauthtoken 1000.e7839*************ea3744.8ba9*****0da575";
        String httpMethod = "GET";

        URL url = new URL(api);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod(httpMethod);
        connection.setRequestProperty("Authorization", access_token);
        connection.setDoOutput(true);
        connection.setInstanceFollowRedirects(false);
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setRequestProperty("Accept", "*/*");
        int responseCode = connection.getResponseCode();
        System.out.println("\nResponse Code:  " + responseCode);

        if (responseCode >= 200 && responseCode < 300) {
            // Read the response from the server
            BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            String line;
            StringBuilder response = new StringBuilder();

            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            reader.close();

            // Print the successful response
            System.out.println("Response: " + response.toString());
        } 
    }
}


Copiedimport requests

headers = {
 "Authorization": "Zoho-oauthtoken 1000.d********************f.8*********************fd",
 "Content-Type": "application/json"
}

response = requests.get("https://app71372tkdhg.zohoiot.in/iot/v1/devices?fields=name,status", headers=headers)
print(response.json())


Copiedfetch("https://app71372tkdhg.zohoiot.in/iot/v1/devices?fields=name,status", {
  method: "GET",
  headers: {
    "Authorization": "Zoho-oauthtoken 1000.83ddrfa*******3.df4353***e"
  }
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

console.log(res);

Refer to the Connections document for creating a connection in the application and using the same in the Deluge code as shown above.

Response to the First API Call

Copied{
    "assets": [
        {
            "layout": {
                "name": "Pheripheral asset model",
                "icon": "asset",
                "id": "308000000201239"
            },
            "connected_gateway": null,
            "parent_id": null,
            "connection_status": {
                "name": "Unconnected Asset",
                "color_code": "#F44336"
            },
            "located_at": null,
            "name": "Instance",
            "record_image": "rb97s7e2d8273a9f74b9ebe9f2588e5b58792",
            "id": "308000000201425",
            "status_update_time": {
                "millis_in_gmt": 1682504565000,
                "formatted": [
                    "5 months ago"
                ],
                "value": "2023-04-26T15:52:45"
            },
            "status": {
                "level": 5,
                "name": "Clear",
                "id": "308000000074953",
                "color_code": "#1CBC9D"
            }
        }
    ],
    "info": {
        "per_page": 10,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}