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: try it with your own values
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.
| (for example A101|A102)
WM.0 = water meter (more)
status and command
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.
- Log in and open the Society page.
- Click API Access.
- Solve the captcha. An OTP is then sent to your registered mobile number and/or email.
- 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).
- 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,
The API key is 48 letters and digits long. You need three values on every call:
| Value | Where to find it | Sent as |
|---|---|---|
| API key | API Access page | Header X-Api-Key (recommended) or parameter api_key |
| Society ID | API Access page | Parameter soc_id |
| User | Your login name or email | Parameter 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.
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.
| Character | Write it as | Example value | In the URL |
|---|---|---|---|
@ | %40 | you@example.com | user=you%40example.com |
| space | %20 (or +) | Master Bath | inlet=Master%20Bath |
+ | %2B | A+B Wing | units=A%2BB%20Wing (an unencoded + is read as a space) |
& | %26 | Bath & Utility | inlet=Bath%20%26%20Utility |
# | %23 | Flat #12 | units=Flat%20%2312 |
/ | %2F | A/101 | units=A%2F101 |
= ? % | %3D %3F %25 | ||
| | %7C | A101|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"}'
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 want | Parameters |
|---|---|
| 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 unit | units=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 from0. Give several numbers to get several sensors of the same type at once.
| Example | Meaning | Available |
|---|---|---|
sensor=WM.0 | Water meter, first (and usually only) one | Yes (default) |
sensor=TP.0, sensor=TP.1 | First / second temperature sensor | Later |
sensor=VR.0.1.2 | Voltage sensors 0, 1 and 2, i.e. all three phases | Later |
sensor=PP.0 | Pipe pressure | Later |
sensor=WL.0 | Water level | Later |
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).
| Endpoint | Parameters (besides authentication) | Returns | Tokens |
|---|---|---|---|
status | scope=sensor&device_id=… | Status of one sensor | 10 |
status | scope=unit&unit=… | Status of all sensors of a unit | 100 |
status | scope=society | Status of all sensors of the society | 1000 |
hour | <ENTITY> date=YYYY-MM-DD&hour=0..23 | Liters used in that hour | 10 |
day | <ENTITY> date=YYYY-MM-DD | Liters for each of the 24 hours | 5 |
month | <ENTITY> month=YYYY-MM | Liters for each day of the month | 2 |
year | <ENTITY> year=YYYY | Liters for each of the 12 months | 2 |
command | action=…&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.
| Parameter | Required | Description |
|---|---|---|
scope | Yes | sensor, unit or society |
device_id | For sensor | The 12-character sensor ID printed on the device (for example A0B1C2D3E4F5; : and - are ignored) |
unit | For unit | Unit 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"
}
]
}
}
| Field | Meaning |
|---|---|
last_seen, seconds_since_seen | When the sensor last reported. null if it has not reported recently. |
online | true if the sensor reported within the society's inactivity timeout (inactivity_timeout_sec) |
is_leaking | true if the sensor's last report flagged a possible leak (continuous flow) |
signal | Radio signal strength in the sensor's last report |
pkt_num | The sensor's report counter. If it jumps, reports were missed. |
health | Ok, NOT Ok or Device Banned |
valve_installed, flow_off | Whether 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.
- 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_withheldis thentrueand the values are0(or-1forhour), 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.
| Parameter | Required | Description |
|---|---|---|
action | Yes | One of the actions below |
device_id | Yes | 12-character sensor ID, or several separated by commas (A0B1C2D3E4F5,A0B1C2D3E4F6). In JSON it can also be a list. |
action | What it does | Who may use it |
|---|---|---|
buzz | Sensor beeps and blinks for a few seconds, to help you find it | Society admins, or members of the unit the sensor belongs to |
blink | Sensor blinks its light only (no sound) | |
valve_close | Closes the valve (stops water) | |
valve_open | Opens the valve. Refused if an admin closed it, or if water rationing closed it and the unit's limit is used up. | |
valve_admin_close | Closes the valve and locks it, so valve_open cannot open it | Society admins only |
valve_admin_open | Opens the valve and removes the admin lock | |
reboot | Restarts 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" }
]
}
}
result | Meaning | Tokens |
|---|---|---|
queued | The command was sent to the sensor (transport: wifi or lora) | 10 |
already_done | The valve is already in the requested state, so nothing was sent | 0 |
rejected | Not 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:
| Field | Meaning |
|---|---|
success | true |
endpoint | The endpoint you called |
soc_id | Your Society ID |
tokens_consumed | Tokens this call used |
tokens_remaining | Tokens left on the key |
next_call_after | Earliest time your next call will be accepted (see call interval) |
data | The result, as described for each endpoint |
warnings | Only 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
}
| HTTP | error_code | Cause | What to do |
|---|---|---|---|
| 401 | KEY_MISMATCH | The 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. |
| 429 | SCI_VIOLATION | Called 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). |
| 402 | TOKENS_EXHAUSTED | Not enough tokens left for this call. tokens_remaining is included. | Contact us to top up. |
| 403 | KEY_EXPIRED | The key's validity has ended | Renew the key on the API Access page. |
| 403 | API_DISABLED | API access is turned off for this society | Contact us. |
| 403 | NOT_PERMITTED | command: 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. |
| 403 | COMMANDS_DISABLED | command: the society admin has turned off device commands | Ask your society admin. |
| 400 | SENSOR_NOT_SUPPORTED | The 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. |
| 400 | BAD_REQUEST | A parameter is missing or badly formatted (the error text says which) | Fix the request. |
| 404 | NOT_FOUND / UNKNOWN_ENDPOINT | The unit, inlet or sensor is not in your society, or the endpoint name is wrong | Check the names on your Dashboard. |
| 405 | METHOD_NOT_ALLOWED | A method other than GET or POST was used | Use GET or POST. |
| 500 | SERVER_ERROR | Something went wrong on our side | Try 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_afterin 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.
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-Keyheader 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_afterorretry_after_secinstead of retrying in a loop. - Watch
tokens_remainingand ask for a top-up before it runs out.
Questions? Contact us.