Quickstart
From no key to a bill in your group in about five minutes. Every step has curl, JavaScript (Node 18 or later, no packages) and Python (with requests).
1. Make a key in the app#
- Open Dimesum and go to Me › Profile › Developer.
Choose Create key, give it a name you will recognise later ("Sheets sync", "Siri"), and pick a scope:
- Read can call every GET.
- Read and write can also add, edit and delete bills, comment and record payments.
- Copy the key. It starts with
dms_live_and is shown once: Dimesum stores only a hash of it, so it cannot show it again. If you lose it, regenerate it.
Start with a read-only key while you explore; making a second scope later means regenerating or deleting this one, because an account has one live key.
2. Put the key in an environment variable#
Your code reads the key from the environment, so it never sits in a file you might commit.
export DIMESUM_API_KEY="dms_live_..."3. Your first call#
GET /v1/me returns the account the key belongs to.
curl https://api.dimesum.com/v1/me \
-H "Authorization: Bearer $DIMESUM_API_KEY"const API = "https://api.dimesum.com";
const headers = { Authorization: `Bearer ${process.env.DIMESUM_API_KEY}` };
const me = await fetch(`${API}/v1/me`, { headers }).then((r) => r.json());
console.log(me.display_name, me.preferred_currency);import os
import requests
API = "https://api.dimesum.com"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DIMESUM_API_KEY']}"
me = session.get(f"{API}/v1/me").json()
print(me["display_name"], me["preferred_currency"]){
"id": "0192f39e-2a4b-7c6d-8e0f-1a2b3c4d5e6f",
"display_name": "Asha",
"email": "asha@example.com",
"timezone": "Asia/Kolkata",
"preferred_currency": "INR"
}A 401 here means the key is wrong, deleted or switched off; the error code says which.
4. List your groups#
GET /v1/groups lists every group you are in. your_position is your net in each currency: positive means the group owes you.
curl https://api.dimesum.com/v1/groups \
-H "Authorization: Bearer $DIMESUM_API_KEY"const { groups } = await fetch(`${API}/v1/groups`, { headers }).then((r) => r.json());
for (const g of groups) console.log(g.id, g.name, g.your_position);groups = session.get(f"{API}/v1/groups").json()["groups"]
for g in groups:
print(g["id"], g["name"], g["your_position"])Then read one group with GET /v1/groups/{groupID}. Its members carry the member ids that bills use to name who paid and who shares, and my_member_id is you.
GROUP_ID="0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
curl https://api.dimesum.com/v1/groups/$GROUP_ID \
-H "Authorization: Bearer $DIMESUM_API_KEY"const groupId = groups[0].id;
const group = await fetch(`${API}/v1/groups/${groupId}`, { headers }).then((r) => r.json());
console.log(group.my_member_id, group.members.map((m) => `${m.display_name}: ${m.id}`));group_id = groups[0]["id"]
group = session.get(f"{API}/v1/groups/{group_id}").json()
print(group["my_member_id"], [(m["display_name"], m["id"]) for m in group["members"]])5. Add a bill#
This needs a read and write key. POST /v1/groups/{groupID}/expenses takes:
id: a UUID you generate. It is the write's idempotency key: if the network drops and you send the same request again, you get the same bill back (200) instead of a second one.description: up to 120 characters.amount_minor: the amount in the currency's minor unit. ₹1,200.00 is120000paise; ¥1,200 is1200because yen has no minor unit (Money).
Leave out participants and it is split equally among everyone in the group; leave out payers and you paid all of it. The currency defaults to the group's; a bill in another currency stays in it unless you send convert_to (Currencies).
curl https://api.dimesum.com/v1/groups/$GROUP_ID/expenses \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR"
}
EOF// UUIDv7: time-ordered, so ids sort by when you made them. Any UUID works.
function uuidv7() {
const b = crypto.getRandomValues(new Uint8Array(16));
let ms = Date.now();
for (let i = 5; i >= 0; i--) { b[i] = ms % 256; ms = Math.floor(ms / 256); }
b[6] = (b[6] & 0x0f) | 0x70;
b[8] = (b[8] & 0x3f) | 0x80;
const h = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
}
const bill = {
id: uuidv7(),
description: "Dinner at Thalassa",
amount_minor: 120000,
currency: "INR",
};
const res = await fetch(`${API}/v1/groups/${groupId}/expenses`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify(bill),
});
console.log(res.status, await res.json()); // 201 the first time, 200 on a retryimport time, uuid
def uuid7() -> str:
"""Time-ordered UUID (Python 3.14 has uuid.uuid7()). Any UUID works."""
b = bytearray(int(time.time() * 1000).to_bytes(6, "big") + os.urandom(10))
b[6] = (b[6] & 0x0F) | 0x70
b[8] = (b[8] & 0x3F) | 0x80
return str(uuid.UUID(bytes=bytes(b)))
bill = {
"id": uuid7(),
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
}
r = session.post(f"{API}/v1/groups/{group_id}/expenses", json=bill)
print(r.status_code, r.json()) # 201 the first time, 200 on a retryTo split with some people only, name them with participants (member ids). To split unevenly, set split_type to EXACT, PERCENT or SHARES with shares, percents or weights; see ExpenseCreate.
Keep the id with the thing it came from
If your script adds bills from rows, messages or events, derive the id from that source (the row, the message id) or store it next to it. Then a re-run replays the same writes instead of doubling them. The Sheets recipe does exactly that.
6. Read balances#
GET /v1/groups/{groupID}/balances gives each member's balance per currency. Positive: the group owes them. Negative: they owe the group. Balances in different currencies are never added together.
curl https://api.dimesum.com/v1/groups/$GROUP_ID/balances \
-H "Authorization: Bearer $DIMESUM_API_KEY"const { balances } = await fetch(`${API}/v1/groups/${groupId}/balances`, { headers }).then((r) => r.json());
for (const m of balances)
for (const b of m.balances)
console.log(m.display_name, b.currency, b.balance_minor > 0 ? "is owed" : "owes", Math.abs(b.balance_minor));balances = session.get(f"{API}/v1/groups/{group_id}/balances").json()["balances"]
for m in balances:
for b in m["balances"]:
verb = "is owed" if b["balance_minor"] > 0 else "owes"
print(m["display_name"], b["currency"], verb, abs(b["balance_minor"]))For every group at once, use GET /v1/me/balances.
A balance can lag a write by a moment
A bill returns as soon as it is stored; the balances move a fraction of a second later. If you read balances straight after writing, allow for the previous figures, or read again.