dimesumdevelopers API reference Console Open the app

Recipes

Eleven automations that take the typing out of shared money. Each one says what scope its key needs and what it cannot do, and each has code you can paste.

RecipeKey scopeRuns on
Move your history in: hand an AI your spreadsheet or exportread + writeClaude (MCP) or any assistant that runs code
Log a bill with Siri or the share sheetread + writeiPhone, iPad, Mac
Bank or UPI SMS to a suggestionread + writeAndroid
Google Sheets: pull every bill, push rows as billsread (pull), read + write (push)Google Apps Script
Rent and subscriptionsread + writeone API call
A chat bot that answers "who owes whom"readTelegram or Slack
n8n, Zapier or Make: a webhook that adds billsread + writeyour automation tool
Nightly backup to JSON and CSVreadany machine with Python
Claude as your expense assistantread, then read + writeClaude Desktop or Claude Code
Reconcile a bank statement against paymentsreadPython
A household dashboardreadGrafana or Notion

Every recipe below keeps the key in a secret store or an environment variable, never in the code. See Keeping the key secret.

Move your history in: hand an AI your spreadsheet or export#

Saves: re-typing months of shared expenses. A flat's year of groceries and bills is a few hundred rows; an assistant with your key reads the file, shows you the plan, and adds every row with its real date, payer and split while you do something else.

Needs: a read and write key (Me › Developer), the file (a Google Sheet or Excel export, a bank statement, or another app's CSV export, such as Splitwise's Export as spreadsheet), and one of:

  • Claude Desktop or any MCP client, connected to Dimesum as in the MCP guide. The assistant uses create_group, add_member and add_expense (with shares for uneven splits and occurred_on for the date).
  • An assistant that writes and runs code (Claude Code, or any assistant with a terminal). It reads this page and the API reference and writes a short script against the REST API.

The prompt#

Paste this, attach the file, and fill in the two blanks. Keep the key out of the chat when you can: MCP clients hold it in their own config, and a script should read it from DIMESUM_API_KEY.

Text
I want to move my shared-expense history into Dimesum.
Docs: https://developers.dimesum.com/recipes.html#import-with-ai
API reference: https://developers.dimesum.com/reference.html

The attached file is my history. Group name to use: ______
Currency, if the file does not say: ______

Please:
1. Read the file and tell me which columns hold the date, what it was, the
   amount, the currency, who paid, and how it was split. Ask me if unsure.
2. Find my group with list_groups (or create it with create_group). Match
   every person in the file to a member from get_group; for anyone missing,
   list them and add them with add_member only after I say yes.
3. Show me a dry run first: a table of the first 20 rows as you will send
   them (date, description, amount, payer, each person's share), plus the
   total count and the total amount per currency. Wait for my OK.
4. Then add every row with add_expense: occurred_on = the row's date, the
   payer as paid_by_member_id, and shares for any split that is not equal.
   Use idempotency_key = the row number plus the date, so running again
   never adds a row twice.
5. Skip rows that are payments between people (Splitwise marks them
   "Payment"), and list them for me instead of adding them as bills.
6. Go slowly: no more than 2 calls a second. If a call fails, note the row
   and the error and carry on. At the end, show what was added, what was
   skipped and why, and my balances with get_my_balances.

What it does, and what it will not do#

  • It never guesses who paid. A row with no payer is asked about, not assigned to you.
  • Every share is exact. For an uneven split the shares must add up to the amount to the last paisa or cent; the API refuses anything else (400), so a rounding slip is caught before it becomes somebody's debt.
  • A re-run is safe. The same idempotency key replays the first write instead of adding a copy, so an import that stopped halfway can simply be run again.
  • Payments stay yours to record. A settlement in your history was confirmed by a person; the prompt lists those rows rather than recording them on anyone's behalf. Record the ones you want from the app, or with record_payment, which dates them today.
  • People you add are kept places. Anyone new becomes a named seat in the group. Share the group's invite link and they claim their seat with its balance intact.
  • Speed. A key allows 2 calls a second with bursts of 30 (rate limits), so 500 rows take about five minutes.

Splitwise's export, specifically. Its CSV has Date, Description, Category, Cost, Currency, then one column per person holding that person's net for the row (positive: they paid more than their share). When exactly one person is positive, they paid the whole cost. Their share is the cost minus their figure; everyone else's share is their own figure without its minus sign. A row of ₹900 where Asha shows +600 and Ravi and Kabir show −300 each is Asha paying ₹900 with ₹300 shares all round. Rows with the category Payment are settlements (see above). The prompt above handles both; tell the assistant the file came from Splitwise.

Log a bill with Siri or the share sheet#

Saves: opening the app, finding the group, typing the amount. Say "Hey Siri, split 450 for lunch" at the counter and it is in the group before you sit down.

Needs: a read and write key, your group's id (from GET /v1/groups or the console), and the Shortcuts app.

The shortcut calls the MCP tool add_expense over plain HTTP. That tool takes the amount as the number you said ("450"), fills in the group's currency, splits it among everyone and marks you as the payer, so the shortcut needs no arithmetic and no UUID.

Build it#

In Shortcuts, create a new shortcut named Split (the name is what you say to Siri) and add these actions:

  1. Dictate Text. Siri hears "450 for lunch".
  2. Get Numbers from Input with the dictated text. Then Get Item from List, first item: this is the amount.
  3. Replace Text on the dictated text: find ^\s*[\d.,]+\s*(for\s+)? with Regular Expression on, replace with nothing. This leaves "lunch" as the description.
  4. Show Alert: "Add ₹[Amount] for [Description] to the flat, split with everyone?" with Show Cancel Button on. This is your confirmation; nothing is sent if you cancel.
  5. Format Date on Current Date with the custom format yyyyMMdd-HHmmss. This becomes the idempotency key, so if Shortcuts retries the request, the bill is not added twice.
  6. Get Contents of URL:

    • URL: https://api.dimesum.com/mcp
    • Method: POST
    • Headers: Authorization = Bearer dms_live_… and Content-Type = application/json
    • Request Body: JSON, with the fields in the request below. Set params as a Dictionary and arguments inside it as a Dictionary, with amount and description taken from steps 2 and 3 as Text and idempotency_key from step 5.
  7. Get Dictionary Value result, then Get Dictionary Value isError. Add an If on it to Show Notification "Added" or "Dimesum refused it".

The request the shortcut sends:

JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_expense",
    "arguments": {
      "group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
      "amount": "450",
      "description": "lunch",
      "idempotency_key": "siri-20260928-131502"
    }
  }
}

To split with some people only, add participant_member_ids (member ids from GET /v1/groups/{groupID}). To pick the group each time, put a Choose from Menu before step 6 with one item per group, each setting a group_id variable.

The key lives in the shortcut

Anyone you share the shortcut with gets your key. Share the steps, not the shortcut file; if you do share it by mistake, regenerate the key.

From the share sheet: an order or a message into a draft#

Shared text (a food order confirmation, a forwarded message) often has several numbers in it, so this variant hands the whole text to POST /v1/captures, which reads it into a suggestion that waits in the app's inbox until you confirm it. Nothing is posted by the shortcut.

  1. Create a shortcut, open its details and turn on Show in Share Sheet, accepting Text.
  2. Shortcuts has no UUID action, and any 8-4-4-4-12 string of hex digits is a valid id, so build one from random numbers: four Random Number actions (10000000 to 99999999, then 1000 to 9999 three times) and one more (100000000000 to 999999999999), joined in a Text action as A-B-C-D-E.
  3. Get Contents of URL: POST https://api.dimesum.com/v1/captures with the same two headers and a JSON body:
JSON
{
  "id": "48213377-5120-8841-3907-615532087713",
  "group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
  "text": "Your order from Paradise: 2x Biryani ₹640, delivery ₹40, total ₹680"
}

Reading the text needs the server's parser. Without it you still get a suggestion, with the text as its name and the amount blank for you to fill in on confirm (Captures).

Bank or UPI SMS to a suggestion#

Saves: going through a month of bank messages to remember what the shared card paid for. Every debit on the shared card becomes a draft bill in the right group, and you confirm or dismiss each with one tap.

Needs: a read and write key, Android with Tasker (or Automate, below), and the parser on the server (see the note at the end).

Nothing posts on its own: the SMS becomes a suggestion through POST /v1/captures, and a person confirms it in the app (or with POST /v1/suggestions/{suggestionID}/confirm).

Tasker#

  1. Store the key: Tasks › + › Variables › Variable Set, %DIMESUM_KEY to your key (a global variable, kept on the phone).
  2. Profile › Event › Phone › Received Text. Set Sender to your bank's sender id (for example *HDFCBK*) and Content to a word only debit messages have, such as *debited*. Filter tightly: this is what stops one-time passwords and other messages from ever leaving the phone.
  3. The task, Action 1: Code › JavaScriptlet:
JavaScript
// Deterministic id from the message itself: if Tasker fires twice for one SMS,
// the second capture replays the first instead of making a second draft.
var sms = global('SMSRB');
var seed = global('SMSRF') + '|' + global('SMSRD') + '|' + global('SMSRT') + '|' + sms;
function h32(s, salt) {
  var x = 0x811c9dc5 ^ salt;
  for (var i = 0; i < s.length; i++) { x ^= s.charCodeAt(i); x = Math.imul(x, 0x01000193) >>> 0; }
  return ('0000000' + x.toString(16)).slice(-8);
}
var hex = h32(seed, 1) + h32(seed, 2) + h32(seed, 3) + h32(seed, 4);
var id = hex.slice(0, 8) + '-' + hex.slice(8, 12) + '-' + hex.slice(12, 16) + '-' + hex.slice(16, 20) + '-' + hex.slice(20, 32);
var body = JSON.stringify({
  id: id,
  group_id: '0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01',
  text: sms
});
  1. Action 2: Net › HTTP Request:

    • Method: POST
    • URL: https://api.dimesum.com/v1/captures
    • Headers: Authorization:Bearer %DIMESUM_KEY and Content-Type:application/json (one per line)
    • Body: %body
  2. Optional Action 3: Alert › Notify when %http_response_code is not 201 or 200, with %http_data as the text, so you notice a refusal.

The draft arrives in the app's inbox. From a script, GET /v1/suggestions lists what is waiting.

Automate#

In LlamaLab Automate the flow is SMS received (with the same sender and content filters) → Expression true? to skip anything that is not a debit → HTTP request with the same method, URL, headers and a body of jsonEncode({"id": …, "group_id": "…", "text": sms}), building the id as above.

What happens to the text

The SMS text is sent to Dimesum and read by its parser, which masks phone numbers, email addresses and UPI ids before the text reaches the language model that reads it. Without the parser configured, you get a suggestion with the SMS as its name and the amount blank for you to fill in.

Google Sheets: pull every bill, push rows as bills#

Saves: copying bills into a spreadsheet for the monthly budget, and typing a batch of receipts into the app one by one.

Needs: a read key to pull; a read and write key to push. Both scripts run in Google Apps Script, so the key lives in the script's properties, not in the sheet.

Open the sheet, Extensions › Apps Script, then Project Settings › Script Properties and add DIMESUM_API_KEY and GROUP_ID. Paste this into Code.gs:

Code.gs
const API = "https://api.dimesum.com";
const props = PropertiesService.getScriptProperties();

function call_(method, path, body) {
  const res = UrlFetchApp.fetch(API + path, {
    method: method,
    contentType: "application/json",
    headers: { Authorization: "Bearer " + props.getProperty("DIMESUM_API_KEY") },
    payload: body ? JSON.stringify(body) : undefined,
    muteHttpExceptions: true,
  });
  const code = res.getResponseCode();
  const json = res.getContentText() ? JSON.parse(res.getContentText()) : null;
  if (code === 429) { Utilities.sleep(2000); return call_(method, path, body); }
  return { code: code, json: json };
}

const EXPONENT = {
  BIF: 0, CLP: 0, DJF: 0, GNF: 0, ISK: 0, JPY: 0, KMF: 0, KRW: 0,
  PYG: 0, RWF: 0, UGX: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
  BHD: 3, IQD: 3, JOD: 3, KWD: 3, LYD: 3, OMR: 3, TND: 3,
};
const exp_ = (c) => (c in EXPONENT ? EXPONENT[c] : 2);

// Pull: every bill of the group into the "Bills" tab, newest first.
function pullBills() {
  const groupId = props.getProperty("GROUP_ID");
  const group = call_("get", "/v1/groups/" + groupId).json;
  const names = {};
  group.members.forEach((m) => (names[m.id] = m.display_name));

  const rows = [["Date", "Description", "Amount", "Currency", "Paid by", "My share", "Deleted", "Id", "Version"]];
  let cursor = "";
  do {
    const page = call_("get", "/v1/groups/" + groupId + "/expenses?limit=100" + (cursor ? "&cursor=" + encodeURIComponent(cursor) : "")).json;
    page.expenses.forEach((e) => {
      const unit = Math.pow(10, exp_(e.currency));
      const payers = e.splits.filter((s) => s.paid_minor > 0).map((s) => names[s.member_id] || "?").join(", ");
      const mine = e.splits.find((s) => s.member_id === group.my_member_id);
      rows.push([e.occurred_on, e.description, e.amount_minor / unit, e.currency, payers,
                 mine ? mine.share_minor / unit : 0, e.deleted, e.id, e.version]);
    });
    cursor = page.next_cursor || "";
    Utilities.sleep(500);
  } while (cursor);

  const sheet = SpreadsheetApp.getActive().getSheetByName("Bills") || SpreadsheetApp.getActive().insertSheet("Bills");
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

// Run once: pull on the 1st of every month at about 6am.
function installMonthlyPull() {
  ScriptApp.newTrigger("pullBills").timeBased().onMonthDay(1).atHour(6).create();
}

// Push: each row of the "To add" tab becomes a bill.
// Columns: A Date (YYYY-MM-DD) | B Description | C Amount (e.g. 1200.50)
//          D Currency | E Id (the script fills it) | F Status (the script fills it)
function pushRows() {
  const groupId = props.getProperty("GROUP_ID");
  const sheet = SpreadsheetApp.getActive().getSheetByName("To add");
  const data = sheet.getDataRange().getValues();
  for (let r = 1; r < data.length; r++) {
    const [date, description, amount, currency, storedId, status] = data[r];
    if (!description || !amount || status === "added") continue;
    // The id comes from the sheet and the row, so pressing Run twice replays
    // instead of adding twice. It is written back, so sorting later is safe.
    const id = storedId || rowId_(sheet, r + 1);
    const cur = String(currency || "INR").toUpperCase();
    const minor = Math.round(Number(amount) * Math.pow(10, exp_(cur)));
    const res = call_("post", "/v1/groups/" + groupId + "/expenses", {
      id: id,
      description: String(description).slice(0, 120),
      amount_minor: minor,
      currency: cur,
      occurred_on: Utilities.formatDate(new Date(date), Session.getScriptTimeZone(), "yyyy-MM-dd"),
    });
    const outcome = res.code === 201 || res.code === 200 ? "added"
      : res.code === 409 ? "changed after adding: edit it in the app"
      : "refused: " + (res.json && res.json.error ? res.json.error.code : res.code);
    sheet.getRange(r + 1, 5, 1, 2).setValues([[id, outcome]]);
    Utilities.sleep(600);
  }
}

function rowId_(sheet, row) {
  const seed = SpreadsheetApp.getActive().getId() + ":" + sheet.getSheetId() + ":" + row;
  const hex = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5, seed)
    .map((b) => ((b + 256) % 256).toString(16).padStart(2, "0")).join("");
  return [hex.slice(0, 8), hex.slice(8, 12), "7" + hex.slice(13, 16), "8" + hex.slice(17, 20), hex.slice(20, 32)].join("-");
}

Run pullBills once to grant access, then installMonthlyPull. For pushing, fill rows in To add and run pushRows.

  • Why ids from row numbers: a re-run of the same row sends the same id, so the API replays it (200) rather than adding a duplicate. The id is written into column E the first time, so after that the row keeps its id even if you sort the sheet. Before the first run, add rows only at the bottom.
  • If you change a row after it was added, the same id now carries different content and the API answers 409 idempotency_conflict. The script marks the row; change the bill in the app instead.
  • Math.round(Number(amount) * …) is safe for amounts typed with the right number of decimals; to refuse a mistyped "12.505", use the toMinor helper from Money.
  • The pull reads a page every half second and the push writes a row every 0.6 s, which stays under the rate limit.

Rent and subscriptions#

Saves: adding the same bill every month, and the argument about whether anyone did.

Needs: a read and write key. One call sets it up; after that the server posts the bill every period.

POST /v1/groups/{groupID}/recurring: rent of ₹45,000 on the 1st of every month, split among everyone:

curl
curl https://api.dimesum.com/v1/groups/$GROUP_ID/recurring \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "id": "$(uuidgen)",
  "description": "Rent",
  "amount_minor": 4500000,
  "currency": "INR",
  "freq": "MONTHLY",
  "day_of_month": 1,
  "start_on": "2026-10-01"
}
EOF

A streaming subscription shared by three of the four flatmates, on the 15th:

JSON
{
  "id": "0192f3c2-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
  "description": "Netflix",
  "amount_minor": 64900,
  "freq": "MONTHLY",
  "day_of_month": 15,
  "participants": [
    "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
    "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
    "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d04"
  ]
}
  • day_of_month runs 1 to 28, so every month has the day; rent due on the 30th goes in as the 28th.
  • Weekly? "freq": "WEEKLY" with "weekday" (0 is Sunday).
  • Each period posts an ordinary bill whose id is derived from the repeat and the period, so a period never posts twice. Leave out participants and it is split among whoever is in the group on the day.
  • See the group's repeats with GET /v1/groups/{groupID}/recurring. Pause, resume or change one in the app.

A chat bot that answers "who owes whom"#

Saves: somebody screenshotting the balances into the group chat every weekend.

Needs: a read key. Put the bot only in a chat whose people are all in the group: it shows the group's balances to everyone in the chat.

Telegram#

Create a bot with @BotFather, then run this with Node 18 or later (no packages):

owes-bot.mjs
// BOT_TOKEN, DIMESUM_API_KEY and GROUP_ID come from the environment.
const TG = `https://api.telegram.org/bot${process.env.BOT_TOKEN}`;
const API = "https://api.dimesum.com";
const headers = { Authorization: `Bearer ${process.env.DIMESUM_API_KEY}` };
const EXPONENT = {
  BIF: 0, CLP: 0, DJF: 0, GNF: 0, ISK: 0, JPY: 0, KMF: 0, KRW: 0,
  PYG: 0, RWF: 0, UGX: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
  BHD: 3, IQD: 3, JOD: 3, KWD: 3, LYD: 3, OMR: 3, TND: 3,
};

const money = (minor, cur) => {
  const exp = EXPONENT[cur] ?? 2;
  return new Intl.NumberFormat("en-IN", { style: "currency", currency: cur }).format(Math.abs(minor) / 10 ** exp);
};

async function balancesText() {
  const res = await fetch(`${API}/v1/groups/${process.env.GROUP_ID}/balances`, { headers });
  if (!res.ok) return `Dimesum said ${(await res.json()).error.code}`;
  const lines = [];
  for (const m of (await res.json()).balances)
    for (const b of m.balances) {
      if (b.balance_minor === 0) continue;
      lines.push(`${m.display_name} ${b.balance_minor > 0 ? "is owed" : "owes"} ${money(b.balance_minor, b.currency)}`);
    }
  return lines.length ? lines.join("\n") : "Everyone is square.";
}

let offset = 0;
for (;;) {
  const { result } = await fetch(`${TG}/getUpdates?timeout=50&offset=${offset}`).then((r) => r.json());
  for (const u of result || []) {
    offset = u.update_id + 1;
    const msg = u.message;
    if (!msg?.text?.startsWith("/owes")) continue;
    await fetch(`${TG}/sendMessage`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ chat_id: msg.chat.id, text: await balancesText() }),
    });
  }
}

Type /owes in the chat. Each currency is its own line: a member can be owed rupees and owe yen at once, and the bot never adds them together.

Slack#

A slash command posts a form to your URL and shows what you answer. A Cloudflare Worker is enough; store the key with wrangler secret put DIMESUM_API_KEY and check Slack's signature before answering:

worker.js
export default {
  async fetch(request, env) {
    if (!(await fromSlack(request.clone(), env.SLACK_SIGNING_SECRET))) return new Response("", { status: 401 });
    const res = await fetch(`https://api.dimesum.com/v1/groups/${env.GROUP_ID}/balances`, {
      headers: { Authorization: `Bearer ${env.DIMESUM_API_KEY}` },
    });
    const { balances = [] } = await res.json();
    const lines = balances.flatMap((m) => m.balances.filter((b) => b.balance_minor).map((b) =>
      `${m.display_name} ${b.balance_minor > 0 ? "is owed" : "owes"} ${b.currency} ${(Math.abs(b.balance_minor) / 100).toFixed(2)}`));
    return Response.json({ response_type: "in_channel", text: lines.join("\n") || "Everyone is square." });
  },
};

async function fromSlack(req, secret) {
  const ts = req.headers.get("X-Slack-Request-Timestamp");
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const body = await req.text();
  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`v0:${ts}:${body}`));
  const hex = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
  return `v0=${hex}` === req.headers.get("X-Slack-Signature");
}

The / 100 assumes a currency with two decimals; use the EXPONENT table from the Telegram bot for yen or dinar groups.

n8n, Zapier or Make: a webhook that adds bills#

Saves: writing any code at all. Anything your automation tool can trigger on (a form, an email, a card transaction webhook, a calendar event) can add a bill.

Needs: a read and write key, stored as a credential in the tool.

Call the MCP tool add_expense from the tool's HTTP step. It takes the amount as a decimal ("1200.50"), fills in the currency and your member id, and takes an idempotency_key: pass the trigger's own id (the form response id, the email message id), so a retried run replays instead of adding the bill twice.

n8n#

Add an HTTP Request node after your trigger:

  • Method POST, URL https://api.dimesum.com/mcp
  • Authentication: Generic Credential Type › Header Auth, name Authorization, value Bearer dms_live_…
  • Send Body: JSON, Specify Body: Using JSON:
JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_expense",
    "arguments": {
      "group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
      "description": "{{ $json.description }}",
      "amount": "{{ $json.amount }}",
      "idempotency_key": "{{ $json.id }}"
    }
  }
}

Add an IF node on {{ $json.result.isError }} to route refusals to a notification.

Zapier#

Use Webhooks by Zapier › Custom Request: method POST, URL https://api.dimesum.com/mcp, headers Authorization: Bearer dms_live_… and Content-Type: application/json, and the same JSON as the data, mapping the trigger's fields into description, amount and idempotency_key.

Make#

Use HTTP › Make a request with the same URL, method, headers and body (Body type Raw, content type JSON (application/json)), and Parse response on.

To use REST instead of MCP, POST to POST /v1/groups/{groupID}/expenses with amount_minor (convert with the currency's exponent) and an id that is a UUID derived from the trigger, for example n8n's {{ $execution.id }} hashed into UUID form.

Nightly backup to JSON and CSV#

Saves: trusting any one app with years of shared history. A nightly copy of every group, bill, payment and repeat, in files you own.

Needs: a read key, Python 3.9 or later with requests.

dimesum_backup.py
"""Back up every Dimesum group you are in: one JSON file per night, plus a CSV of bills."""
import csv, datetime, json, os, pathlib, time
import requests

API = "https://api.dimesum.com"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['DIMESUM_API_KEY']}"

def get(path, **params):
    for attempt in range(5):
        r = s.get(API + path, params=params, timeout=30)
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", "2")))
            continue
        r.raise_for_status()
        time.sleep(0.5)  # stay under 2 requests a second
        return r.json()
    raise RuntimeError(f"gave up on {path}")

def pages(path, key, **params):
    cursor = None
    while True:
        page = get(path, **params, **({"cursor": cursor} if cursor else {}))
        yield from page.get(key, [])
        cursor = page.get("next_cursor")
        if not cursor:
            return

out = pathlib.Path(os.environ.get("BACKUP_DIR", "dimesum-backups"))
out.mkdir(parents=True, exist_ok=True)
stamp = datetime.date.today().isoformat()

backup = {"taken_at": datetime.datetime.now(datetime.timezone.utc).isoformat(), "me": get("/v1/me"), "groups": []}
for row in get("/v1/groups")["groups"]:
    gid = row["id"]
    backup["groups"].append({
        "group": get(f"/v1/groups/{gid}"),
        "balances": get(f"/v1/groups/{gid}/balances")["balances"],
        "expenses": list(pages(f"/v1/groups/{gid}/expenses", "expenses", limit=100)),
        "settlements": list(pages(f"/v1/groups/{gid}/settlements", "settlements")),
        "recurring": get(f"/v1/groups/{gid}/recurring"),
    })

(out / f"dimesum-{stamp}.json").write_text(json.dumps(backup, indent=2, ensure_ascii=False))

with open(out / f"dimesum-bills-{stamp}.csv", "w", newline="", encoding="utf-8") as f:
    w = csv.writer(f)
    w.writerow(["group", "date", "description", "amount_minor", "currency", "split_type", "deleted", "id", "version"])
    for g in backup["groups"]:
        for e in g["expenses"]:
            w.writerow([g["group"]["name"], e["occurred_on"], e["description"], e["amount_minor"],
                        e["currency"], e["split_type"], e["deleted"], e["id"], e["version"]])
print(f"backed up {len(backup['groups'])} groups to {out}")

Run it nightly with cron (crontab -e), keeping the key in a file only you can read:

Shell
# ~/.dimesum.env holds: export DIMESUM_API_KEY="dms_live_..."   (chmod 600)
15 3 * * * . "$HOME/.dimesum.env" && /usr/bin/python3 "$HOME/dimesum_backup.py" >> "$HOME/dimesum-backup.log" 2>&1

The CSV keeps amount_minor as the integer it is. Divide by 10 to the currency's exponent when you open it, never before you store it.

Claude as your expense assistant#

Saves: tapping through screens to answer a question. "How much did the Goa trip cost me?", "who still owes for the cab?", "add the ₹900 groceries to the flat, Ravi paid".

Needs: a read key to start. Give it a read and write key once you like how it behaves.

  1. Connect Dimesum in Claude Desktop or Claude Code.
  2. Ask. Claude finds the group, reads the member ids, and calls the tools. The prompt examples show which tools each question uses.
  3. For writes, a line of standing instructions keeps it careful. In a Claude project or at the start of a chat: "When I ask you to add a Dimesum bill or record a payment, first tell me the group, the amount with its currency, who paid and who shares it, and wait for me to say yes."

It works with the same rules you do: it cannot see groups you are not in, it cannot edit a bill the group's editor policy keeps from you, and a payment it records is confirmed by the other person, as always.

Reconcile a bank statement against payments#

Saves: the end-of-month "did I pay Asha back or not?" Match the transfers in your bank's CSV with the payments recorded in Dimesum, and see what is missing on either side.

Needs: a read key, Python 3.9 or later, and your statement exported as CSV.

reconcile.py
"""python3 reconcile.py statement.csv
Statement columns used: date (YYYY-MM-DD), amount (debits positive, in rupees), reference."""
import csv, datetime, os, sys, time
from decimal import Decimal
import requests

API = "https://api.dimesum.com"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['DIMESUM_API_KEY']}"
CURRENCY = "INR"

def get(path, **params):
    r = s.get(API + path, params=params, timeout=30)
    r.raise_for_status()
    time.sleep(0.5)
    return r.json()

# Every payment I recorded, across groups.
mine = []
for g in get("/v1/groups")["groups"]:
    me = get(f"/v1/groups/{g['id']}")["my_member_id"]
    cursor = None
    while True:
        page = get(f"/v1/groups/{g['id']}/settlements", **({"cursor": cursor} if cursor else {}))
        mine += [dict(p, group=g["name"]) for p in page["settlements"]
                 if p["from_member_id"] == me and p["currency"] == CURRENCY and p["status"] != "REVERSED"]
        cursor = page.get("next_cursor")
        if not cursor:
            break

bank = []
with open(sys.argv[1], newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        bank.append({"date": datetime.date.fromisoformat(row["date"]),
                     "minor": int(Decimal(row["amount"]) * 100),
                     "reference": row.get("reference", "").strip()})

unmatched = list(mine)
missing = []
for t in bank:
    hit = next((p for p in unmatched if t["reference"] and p.get("reference") == t["reference"]), None)
    if not hit:  # same amount within two days
        hit = next((p for p in unmatched if p["amount_minor"] == t["minor"] and
                    abs((datetime.date.fromisoformat(p["created_at"][:10]) - t["date"]).days) <= 2), None)
    if hit:
        unmatched.remove(hit)
    else:
        missing.append(t)

print("In the bank, not recorded in Dimesum (check whether they were paybacks):")
for t in missing:
    print(f"  {t['date']}  ₹{Decimal(t['minor']) / 100:>10}  {t['reference']}")
print("Recorded in Dimesum, not found in this statement:")
for p in unmatched:
    print(f"  {p['created_at'][:10]}  ₹{Decimal(p['amount_minor']) / 100:>10}  {p['group']}  {p['status']}  {p.get('reference', '')}")

Most bank transfers are not paybacks, so the first list is a list to look at, not to record blindly. For the ones that are, record them with POST /v1/groups/{groupID}/settlements (a read and write key), passing the bank's reference so the other person can find it.

A household dashboard#

Saves: asking "where do we stand?" every month. One page with each group's balance per currency and what the household spent.

Needs: a read key, and a small script that runs on a schedule, because a dashboard should not hold a key in the browser.

The script folds GET /v1/me/balances and GET /v1/me/insights into flat rows a dashboard can read:

household.py
"""Write household.json: my position per group and currency, and this month's share of spending."""
import json, os, requests

API = "https://api.dimesum.com"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['DIMESUM_API_KEY']}"

rows, cursor = [], None
while True:
    page = s.get(f"{API}/v1/me/balances", params={"cursor": cursor} if cursor else {}).json()
    for g in page["groups"]:
        for m in g["members"]:
            for b in m["balances"]:
                rows.append({"group": g["name"], "person": m["display_name"], "me": m["member_id"] == g["my_member_id"],
                             "currency": b["currency"], "balance_minor": b["balance_minor"]})
    cursor = page.get("next_cursor")
    if not cursor:
        break

insights = s.get(f"{API}/v1/me/insights").json()
spend = [{"currency": x["currency"], "minor": x["minor"]} for x in insights.get("my_share", {}).get("sums", [])]

with open(os.environ.get("OUT", "household.json"), "w") as f:
    json.dump({"balances": rows, "my_share_this_month": spend, "period": insights.get("period")}, f, indent=2)
  • Grafana: serve household.json from the same machine and read it with the Infinity data source (type JSON, root balances). A table panel of the rows where me is true is "where I stand per group"; filter on a person to see them across groups. Keep currencies as separate series.
  • Notion: after writing the file, update one database row per group and currency with Notion's PATCH /v1/pages/{page_id}, using a Notion integration token held next to the Dimesum key.

Balances are each member's position against the group, never a figure summed across currencies (Balances). Read-only example groups are not included.