← Self Help

Jalmiti Society API

Read your society's sensor status and water consumption from your own software: a society management system, a billing tool, a spreadsheet or a home-automation hub.

Quick Start Guide

Enter your own values and click Apply. Every example below is rebuilt with them, ready to copy and run. Each value has its own colour, so you can see exactly where it goes. What you type stays on this page in your browser. Nothing is sent to Jalmiti.

You will find your API key, Society ID and user on the API Access page, and unit names on your Dashboard.

48 letters and digits
Shown on the API Access page
Your login name or email
Separate several units with | (for example A101|A102)
WM.0 = water meter (more)
12 characters printed on the device, used by status and command
Month and year examples use this date's month and year

Examples need JavaScript to be enabled.

Each example is one call. Wait for your call interval between calls, or you will get SCI_VIOLATION.

1. Getting an API key

Only the Super Admin of a society can create its API key.

  1. Log in and open the Society page.
  2. Click API Access.
  3. Solve the captcha. An OTP is then sent to your registered mobile number and/or email.
  4. Enter the OTP. The page shows your Society ID, your user name and, if you already have one, your API key (hidden until you click Show).
  5. If you do not have a key yet, choose:
    • Interval between successive API calls (for example, every 15 minutes), and
    • Validity of the key in days,
    within the limits shown for your society, and click Create new passcode. The key starts with the number of tokens shown on the page (for example, 10,000).

The API key is 48 letters and digits long. You need three values on every call:

ValueWhere to find itSent as
API keyAPI Access pageHeader X-Api-Key (recommended) or parameter api_key
Society IDAPI Access pageParameter soc_id
UserYour login name or emailParameter user

Changing or renewing the key

  • Rotate key gives you a new key string straight away and the old one stops working. Use it if the key may have leaked. Your tokens, call interval and validity stay the same.
  • When a key expires, the API Access page lets you renew it with a new interval and validity. You get a new key string, and your remaining tokens carry over.
  • To top up tokens, please contact us.
Each time you open the API Access page, you have to solve a new captcha and enter a new OTP. This keeps the key safe if someone else uses your logged-in browser.

2. Making a call

Base URL:

https://jalmiti.com/society/api/v1/<endpoint>/

The endpoints are status, hour, day, month, year and command. You can send parameters in any of these ways:

  • GET as a query string, or
  • POST as a form (application/x-www-form-urlencoded), or
  • POST as JSON (Content-Type: application/json).

Always use https://. Every response is JSON.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/status/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&scope=society"

Special characters in values (@, spaces, &, + …)

In a URL query string, some characters have a special meaning. Values such as your email, or unit and inlet names with spaces, must be URL-encoded (percent-encoded). Otherwise the call fails, or a different unit or inlet is looked up.

CharacterWrite it asExample valueIn the URL
@%40you@example.comuser=you%40example.com
space%20 (or +)Master Bathinlet=Master%20Bath
+%2BA+B Wingunits=A%2BB%20Wing  (an unencoded + is read as a space)
&%26Bath & Utilityinlet=Bath%20%26%20Utility
#%23Flat #12units=Flat%20%2312
/%2FA/101units=A%2F101
=   ?   %%3D   %3F   %25
|%7CA101|A102 (two units)units=A101%7CA102
,Leave as ,A comma also separates units (units=A101,A102) unless the value contains |. For a unit name with a comma, separate the units with | or use a JSON body.

Easiest way with curl: let curl do the encoding with --get and --data-urlencode, one parameter at a time:

curl --get "https://jalmiti.com/society/api/v1/day/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "soc_id=YOUR_SOCIETY_ID" \
  --data-urlencode "user=you@example.com" \
  --data-urlencode "units=A101" \
  --data-urlencode "inlet=Master Bath" \
  --data-urlencode "date=2026-11-15"

The same request with the encoding typed by hand:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/day/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&units=A101&inlet=Master%20Bath&date=2026-11-15"

Python and JavaScript encode for you when you pass the parameters separately (params= in requests, URLSearchParams in JavaScript), so write the plain values there, for example "you@example.com" and "Master Bath". Do not encode them a second time. See the code examples.

JSON body: values inside a JSON body are never URL-encoded. Write them as they are. A list of units avoids separators altogether:

curl -X POST "https://jalmiti.com/society/api/v1/month/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soc_id": "YOUR_SOCIETY_ID", "user": "you@example.com", "units": ["Villa 7, East", "A+B Wing"], "inlet": "Bath & Utility", "month": "2026-10"}'
On Windows cmd, a % in a batch file must be written as %%, and & must be inside double quotes. --data-urlencode avoids most of these problems.

3. Choosing units and inlets (<ENTITY>)

The consumption endpoints (hour, day, month, year) add up all the sensors of an <ENTITY>. Use the unit and inlet names exactly as they appear on your Dashboard.

You wantParameters
One unit (all its inlets)units=A101
A group of units (all their inlets)units=A101|A102|B004 or units=A101,A102,B004  (up to 5 units; your society's limit may differ)
One inlet of one unitunits=A101&inlet=Kitchen  or  units=A101&inlet=Master%20Bath

Names with spaces or symbols must be URL-encoded in a query string. See special characters.

Choosing the sensor (sensor=)

A Jalmiti device can carry more than one sensor. The data endpoints (status, hour, day, month, year) take a sensor parameter to say which one you want:

sensor=<TYPE>.<number>[.<number>…]
  • <TYPE> is the two-letter sensor type.
  • <number> picks which sensor of that type on the device, starting from 0. Give several numbers to get several sensors of the same type at once.
ExampleMeaningAvailable
sensor=WM.0Water meter, first (and usually only) oneYes (default)
sensor=TP.0, sensor=TP.1First / second temperature sensorLater
sensor=VR.0.1.2Voltage sensors 0, 1 and 2, i.e. all three phasesLater
sensor=PP.0Pipe pressureLater
sensor=WL.0Water levelLater

If you leave sensor out, WM.0 (the water meter) is used, so existing integrations keep working. Every response tells you which sensor it is for, in data.sensor. Asking for a sensor that is not available yet returns SENSOR_NOT_SUPPORTED and uses no tokens. The command endpoint does not take sensor.

Separate unit names with | (recommended) or ,. Unit names can never contain |, but they can contain commas. If the value has a |, only | separates names, so units=Villa 7, East|A101 means two units. In a URL, | is written %7C. In a JSON body, units can also be a list: "units": ["A101", "A102"]. unit is accepted in place of units.

4. Endpoints

Each call uses tokens, as shown next to the endpoint. Only successful calls use tokens. All data endpoints also accept the optional sensor parameter (default WM.0).

EndpointParameters (besides authentication)ReturnsTokens
statusscope=sensor&device_id=…Status of one sensor10
statusscope=unit&unit=…Status of all sensors of a unit100
statusscope=societyStatus of all sensors of the society1000
hour<ENTITY> date=YYYY-MM-DD&hour=0..23Liters used in that hour10
day<ENTITY> date=YYYY-MM-DDLiters for each of the 24 hours5
month<ENTITY> month=YYYY-MMLiters for each day of the month2
year<ENTITY> year=YYYYLiters for each of the 12 months2
commandaction=…&device_id=…Buzz, blink, open/close the valve, or reboot sensors (details)10 per sensor

All dates and hours are in Indian Standard Time (IST, UTC+05:30). Hour 7 means 07:00 to 07:59.

GET status 10 / 100 / 1000 tokens

Current status of sensors, as last reported to Jalmiti.

ParameterRequiredDescription
scopeYessensor, unit or society
device_idFor sensorThe 12-character sensor ID printed on the device (for example A0B1C2D3E4F5; : and - are ignored)
unitFor unitUnit name
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/status/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&scope=unit&unit=A101"
{
  "success": true,
  "endpoint": "status",
  "soc_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tokens_consumed": 100,
  "tokens_remaining": 9800,
  "next_call_after": "2026-11-16T10:45:00+05:30",
  "data": {
    "sensor": "WM.0",
    "scope": "unit",
    "inactivity_timeout_sec": 1800,
    "count": 2,
    "online_count": 1,
    "sensors": [
      {
        "device_id": "A0B1C2D3E4F5",
        "unit": "A101",
        "inlet": "Kitchen",
        "last_seen": "2026-11-16T10:28:12+05:30",
        "seconds_since_seen": 108,
        "online": true,
        "is_leaking": false,
        "signal": -61,
        "pkt_num": 48211,
        "health": "Ok",
        "valve_installed": true,
        "flow_off": false,
        "sw_version": "3.2.7"
      },
      {
        "device_id": "A0B1C2D3E4F6",
        "unit": "A101",
        "inlet": "Bathroom",
        "last_seen": "2026-11-15T22:03:40+05:30",
        "seconds_since_seen": 44780,
        "online": false,
        "is_leaking": false,
        "signal": -78,
        "pkt_num": 30902,
        "health": "Ok",
        "valve_installed": false,
        "flow_off": null,
        "sw_version": "3.2.7"
      }
    ]
  }
}
FieldMeaning
last_seen, seconds_since_seenWhen the sensor last reported. null if it has not reported recently.
onlinetrue if the sensor reported within the society's inactivity timeout (inactivity_timeout_sec)
is_leakingtrue if the sensor's last report flagged a possible leak (continuous flow)
signalRadio signal strength in the sensor's last report
pkt_numThe sensor's report counter. If it jumps, reports were missed.
healthOk, NOT Ok or Device Banned
valve_installed, flow_offWhether a shut-off valve is fitted and, if it is, whether the water is currently shut off

GET hour 10 tokens

Liters used by the <ENTITY> in one hour. liters is -1 if none of its sensors reported in that hour.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/hour/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&sensor=WM.0&units=A101&date=2026-11-15&hour=7"
{
  "success": true,
  "endpoint": "hour",
  "soc_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tokens_consumed": 10,
  "tokens_remaining": 9790,
  "next_call_after": "2026-11-16T11:00:00+05:30",
  "data": {
    "entity": { "units": ["A101"], "inlet": null },
    "sensor": "WM.0",
    "date": "2026-11-15",
    "hour": 7,
    "liters": 42.5,
    "breakdown": {
      "A101": { "Kitchen": 30.1, "Bathroom": 12.4 }
    },
    "data_withheld": false
  }
}

In breakdown, an inlet with no reports in that hour shows -1, and it is not counted in liters.

GET day 5 tokens

Liters for each hour of a day, from 00:00 to 23:00. This is the same data as the Dashboard's hour-wise graph.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/day/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&units=A101,A102&date=2026-11-15"
{
  "success": true,
  "endpoint": "day",
  "tokens_consumed": 5,
  "tokens_remaining": 9785,
  "next_call_after": "2026-11-16T11:15:00+05:30",
  "soc_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "entity": { "units": ["A101", "A102"], "inlet": null },
    "sensor": "WM.0",
    "date": "2026-11-15",
    "totals": [0.0, 0.0, 0.0, 0.0, 0.0, 12.3, 88.4, 142.0, 97.1, 40.2, 22.0, 18.5,
               25.7, 30.0, 11.2, 9.8, 14.1, 35.6, 70.3, 95.0, 60.2, 31.4, 8.0, 1.2],
    "breakdown": {
      "A101": { "Kitchen": [ "...24 values..." ], "Bathroom": [ "...24 values..." ] },
      "A102": { "Combined Inlet": [ "...24 values..." ] }
    },
    "data_withheld": false
  }
}

totals[i] is the sum over all inlets of the <ENTITY> for hour i. breakdown lists each unit and inlet separately, the same way as the Dashboard.

GET month 2 tokens

Liters for each day of a month. totals has 28 to 31 values, and the first value is day 1.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/month/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&units=A101&inlet=Kitchen&month=2026-10"

The response looks like day, but has "month": "2026-10" instead of date.

GET year 2 tokens

Liters for each month of a year. totals has 12 values, January first.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://jalmiti.com/society/api/v1/year/?soc_id=YOUR_SOCIETY_ID&user=you%40example.com&units=A101&year=2026"

The response looks like day, but has "year": "2026" instead of date.

About the numbers
  • All values are liters, rounded to 2 decimals and converted using each sensor's calibration.
  • Daily and monthly figures come from summaries that the server builds. Today's and this month's values can be incomplete until the next summary runs.
  • While a society's installation is not yet commissioned, or is in calibration mode, consumption data is held back. data_withheld is then true and the values are 0 (or -1 for hour), as on the Dashboard.

POST command 10 tokens per sensor

Sends a command to one or more sensors (up to 10 per call). GET works too, but POST is recommended because these calls change something.

ParameterRequiredDescription
actionYesOne of the actions below
device_idYes12-character sensor ID, or several separated by commas (A0B1C2D3E4F5,A0B1C2D3E4F6). In JSON it can also be a list.
actionWhat it doesWho may use it
buzzSensor beeps and blinks for a few seconds, to help you find itSociety admins, or members of the unit the sensor belongs to
blinkSensor blinks its light only (no sound)
valve_closeCloses the valve (stops water)
valve_openOpens the valve. Refused if an admin closed it, or if water rationing closed it and the unit's limit is used up.
valve_admin_closeCloses the valve and locks it, so valve_open cannot open itSociety admins only
valve_admin_openOpens the valve and removes the admin lock
rebootRestarts the sensor

The API applies the same permissions as the website. What you may do depends on the account that owns the key. If the society admin has turned off device commands for the society, commands are refused with COMMANDS_DISABLED.

curl -X POST "https://jalmiti.com/society/api/v1/command/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  --data-urlencode "soc_id=YOUR_SOCIETY_ID" \
  --data-urlencode "user=you@example.com" \
  --data-urlencode "action=valve_close" \
  --data-urlencode "device_id=A0B1C2D3E4F5,A0B1C2D3E4F6,A0B1C2D3E4F7"
{
  "success": true,
  "endpoint": "command",
  "soc_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tokens_consumed": 10,
  "tokens_remaining": 9770,
  "next_call_after": "2026-11-16T11:30:00+05:30",
  "data": {
    "action": "valve_close",
    "queued": 1,
    "results": [
      { "device_id": "A0B1C2D3E4F5", "unit": "A101", "inlet": "Kitchen",  "result": "queued", "transport": "wifi" },
      { "device_id": "A0B1C2D3E4F6", "unit": "A101", "inlet": "Bathroom", "result": "already_done", "reason": "valve already closed" },
      { "device_id": "A0B1C2D3E4F7", "unit": "A102", "inlet": "Kitchen",  "result": "rejected", "reason": "no valve installed on this sensor" }
    ]
  }
}
resultMeaningTokens
queuedThe command was sent to the sensor (transport: wifi or lora)10
already_doneThe valve is already in the requested state, so nothing was sent0
rejectedNot sent; reason says why (no valve, sensor offline, valve locked by an admin, …)0
queued means the command was sent, not that the sensor has confirmed it. A sensor that is out of range may miss it. To check the outcome, call status after a minute and look at flow_off and last_seen. The call needs enough tokens for every sensor listed, but you are charged only for the ones that were queued.

5. Response format

A successful call returns HTTP 200:

FieldMeaning
successtrue
endpointThe endpoint you called
soc_idYour Society ID
tokens_consumedTokens this call used
tokens_remainingTokens left on the key
next_call_afterEarliest time your next call will be accepted (see call interval)
dataThe result, as described for each endpoint
warningsOnly present when there is something to warn about (see below)

Warnings

While your society's installation is not yet commissioned, calls made before the call interval has passed are accepted so you can build and test your integration. They are not rejected with SCI_VIOLATION. The response then contains a warning:

"warnings": [
  {
    "code": "SCI_VIOLATION",
    "message": "Called before the successive call interval of 900 s. Allowed because the society installation is not yet commissioned; it will be rejected after commissioning.",
    "retry_after_sec": 412
  }
]

These calls still use tokens. Once the installation is commissioned, the same calls are rejected, so treat this warning as a bug in your call schedule.

6. Errors

A rejected call returns an HTTP error status and this body. Rejected calls never use tokens, and they do not restart the call interval.

{
  "success": false,
  "error_code": "SCI_VIOLATION",
  "error": "Called before the successive call interval of 900 s.",
  "retry_after_sec": 412
}
HTTPerror_codeCauseWhat to do
401KEY_MISMATCHThe key, Society ID or user is missing, wrong, or does not belong together. Also returned if the key owner is no longer the society's Super Admin.Check the three values on the API Access page.
429SCI_VIOLATIONCalled before the interval between successive calls has passed. While the installation is not yet commissioned, the call is accepted with a warning instead.Wait retry_after_sec seconds (also sent in the Retry-After header).
402TOKENS_EXHAUSTEDNot enough tokens left for this call. tokens_remaining is included.Contact us to top up.
403KEY_EXPIREDThe key's validity has endedRenew the key on the API Access page.
403API_DISABLEDAPI access is turned off for this societyContact us.
403NOT_PERMITTEDcommand: the key owner may not perform this action on one of the listed sensors. Nothing is sent to any of them.Use an account with the right role, or remove that sensor from the list.
403COMMANDS_DISABLEDcommand: the society admin has turned off device commandsAsk your society admin.
400SENSOR_NOT_SUPPORTEDThe sensor you asked for is not available through the API yet (the error text lists what is)Use an available sensor, such as WM.0.
400BAD_REQUESTA parameter is missing or badly formatted (the error text says which)Fix the request.
404NOT_FOUND / UNKNOWN_ENDPOINTThe unit, inlet or sensor is not in your society, or the endpoint name is wrongCheck the names on your Dashboard.
405METHOD_NOT_ALLOWEDA method other than GET or POST was usedUse GET or POST.
500SERVER_ERRORSomething went wrong on our sideTry again later. No tokens were used.

7. Tokens, call interval and validity

  • Tokens: every successful call uses the number of tokens listed for its endpoint. A key starts with the number of tokens set for your society (for example, 10,000). Tokens are not refilled automatically.
  • Successive call interval: you chose this when you created the key (for example, from 2 minutes to 24 hours). It applies to the key as a whole, across all endpoints, and is counted from your last successful call. next_call_after in every response tells you when you can call next.
  • Validity: also chosen at creation (for example, from 1 day to 1 year). After that the key is rejected with KEY_EXPIRED.

Your society's exact limits are shown on the API Access page.

Plan your calls. One day call (5 tokens) returns all 24 hours. That is cheaper than one hour call (10 tokens), and you only have to wait for the interval once. In the same way, status with scope=unit covers every sensor of a unit in one call.

8. Code examples

Python (requests)

import time
import requests

BASE = "https://jalmiti.com/society/api/v1/"
AUTH = {"soc_id": "YOUR_SOCIETY_ID", "user": "you@example.com"}
HEADERS = {"X-Api-Key": "YOUR_API_KEY"}


def call(endpoint, **params):
    r = requests.get(BASE + endpoint + "/", params=dict(AUTH, **params), headers=HEADERS, timeout=60)
    body = r.json()
    if r.status_code == 429:                      # Too early: wait and retry once
        time.sleep(body["retry_after_sec"])
        r = requests.get(BASE + endpoint + "/", params=dict(AUTH, **params), headers=HEADERS, timeout=60)
        body = r.json()
    if not body["success"]:
        raise RuntimeError(body["error_code"] + ": " + body["error"])
    return body


# Plain values: requests URL-encodes "@" and spaces itself (AUTH["user"] = "you@example.com")
res = call("month", units="A101,A102", month="2026-10")
print("Tokens left:", res["tokens_remaining"])
for day, liters in enumerate(res["data"]["totals"], start=1):
    print(day, liters)

# Later (after the call interval): one inlet whose name has a space
res = call("day", units="A101", inlet="Master Bath", date="2026-11-15")

JavaScript (Node.js 18+)

const BASE = "https://jalmiti.com/society/api/v1/";

const params = new URLSearchParams({
  soc_id: "YOUR_SOCIETY_ID",
  user: "you@example.com",
  units: "A101",
  date: "2026-11-15",
});

const res = await fetch(BASE + "day/?" + params, {
  headers: { "X-Api-Key": process.env.JALMITI_API_KEY },
});
const body = await res.json();
if (!body.success) throw new Error(body.error_code + ": " + body.error);
console.log(body.data.totals);   // 24 hourly liters

POST with JSON

curl -X POST "https://jalmiti.com/society/api/v1/year/" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soc_id": "YOUR_SOCIETY_ID", "user": "you@example.com", "units": ["A101", "A102"], "year": "2026"}'

9. Good practice

  • Keep the key secret. Call the API only from your server or a trusted script. Never put the key in a web page, a mobile app or a shared spreadsheet.
  • Send the key in the X-Api-Key header instead of the URL, so it does not end up in logs or browser history.
  • If you think the key has leaked, click Rotate key on the API Access page straight away.
  • Schedule calls no more often than your call interval, and use next_call_after or retry_after_sec instead of retrying in a loop.
  • Watch tokens_remaining and ask for a top-up before it runs out.

Questions? Contact us.