dimesumdevelopers API reference Console Open the app

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#

  1. Open Dimesum and go to Me › Profile › Developer.
  2. 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.
  3. 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.

Shell
export DIMESUM_API_KEY="dms_live_..."

3. Your first call#

GET /v1/me returns the account the key belongs to.

curl
curl https://api.dimesum.com/v1/me \
  -H "Authorization: Bearer $DIMESUM_API_KEY"
Response
{
  "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
curl https://api.dimesum.com/v1/groups \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

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.

curl
GROUP_ID="0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
curl https://api.dimesum.com/v1/groups/$GROUP_ID \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

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 is 120000 paise; ¥1,200 is 1200 because 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
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

To 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
curl https://api.dimesum.com/v1/groups/$GROUP_ID/balances \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

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.

Next#

  • Concepts: money, idempotency, editing, members and pagination, in one page.
  • Recipes: working automations to copy.
  • Console: try any call in the browser.