API reference
Every operation a key can call, generated from the API's own OpenAPI contract, so nothing here can be missing or out of date.
The public API has 40 operations: 24 need the read scope and 16 need write.
Every request needs Authorization: Bearer dms_live_… (Authentication). Requests with a body send Content-Type: application/json. Money is an integer in the currency's minor unit (Money), and every write carries an id you generate (Idempotency). A refusal is always the error envelope with a stable code.
In the examples, $DIMESUM_API_KEY is your key and $GROUP_ID, $EXPENSE_ID and the like are ids from earlier responses. The curl examples use uuidgen for a fresh id; any UUID works and UUIDv7 is recommended. Download the contract as openapi.json.
You#
Who you are#
/v1/mescope: readThe account the key belongs to.
Responses
An object of type Me.
idstring · uuiddisplay_namestringemailstring · emailtimezonestringExample"Asia/Kolkata"preferred_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"avatar_urlstring · uri
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"display_name": "Asha",
"preferred_currency": "INR"
}Example request
curl "https://api.dimesum.com/v1/me" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/me`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/me",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Groups#
List groups#
/v1/groupsscope: readEvery group you are in, with your position in each.
Responses
groupsarray of object (GroupRow)Child fields of
groupsidstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"kindstringOne of"GROUP""QUICK"member_countintegercreated_atstring · date-timeread_onlybooleanarchivedbooleanYou archived it in the app: hidden from your own home screen and pickers, nobody else's. Its money still counts everywhere.squarebooleanTrue only when every member is at zero in every currency.your_positionarray of object (Money)Your net in each currency: positive means the group owes you.Child fields of
your_positioncurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"net_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Example response
{
"groups": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"name": "Goa trip",
"default_currency": "INR",
"kind": "GROUP",
"member_count": 1,
"created_at": "2026-09-28T09:30:00Z",
"read_only": true,
"archived": true,
"square": true,
"your_position": [
{
"currency": "INR",
"net_minor": 1
}
]
}
]
}Example request
curl "https://api.dimesum.com/v1/groups" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/groups`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/groups",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Create a group#
/v1/groupsscope: writeYou are its first member and owner.
Request body (JSON, required)
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.namestringrequiredUp to 60 charactersdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"timezonestring
Responses
An object of type GroupDetail.
idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"timezonestringkindstringmy_member_idstring · uuidYour own member id in this group.owner_member_idstring · uuidread_onlybooleanmembersarray of object (Member)Child fields of
membersidstring · uuidThe member id. Bills and payments name people by this.display_namestringis_ghostbooleanA kept place: somebody without an account (yet).user_idstring · uuidThe account behind the member, when there is one.avatar_urlstring · uri
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"name": "Goa trip",
"default_currency": "INR",
"kind": "string",
"my_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"owner_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"members": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"display_name": "Asha",
"is_ghost": true,
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
}
]
}Example request
curl "https://api.dimesum.com/v1/groups" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"name": "Goa trip",
"default_currency": "INR"
}
EOFconst res = await fetch(`https://api.dimesum.com/v1/groups`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
name: "Goa trip",
default_currency: "INR",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
r = requests.post(
f"https://api.dimesum.com/v1/groups",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"name": "Goa trip",
"default_currency": "INR",
},
)
r.raise_for_status()
print(r.json())Get a group#
/v1/groups/{groupID}scope: readMembers (with member ids), currency and settings.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Responses
An object of type GroupDetail.
idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"timezonestringkindstringmy_member_idstring · uuidYour own member id in this group.owner_member_idstring · uuidread_onlybooleanmembersarray of object (Member)Child fields of
membersidstring · uuidThe member id. Bills and payments name people by this.display_namestringis_ghostbooleanA kept place: somebody without an account (yet).user_idstring · uuidThe account behind the member, when there is one.avatar_urlstring · uri
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"name": "Goa trip",
"default_currency": "INR",
"kind": "string",
"my_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"owner_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"members": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"display_name": "Asha",
"is_ghost": true,
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
}
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Add a kept place#
/v1/groups/{groupID}/membersscope: writeA member without an account (yet), so bills can include them. Offer it to an account with offer_user_id; they accept in their inbox. Refused with 403 offer_not_connected unless you share a group with that account or keep each other in People.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Request body (JSON, required)
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.display_namestringrequiredemailstringphonestringE.164offer_user_idstring · uuid
Responses
An object of type Member.
idstring · uuidThe member id. Bills and payments name people by this.display_namestringis_ghostbooleanA kept place: somebody without an account (yet).user_idstring · uuidThe account behind the member, when there is one.avatar_urlstring · uri
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"display_name": "Asha",
"is_ghost": true,
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/members" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"display_name": "Asha"
}
EOF// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/members`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
display_name: "Asha",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/members",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"display_name": "Asha",
},
)
r.raise_for_status()
print(r.json())Who can edit bills#
/v1/groups/{groupID}/editorsscope: readThe group's editor policy. Anyone may always change a bill they added.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Responses
An object of type Editors.
modestringOWNER: the owner and member_ids may change anybody's bill. EVERYONE: all members may.One of"OWNER""EVERYONE"member_idsarray of string · uuid
Example response
{
"mode": "OWNER",
"member_ids": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/editors" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/editors`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/editors",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Expenses#
List bills#
/v1/groups/{groupID}/expensesscope: readNewest first, paged. Deleted bills stay in the list with deleted=true.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.limitinteger · in query1 to 100, 20 by default.cursorstring · in queryFrom next_cursor.
Responses
An object of type ExpensePage.
expensesarray of object (Expense)Child fields of
expensesidstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
next_cursorstringPass as ?cursor= for the next page; absent on the last.
Example response
{
"expenses": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}
],
"next_cursor": "string"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses?limit=50" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses?limit=50`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses?limit=50",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Add a bill#
/v1/groups/{groupID}/expensesscope: writeSplit equally among everyone unless you say otherwise; you paid unless payers says otherwise.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Request body (JSON, required)
An object of type ExpenseCreate.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.descriptionstringrequiredUp to 120 charactersamount_minorintegerIn the currency's minor unit. Required unless the bill is by item (items).currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"Default"EQUAL"participantsarray of string · uuidMember ids who share it. Everyone in the group when left out.payersarray of object (Payer)Who paid how much; must sum to amount_minor. You, paying all of it, when left out.Child fields of
payersmember_idstring · uuidrequiredpaid_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
sharesarray of object (MemberValue)EXACT: each person's amount in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
percentsarray of object (MemberValue)PERCENT: basis points (100% = 10000).Child fields of
percentsmember_idstring · uuidrequiredvalueintegerrequired
weightsarray of object (MemberValue)SHARES: relative weights.Child fields of
weightsmember_idstring · uuidrequiredvalueintegerrequired
itemsarray of object (Item)A bill by item. The total is then the lines plus the pools, so amount_minor may be left out; if sent, it must agree.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)With items: tax, tip, fees and discounts, in the order the bill prints them.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
occurred_onstring · dateA calendar date, YYYY-MM-DD.fx_ratestringFor a bill converted into another currency: convert_to's currency (the group's when convert_to is left out) per unit.convert_tostringThe currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it.locationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystringOptional. Left out, the bill is labelled for you shortly after it is added; set, it is yours and is never overwritten.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
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",
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
],
"occurred_on": "2026-09-28",
"convert_to": "string",
"category": "food_dining"
}
EOF// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
description: "Dinner at Thalassa",
amount_minor: 120000,
currency: "INR",
items: [
{
description: "Dinner at Thalassa",
amount_minor: 120000,
assignees: ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"],
},
],
pools: [
{
kind: "TAX",
label: "string",
amount_minor: 120000,
rate_bp: 1,
},
],
occurred_on: "2026-09-28",
convert_to: "string",
category: "food_dining",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"],
},
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1,
},
],
"occurred_on": "2026-09-28",
"convert_to": "string",
"category": "food_dining",
},
)
r.raise_for_status()
print(r.json())Get a bill#
/v1/groups/{groupID}/expenses/{expenseID}scope: readWith its split inputs, version and can_edit for you.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, expense_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Edit a bill#
/v1/groups/{groupID}/expenses/{expenseID}scope: writeRestate the whole bill from the version you read. Refused with 403 not_editor unless it is your bill or the group lets you edit others'.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Request body (JSON, required)
An object of type ExpenseAmend.
revision_idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.base_versionintegerrequiredThe version you read. A stale one is refused (409 stale_version).descriptionstringrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"occurred_onstring · dateA calendar date, YYYY-MM-DD.fx_ratestringAs on create.convert_tostringThe currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it.split_typestringrequiredOne of"EQUAL""EXACT""PERCENT""SHARES"participantsarray of string · uuidrequiredpayersarray of object (Payer)Child fields of
payersmember_idstring · uuidrequiredpaid_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
sharesarray of object (MemberValue)Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
percentsarray of object (MemberValue)Child fields of
percentsmember_idstring · uuidrequiredvalueintegerrequired
weightsarray of object (MemberValue)Child fields of
weightsmember_idstring · uuidrequiredvalueintegerrequired
itemsarray of object (Item)Restate the lines, or the bill stops being by item.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
categorystring or nullThe one field an edit may leave out: absent or null keeps the bill's category; "" clears it for good; a value sets it as yours.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"""null
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
curl -X PATCH "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"revision_id": "$(uuidgen)",
"base_version": 1,
"description": "Dinner at Thalassa (with dessert)",
"amount_minor": 135000,
"currency": "INR",
"occurred_on": "2026-09-28",
"convert_to": "string",
"split_type": "EQUAL",
"participants": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d04"
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
],
"category": "food_dining"
}
EOF// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
revision_id: crypto.randomUUID(),
base_version: 1,
description: "Dinner at Thalassa (with dessert)",
amount_minor: 135000,
currency: "INR",
occurred_on: "2026-09-28",
convert_to: "string",
split_type: "EQUAL",
participants: [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d04",
],
items: [
{
description: "Dinner at Thalassa",
amount_minor: 120000,
assignees: ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"],
},
],
pools: [
{
kind: "TAX",
label: "string",
amount_minor: 120000,
rate_bp: 1,
},
],
category: "food_dining",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id, expense_id: ids from earlier calls
r = requests.patch(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"revision_id": str(uuid.uuid4()),
"base_version": 1,
"description": "Dinner at Thalassa (with dessert)",
"amount_minor": 135000,
"currency": "INR",
"occurred_on": "2026-09-28",
"convert_to": "string",
"split_type": "EQUAL",
"participants": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d04",
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": ["0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"],
},
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1,
},
],
"category": "food_dining",
},
)
r.raise_for_status()
print(r.json())Delete a bill#
/v1/groups/{groupID}/expenses/{expenseID}scope: writeA tombstone: the ledger reverses it and the history keeps it.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Request body (JSON, required)
An object of type ExpenseDelete.
revision_idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.base_versionintegerrequired
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
curl -X DELETE "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"revision_id": "$(uuidgen)",
"base_version": 1
}
EOF// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
revision_id: crypto.randomUUID(),
base_version: 1,
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id, expense_id: ids from earlier calls
r = requests.delete(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"revision_id": str(uuid.uuid4()),
"base_version": 1,
},
)
r.raise_for_status()
print(r.json())A bill's history#
/v1/groups/{groupID}/expenses/{expenseID}/revisionsscope: readOne snapshot per version.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Responses
revisionsarray of object (Revision)Child fields of
revisionsversionintegeractionstringatstring · date-time
Example response
{
"revisions": [
{
"version": 1,
"action": "string",
"at": "2026-09-28T09:30:00Z"
}
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/revisions" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}/revisions`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, expense_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}/revisions",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())A bill's comments#
/v1/groups/{groupID}/expenses/{expenseID}/commentsscope: readOldest first; deleted ones stay as tombstones.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Responses
commentsarray of object (Comment)Child fields of
commentsidstring · uuidauthor_member_idstring · uuidbodystringcreated_atstring · date-timeeditedbooleandeletedboolean
Example response
{
"comments": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"author_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"body": "Paid the tip in cash, it is included.",
"created_at": "2026-09-28T09:30:00Z",
"edited": true,
"deleted": true
}
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/comments" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}/comments`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, expense_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}/comments",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Comment on a bill#
/v1/groups/{groupID}/expenses/{expenseID}/commentsscope: writeUp to 30 per member per hour, 200 per bill.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Request body (JSON, required)
An object of type CommentCreate.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.bodystringrequiredUp to 1000 characters
Responses
An object of type Comment.
idstring · uuidauthor_member_idstring · uuidbodystringcreated_atstring · date-timeeditedbooleandeletedboolean
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"author_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"body": "Paid the tip in cash, it is included.",
"created_at": "2026-09-28T09:30:00Z",
"edited": true,
"deleted": true
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/comments" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"body": "Paid the tip in cash, it is included."
}
EOF// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}/comments`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
body: "Paid the tip in cash, it is included.",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id, expense_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}/comments",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"body": "Paid the tip in cash, it is included.",
},
)
r.raise_for_status()
print(r.json())Set a bill's rate#
/v1/groups/{groupID}/expenses/{expenseID}/fx-ratescope: writeFor a bill in another currency: group currency per unit, e.g. "0.5624".
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.expenseIDstring · uuid · in pathrequiredThe bill's id.
Request body (JSON, required)
ratestringrequired
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
curl -X PUT "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/fx-rate" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rate": "0.5624"
}'// groupId, expenseId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/expenses/${expenseId}/fx-rate`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
rate: "0.5624",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, expense_id: ids from earlier calls
r = requests.put(
f"https://api.dimesum.com/v1/groups/{group_id}/expenses/{expense_id}/fx-rate",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"rate": "0.5624",
},
)
r.raise_for_status()
print(r.json())Balances#
Balances across every group#
/v1/me/balancesscope: readEvery group you are in, with each member's balance per currency. Fold it by person (user_id) to answer "who owes me"; never add across currencies.
Parameters
cursorstring · in queryFrom next_cursor.
Responses
An object of type MeBalances.
groupsarray of objectChild fields of
groupsgroup_idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"my_member_idstring · uuidmembersarray of object (MemberBalance)Child fields of
membersmember_idstring · uuiddisplay_namestringis_ghostbooleanbalancesarray of object (CurrencyBalance)Per currency. Positive: the group owes this member; negative: they owe the group.Child fields of
balancescurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
next_cursorstring
Example response
{
"groups": [
{
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"name": "Goa trip",
"default_currency": "INR",
"my_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"members": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"display_name": "Asha",
"is_ghost": true,
"balances": [
{
"currency": null,
"balance_minor": null
}
]
}
]
}
],
"next_cursor": "string"
}Example request
curl "https://api.dimesum.com/v1/me/balances" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/me/balances`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/me/balances",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Group balances#
/v1/groups/{groupID}/balancesscope: readEach member's balance per currency.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Responses
An object of type Balances.
balancesarray of object (MemberBalance)Child fields of
balancesmember_idstring · uuiddisplay_namestringis_ghostbooleanbalancesarray of object (CurrencyBalance)Per currency. Positive: the group owes this member; negative: they owe the group.Child fields of
balancescurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Example response
{
"balances": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"display_name": "Asha",
"is_ghost": true,
"balances": [
{
"currency": "INR",
"balance_minor": 1
}
]
}
]
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/balances" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/balances`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/balances",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Settling#
Payments#
/v1/groups/{groupID}/settlementsscope: readNewest first, paged.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.cursorstring · in queryFrom next_cursor.
Responses
settlementsarray of object (Settlement)Child fields of
settlementsidstring · uuidfrom_member_idstring · uuidto_member_idstring · uuidamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"methodstringreferencestringbatch_idstring · uuidSet when this payment is one leg of a transfer that cleared several groups.created_atstring · date-time
next_cursorstring
Example response
{
"settlements": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"method": "tools/list",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"created_at": "2026-09-28T09:30:00Z"
}
],
"next_cursor": "string"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/settlements" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/settlements`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/settlements",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Record a payment#
/v1/groups/{groupID}/settlementsscope: writeSomething you paid in your own app or in cash. Any positive amount: more than you owe leaves them owing you the difference.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Request body (JSON, required)
An object of type SettlementCreate.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.from_member_idstring · uuidrequiredMust be your own member id.to_member_idstring · uuidrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"methodstringOne of"UPI""CASH""OTHER""PAYPAL""VENMO""CASHAPP""WISE""REVOLUT""ZELLE""PAYNOW""PIX""IBAN""BANK"referencestringThe payment app's reference, for the other person to find.notestringbatch_idstring · uuidOptional. The same id on every leg of one transfer that clears several groups; every leg must be between the same two people, in one currency (400 batch_mismatch otherwise).
Responses
An object of type Settlement.
idstring · uuidfrom_member_idstring · uuidto_member_idstring · uuidamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"methodstringreferencestringbatch_idstring · uuidSet when this payment is one leg of a transfer that cleared several groups.created_atstring · date-time
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"method": "tools/list",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"created_at": "2026-09-28T09:30:00Z"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/settlements" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 50000,
"currency": "INR",
"method": "UPI",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
}
EOF// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/settlements`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
from_member_id: "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
to_member_id: "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
amount_minor: 50000,
currency: "INR",
method: "UPI",
reference: "628104551923",
batch_id: "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/settlements",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 50000,
"currency": "INR",
"method": "UPI",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
},
)
r.raise_for_status()
print(r.json())Confirm a payment#
/v1/groups/{groupID}/settlements/{settlementID}/confirmscope: writeAs the person paid.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.settlementIDstring · uuid · in pathrequiredThe payment's id.
Request body (JSON, required)
An empty object: send {}.
Responses
An object of type Settlement.
idstring · uuidfrom_member_idstring · uuidto_member_idstring · uuidamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"methodstringreferencestringbatch_idstring · uuidSet when this payment is one leg of a transfer that cleared several groups.created_atstring · date-time
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"method": "tools/list",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"created_at": "2026-09-28T09:30:00Z"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/settlements/$SETTLEMENT_ID/confirm" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'// groupId, settlementId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/settlements/${settlementId}/confirm`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, settlement_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/settlements/{settlement_id}/confirm",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={},
)
r.raise_for_status()
print(r.json())Dispute a payment#
/v1/groups/{groupID}/settlements/{settlementID}/disputescope: writeAs the person paid: the money did not arrive. The payment is reversed.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.settlementIDstring · uuid · in pathrequiredThe payment's id.
Request body (JSON, required)
An empty object: send {}.
Responses
An object of type Settlement.
idstring · uuidfrom_member_idstring · uuidto_member_idstring · uuidamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"methodstringreferencestringbatch_idstring · uuidSet when this payment is one leg of a transfer that cleared several groups.created_atstring · date-time
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"from_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"to_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d03",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"method": "tools/list",
"reference": "628104551923",
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"created_at": "2026-09-28T09:30:00Z"
}Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/settlements/$SETTLEMENT_ID/dispute" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'// groupId, settlementId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/settlements/${settlementId}/dispute`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id, settlement_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/settlements/{settlement_id}/dispute",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={},
)
r.raise_for_status()
print(r.json())One payment across groups#
/v1/settlement-batches/{batchID}scope: readEvery leg of a transfer that cleared several groups, in the groups you share.
Parameters
batchIDstring · uuid · in pathrequiredThe transfer's batch id.
Responses
An object of type SettlementBatch.
batch_idstring · uuidlegsarray of objectChild fields of
legsidstring · uuidgroup_idstring · uuidgroup_namestringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"fromobjectChild fields of
frommember_idstring · uuiduser_idstring · uuiddisplay_namestring
toobjectChild fields of
tomember_idstring · uuiduser_idstring · uuiddisplay_namestring
Example response
{
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"legs": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"group_name": "string",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"from": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
},
"to": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
}
}
]
}Example request
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// batchId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/settlement-batches/${batchId}`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# batch_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/settlement-batches/{batch_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Confirm a payment across groups#
/v1/settlement-batches/{batchID}/confirmscope: writeAs the other person: confirms every leg you are the counterparty of, once.
Parameters
batchIDstring · uuid · in pathrequiredThe transfer's batch id.
Request body (JSON, required)
An empty object: send {}.
Responses
An object of type SettlementBatch.
batch_idstring · uuidlegsarray of objectChild fields of
legsidstring · uuidgroup_idstring · uuidgroup_namestringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"fromobjectChild fields of
frommember_idstring · uuiduser_idstring · uuiddisplay_namestring
toobjectChild fields of
tomember_idstring · uuiduser_idstring · uuiddisplay_namestring
Example response
{
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"legs": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"group_name": "string",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"from": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
},
"to": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
}
}
]
}Example request
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID/confirm" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'// batchId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/settlement-batches/${batchId}/confirm`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# batch_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/settlement-batches/{batch_id}/confirm",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={},
)
r.raise_for_status()
print(r.json())Dispute a payment across groups#
/v1/settlement-batches/{batchID}/disputescope: writeAs the other person: the money did not arrive. Every leg is reversed.
Parameters
batchIDstring · uuid · in pathrequiredThe transfer's batch id.
Request body (JSON, required)
An empty object: send {}.
Responses
An object of type SettlementBatch.
batch_idstring · uuidlegsarray of objectChild fields of
legsidstring · uuidgroup_idstring · uuidgroup_namestringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"fromobjectChild fields of
frommember_idstring · uuiduser_idstring · uuiddisplay_namestring
toobjectChild fields of
tomember_idstring · uuiduser_idstring · uuiddisplay_namestring
Example response
{
"batch_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"legs": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"group_name": "string",
"amount_minor": 120000,
"currency": "INR",
"status": "RECORDED",
"from": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
},
"to": {
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha"
}
}
]
}Example request
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID/dispute" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'// batchId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/settlement-batches/${batchId}/dispute`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# batch_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/settlement-batches/{batch_id}/dispute",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={},
)
r.raise_for_status()
print(r.json())Forgiven debts#
/v1/groups/{groupID}/write-offsscope: readDebts a creditor forgave (write-offs are made in the app).
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/write-offs" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/write-offs`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/write-offs",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Repeats#
Repeats#
/v1/groups/{groupID}/recurringscope: readThe group's standing instructions (rent, subscriptions).
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/recurring" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/recurring`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/recurring",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Create a repeat#
/v1/groups/{groupID}/recurringscope: writePosts an ordinary bill on schedule; each occurrence is idempotent per period.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.
Request body (JSON, required)
An object of type RecurringCreate.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.descriptionstringrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"split_typestringparticipantsarray of string · uuidfreqstringrequiredOne of"DAILY""WEEKLY""MONTHLY"day_of_monthinteger1 to 28weekdayinteger0 to 6start_onstring · dateA calendar date, YYYY-MM-DD.source_expense_idstring · uuidThe bill this repeats, when switched on from one.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
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
}
EOF// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/recurring`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
description: "Rent",
amount_minor: 4500000,
currency: "INR",
freq: "MONTHLY",
day_of_month: 1,
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
# group_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/groups/{group_id}/recurring",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"description": "Rent",
"amount_minor": 4500000,
"currency": "INR",
"freq": "MONTHLY",
"day_of_month": 1,
},
)
r.raise_for_status()
print(r.json())Capture#
Read a line into a draft#
/v1/capturesscope: writeA sentence in, a suggestion out, never a posted bill: a person (or your script) confirms it. With no parser configured the suggestion still arrives: the line is its name and the amount is left for a person to fill.
Request body (JSON, required)
An object of type CaptureCreate.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.group_idstring · uuidrequiredtextstringrequiredA line in plain words, e.g. "dinner 1200 with Ravi and Priya, I paid".Up to 2000 characters
Responses
An object of type Suggestion.
idstring · uuidgroup_idstring · uuidstatusstringOne of"PENDING""CONFIRMED""DISMISSED"descriptionstringamount_minorinteger or nullcurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"textstring
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"status": "PENDING",
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"text": "dinner 1200 with Ravi and Priya, I paid"
}Example request
curl "https://api.dimesum.com/v1/captures" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"id": "$(uuidgen)",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"text": "dinner 1200 with Ravi and Priya, I paid"
}
EOFconst res = await fetch(`https://api.dimesum.com/v1/captures`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
id: crypto.randomUUID(),
group_id: "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
text: "dinner 1200 with Ravi and Priya, I paid",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os, uuid
import requests
r = requests.post(
f"https://api.dimesum.com/v1/captures",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"id": str(uuid.uuid4()),
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"text": "dinner 1200 with Ravi and Priya, I paid",
},
)
r.raise_for_status()
print(r.json())Suggestions#
/v1/suggestionsscope: readDrafts waiting to be confirmed.
Responses
suggestionsarray of object (Suggestion)Child fields of
suggestionsidstring · uuidgroup_idstring · uuidstatusstringOne of"PENDING""CONFIRMED""DISMISSED"descriptionstringamount_minorinteger or nullcurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"textstring
Example response
{
"suggestions": [
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"status": "PENDING",
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"text": "dinner 1200 with Ravi and Priya, I paid"
}
]
}Example request
curl "https://api.dimesum.com/v1/suggestions" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/suggestions`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/suggestions",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())A suggestion#
/v1/suggestions/{suggestionID}scope: readParameters
suggestionIDstring · uuid · in pathrequiredThe suggestion's id.
Responses
An object of type Suggestion.
idstring · uuidgroup_idstring · uuidstatusstringOne of"PENDING""CONFIRMED""DISMISSED"descriptionstringamount_minorinteger or nullcurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"textstring
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"status": "PENDING",
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"text": "dinner 1200 with Ravi and Priya, I paid"
}Example request
curl "https://api.dimesum.com/v1/suggestions/$SUGGESTION_ID" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// suggestionId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/suggestions/${suggestionId}`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# suggestion_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/suggestions/{suggestion_id}",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Confirm a suggestion#
/v1/suggestions/{suggestionID}/confirmscope: writePosts it as a bill, with anything you correct. Idempotent: the bill's id comes from the suggestion's.
Parameters
suggestionIDstring · uuid · in pathrequiredThe suggestion's id.
Request body (JSON, required)
An object of type SuggestionConfirm.
amount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.descriptionstringparticipantsarray of string · uuid
Responses
An object of type Expense.
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"version": 1,
"deleted": true,
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"group_currency": "INR",
"amount_group_minor": 1,
"needs_fx_rate": true,
"display_currency": "string",
"display_rate": "string",
"display_rate_on": "2026-09-28",
"display_rate_source": "string",
"occurred_on": "2026-09-28",
"created_at": "2026-09-28T09:30:00Z",
"created_by_member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"read_only": true,
"category": "food_dining",
"category_source": "USER",
"can_edit": true,
"splits": [
{
"member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
"share_minor": 60000,
"paid_minor": 120000
}
],
"items": [
{
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"assignees": [
"0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
]
}
],
"pools": [
{
"kind": "TAX",
"label": "string",
"amount_minor": 120000,
"rate_bp": 1
}
]
}Example request
curl "https://api.dimesum.com/v1/suggestions/$SUGGESTION_ID/confirm" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_minor": 120000,
"description": "Dinner"
}'// suggestionId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/suggestions/${suggestionId}/confirm`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
amount_minor: 120000,
description: "Dinner",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# suggestion_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/suggestions/{suggestion_id}/confirm",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"amount_minor": 120000,
"description": "Dinner",
},
)
r.raise_for_status()
print(r.json())Dismiss a suggestion#
/v1/suggestions/{suggestionID}/dismissscope: writeParameters
suggestionIDstring · uuid · in pathrequiredThe suggestion's id.
Request body (JSON, required)
An empty object: send {}.
Responses
An object of type Suggestion.
idstring · uuidgroup_idstring · uuidstatusstringOne of"PENDING""CONFIRMED""DISMISSED"descriptionstringamount_minorinteger or nullcurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"textstring
Example response
{
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"group_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"status": "PENDING",
"description": "Dinner at Thalassa",
"amount_minor": 120000,
"currency": "INR",
"text": "dinner 1200 with Ravi and Priya, I paid"
}Example request
curl "https://api.dimesum.com/v1/suggestions/$SUGGESTION_ID/dismiss" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'// suggestionId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/suggestions/${suggestionId}/dismiss`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# suggestion_id: ids from earlier calls
r = requests.post(
f"https://api.dimesum.com/v1/suggestions/{suggestion_id}/dismiss",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={},
)
r.raise_for_status()
print(r.json())Activity#
Your activity feed#
/v1/me/activityscope: readWhat happened across your groups, newest last, as a delta from a cursor.
Parameters
sincestring · in queryA cursor from the previous read.limitinteger · in queryUp to 500.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/me/activity?limit=50" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/me/activity?limit=50`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/me/activity?limit=50",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())A group's activity feed#
/v1/groups/{groupID}/activityscope: readBills, edits, payments and members joining, as a delta from a cursor.
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.sincestring · in queryCursor.limitinteger · in queryUp to 500.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/activity?limit=50" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/activity?limit=50`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/activity?limit=50",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Insights#
Your spending insights#
/v1/me/insightsscope: readYour share of spending for a month and the year around it: by group, by category (by_category), by day, by week, what repeats (fixed_months).
Parameters
monthstring · in queryYYYY-MM; this month by default.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/me/insights?month=2026-09" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/me/insights?month=2026-09`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/me/insights?month=2026-09",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Group insights#
/v1/groups/{groupID}/insightsscope: readThe group's spending for a month: totals, by member, by day, by category (by_category, my_by_category; category null is the uncategorised bucket).
Parameters
groupIDstring · uuid · in pathrequiredThe group's id.monthstring · in queryYYYY-MM.
Responses
An object of type Loose.
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/insights?month=2026-09" \
-H "Authorization: Bearer $DIMESUM_API_KEY"// groupId: ids from earlier calls, e.g. GET /v1/groups
const res = await fetch(`https://api.dimesum.com/v1/groups/${groupId}/insights?month=2026-09`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
# group_id: ids from earlier calls
r = requests.get(
f"https://api.dimesum.com/v1/groups/{group_id}/insights?month=2026-09",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())People#
People you keep#
/v1/peoplescope: readPeople added by their code or phone number, outside any group.
Responses
peoplearray of object (Person)Child fields of
peopleuser_idstring · uuiddisplay_namestringavatar_urlstringviastringOne of"CODE""PHONE"sincestring · date-time
Example response
{
"people": [
{
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"display_name": "Asha",
"via": "CODE",
"since": "2026-09-28T09:30:00Z"
}
]
}Example request
curl "https://api.dimesum.com/v1/people" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/people`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/people",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Rates#
A market rate#
/v1/fx/quotescope: readThe latest published rate between two currencies, for reference.
Parameters
fromstring · in queryISO code.tostring · in queryISO code.
Responses
An object of type FXQuote.
fromstringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"tostringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"ratestringas_ofstring · dateA calendar date, YYYY-MM-DD.
Example response
{
"from": "INR",
"to": "INR",
"rate": "0.5624",
"as_of": "2026-09-28"
}Example request
curl "https://api.dimesum.com/v1/fx/quote?from=USD&to=INR" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/fx/quote?from=USD&to=INR`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/fx/quote?from=USD&to=INR",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())Developer#
This key#
/v1/developer/keyscope: readWhich key is calling, its scopes, its limits and its recent requests.
Responses
An object of type DeveloperKey.
keyobjectChild fields of
keyidstring · uuidnamestringprefixstringExample"dms_live_Ab3x"scopesarray of stringenabledbooleancreated_atstring · date-timelast_used_atstring · date-time
user_idstring · uuidrate_limitobjectChild fields of
rate_limitper_secondnumberburstinteger
requestsarray of objectChild fields of
requestsatstring · date-timemethodstringpathstringstatusintegerduration_msinteger
Example response
{
"key": {
"id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
"name": "Goa trip",
"prefix": "dms_live_Ab3x",
"scopes": [
"read"
],
"enabled": true,
"created_at": "2026-09-28T09:30:00Z",
"last_used_at": "2026-09-28T09:30:00Z"
},
"user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
"rate_limit": {
"per_second": 1,
"burst": 1
},
"requests": [
{
"at": "2026-09-28T09:30:00Z",
"method": "tools/list",
"path": "string",
"status": 1,
"duration_ms": 1
}
]
}Example request
curl "https://api.dimesum.com/v1/developer/key" \
-H "Authorization: Bearer $DIMESUM_API_KEY"const res = await fetch(`https://api.dimesum.com/v1/developer/key`, {
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
},
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.get(
f"https://api.dimesum.com/v1/developer/key",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
)
r.raise_for_status()
print(r.json())MCP endpoint#
/mcpscope: readModel Context Protocol over Streamable HTTP (JSON-RPC 2.0, JSON responses). Methods: initialize, tools/list, tools/call, ping. See the MCP guide for the tools.
Tools, arguments and client setup are in the MCP guide.
Request body (JSON, required)
jsonrpcstringOne of"2.0"idanymethodstringparamsobject
Responses
An object. The fields worth knowing are in Concepts: report objects.
Example request
curl "https://api.dimesum.com/mcp" \
-H "Authorization: Bearer $DIMESUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'const res = await fetch(`https://api.dimesum.com/mcp`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "tools/list",
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
console.log(await res.json());import os
import requests
r = requests.post(
f"https://api.dimesum.com/mcp",
headers={"Authorization": f"Bearer {os.environ['DIMESUM_API_KEY']}"},
json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
},
)
r.raise_for_status()
print(r.json())Objects#
Every named schema the operations above refer to.
Error#
errorobjectrequiredChild fields of
errorcodestringrequiredA stable, machine-readable reason, e.g. not_found, api_key_read_only, not_editor.messagestringrequiredA sentence for a person.
Money#
currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"net_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Me#
idstring · uuiddisplay_namestringemailstring · emailtimezonestringExample"Asia/Kolkata"preferred_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"avatar_urlstring · uri
GroupRow#
idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"kindstringOne of"GROUP""QUICK"member_countintegercreated_atstring · date-timeread_onlybooleanarchivedbooleanYou archived it in the app: hidden from your own home screen and pickers, nobody else's. Its money still counts everywhere.squarebooleanTrue only when every member is at zero in every currency.your_positionarray of object (Money)Your net in each currency: positive means the group owes you.Child fields of
your_positioncurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"net_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Member#
idstring · uuidThe member id. Bills and payments name people by this.display_namestringis_ghostbooleanA kept place: somebody without an account (yet).user_idstring · uuidThe account behind the member, when there is one.avatar_urlstring · uri
GroupDetail#
idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"timezonestringkindstringmy_member_idstring · uuidYour own member id in this group.owner_member_idstring · uuidread_onlybooleanmembersarray of object (Member)Child fields of
membersidstring · uuidThe member id. Bills and payments name people by this.display_namestringis_ghostbooleanA kept place: somebody without an account (yet).user_idstring · uuidThe account behind the member, when there is one.avatar_urlstring · uri
Split#
member_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Location#
namestringlatnumberlngnumber
Expense#
idstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
ExpensePage#
expensesarray of object (Expense)Child fields of
expensesidstring · uuidgroup_idstring · uuidversionintegerBumps on every edit; an edit must name the version it read.deletedbooleandescriptionstringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"group_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"fx_ratestringGroup currency per unit of this bill's currency, as a decimal string.amount_group_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.needs_fx_ratebooleandisplay_currencystringThe group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day.display_ratestringThe market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only ("about ₹4,750"): it never changes a balance and is not fx_rate.display_rate_onstring · dateThe date the rate was published for.display_rate_sourcestringWho published the rate, e.g. ECB.split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"occurred_onstring · dateA calendar date, YYYY-MM-DD.created_atstring · date-timecreated_by_member_idstring · uuidread_onlybooleanlocationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystring or nullWhat the bill was for, from a fixed list. Null: uncategorised.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"nullcategory_sourcestring or nullUSER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.One of"USER""AI"nullcan_editbooleanOn a single bill: whether YOU may change it (its author always; others as the group's editor policy allows).splitsarray of object (Split)Child fields of
splitsmember_idstring · uuidshare_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.paid_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
itemsarray of object (Item)On a single bill by item: its lines.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)On a single bill by item: its tax, tip, fees and discounts, in order.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
next_cursorstringPass as ?cursor= for the next page; absent on the last.
Payer#
member_idstring · uuidrequiredpaid_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
MemberValue#
member_idstring · uuidrequiredvalueintegerrequired
Item#
One line of a bill by item.
descriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
Pool#
Tax, tip, a fee or a discount on a bill by item, applied in list order and shared by what each person had. State amount_minor OR rate_bp, not both.
kindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
ExpenseCreate#
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.descriptionstringrequiredUp to 120 charactersamount_minorintegerIn the currency's minor unit. Required unless the bill is by item (items).currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"split_typestringOne of"EQUAL""EXACT""PERCENT""SHARES"Default"EQUAL"participantsarray of string · uuidMember ids who share it. Everyone in the group when left out.payersarray of object (Payer)Who paid how much; must sum to amount_minor. You, paying all of it, when left out.Child fields of
payersmember_idstring · uuidrequiredpaid_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
sharesarray of object (MemberValue)EXACT: each person's amount in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
percentsarray of object (MemberValue)PERCENT: basis points (100% = 10000).Child fields of
percentsmember_idstring · uuidrequiredvalueintegerrequired
weightsarray of object (MemberValue)SHARES: relative weights.Child fields of
weightsmember_idstring · uuidrequiredvalueintegerrequired
itemsarray of object (Item)A bill by item. The total is then the lines plus the pools, so amount_minor may be left out; if sent, it must agree.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)With items: tax, tip, fees and discounts, in the order the bill prints them.Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
occurred_onstring · dateA calendar date, YYYY-MM-DD.fx_ratestringFor a bill converted into another currency: convert_to's currency (the group's when convert_to is left out) per unit.convert_tostringThe currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it.locationobject (Location)Child fields of
locationnamestringlatnumberlngnumber
categorystringOptional. Left out, the bill is labelled for you shortly after it is added; set, it is yours and is never overwritten.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"
ExpenseAmend#
An edit restates the whole bill: a typo fix must not silently change who shares it.
revision_idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.base_versionintegerrequiredThe version you read. A stale one is refused (409 stale_version).descriptionstringrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"occurred_onstring · dateA calendar date, YYYY-MM-DD.fx_ratestringAs on create.convert_tostringThe currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it.split_typestringrequiredOne of"EQUAL""EXACT""PERCENT""SHARES"participantsarray of string · uuidrequiredpayersarray of object (Payer)Child fields of
payersmember_idstring · uuidrequiredpaid_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
sharesarray of object (MemberValue)Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
percentsarray of object (MemberValue)Child fields of
percentsmember_idstring · uuidrequiredvalueintegerrequired
weightsarray of object (MemberValue)Child fields of
weightsmember_idstring · uuidrequiredvalueintegerrequired
itemsarray of object (Item)Restate the lines, or the bill stops being by item.Child fields of
itemsdescriptionstringamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.assigneesarray of string · uuidWho had it. Empty: shared by everyone in the bill, by its split_type.sharesarray of object (MemberValue)Optional: an unequal split of this line over its assignees, in minor units.Child fields of
sharesmember_idstring · uuidrequiredvalueintegerrequired
poolsarray of object (Pool)Child fields of
poolskindstringrequiredOne of"TAX""TIP""FEE""DISCOUNT"labelstringThe bill's own word for it, e.g. GST.amount_minorintegerA flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.rate_bpintegerA percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip.
categorystring or nullThe one field an edit may leave out: absent or null keeps the bill's category; "" clears it for good; a value sets it as yours.One of"food_dining""groceries""transport""travel""stay""rent""utilities""entertainment""shopping""other"""null
ExpenseDelete#
revision_idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.base_versionintegerrequired
Revision#
versionintegeractionstringatstring · date-time
Comment#
idstring · uuidauthor_member_idstring · uuidbodystringcreated_atstring · date-timeeditedbooleandeletedboolean
CommentCreate#
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.bodystringrequiredUp to 1000 characters
CurrencyBalance#
currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
MemberBalance#
member_idstring · uuiddisplay_namestringis_ghostbooleanbalancesarray of object (CurrencyBalance)Per currency. Positive: the group owes this member; negative: they owe the group.Child fields of
balancescurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Balances#
balancesarray of object (MemberBalance)Child fields of
balancesmember_idstring · uuiddisplay_namestringis_ghostbooleanbalancesarray of object (CurrencyBalance)Per currency. Positive: the group owes this member; negative: they owe the group.Child fields of
balancescurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
MeBalances#
Every group you are in with its members' balances, paged over your groups.
groupsarray of objectChild fields of
groupsgroup_idstring · uuidnamestringdefault_currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"my_member_idstring · uuidmembersarray of object (MemberBalance)Child fields of
membersmember_idstring · uuiddisplay_namestringis_ghostbooleanbalancesarray of object (CurrencyBalance)Per currency. Positive: the group owes this member; negative: they owe the group.Child fields of
balancescurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"balance_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
next_cursorstring
Settlement#
idstring · uuidfrom_member_idstring · uuidto_member_idstring · uuidamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"methodstringreferencestringbatch_idstring · uuidSet when this payment is one leg of a transfer that cleared several groups.created_atstring · date-time
SettlementBatch#
One transfer that cleared several groups: one settlement per group, the legs you can see.
batch_idstring · uuidlegsarray of objectChild fields of
legsidstring · uuidgroup_idstring · uuidgroup_namestringamount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"statusstringOne of"RECORDED""POSTED""CONFIRMED""REVERSED"fromobjectChild fields of
frommember_idstring · uuiduser_idstring · uuiddisplay_namestring
toobjectChild fields of
tomember_idstring · uuiduser_idstring · uuiddisplay_namestring
SettlementCreate#
Records a payment that already happened in a bank or payment app. Dimesum holds no money; the other person confirms or disputes, and silence confirms after 48 hours.
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.from_member_idstring · uuidrequiredMust be your own member id.to_member_idstring · uuidrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"methodstringOne of"UPI""CASH""OTHER""PAYPAL""VENMO""CASHAPP""WISE""REVOLUT""ZELLE""PAYNOW""PIX""IBAN""BANK"referencestringThe payment app's reference, for the other person to find.notestringbatch_idstring · uuidOptional. The same id on every leg of one transfer that clears several groups; every leg must be between the same two people, in one currency (400 batch_mismatch otherwise).
RecurringCreate#
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.descriptionstringrequiredamount_minorinteger · int64requiredMoney in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.currencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"split_typestringparticipantsarray of string · uuidfreqstringrequiredOne of"DAILY""WEEKLY""MONTHLY"day_of_monthinteger1 to 28weekdayinteger0 to 6start_onstring · dateA calendar date, YYYY-MM-DD.source_expense_idstring · uuidThe bill this repeats, when switched on from one.
CaptureCreate#
idstring · uuidrequiredA UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409.group_idstring · uuidrequiredtextstringrequiredA line in plain words, e.g. "dinner 1200 with Ravi and Priya, I paid".Up to 2000 characters
Suggestion#
A capture read into a draft. Nothing is posted until it is confirmed.
idstring · uuidgroup_idstring · uuidstatusstringOne of"PENDING""CONFIRMED""DISMISSED"descriptionstringamount_minorinteger or nullcurrencystringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"textstring
SuggestionConfirm#
amount_minorinteger · int64Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.descriptionstringparticipantsarray of string · uuid
Person#
user_idstring · uuiddisplay_namestringavatar_urlstringviastringOne of"CODE""PHONE"sincestring · date-time
Editors#
modestringOWNER: the owner and member_ids may change anybody's bill. EVERYONE: all members may.One of"OWNER""EVERYONE"member_idsarray of string · uuid
FXQuote#
fromstringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"tostringISO 4217 code.Pattern^[A-Z]{3}$Example"INR"ratestringas_ofstring · dateA calendar date, YYYY-MM-DD.
DeveloperKey#
keyobjectChild fields of
keyidstring · uuidnamestringprefixstringExample"dms_live_Ab3x"scopesarray of stringenabledbooleancreated_atstring · date-timelast_used_atstring · date-time
user_idstring · uuidrate_limitobjectChild fields of
rate_limitper_secondnumberburstinteger
requestsarray of objectChild fields of
requestsatstring · date-timemethodstringpathstringstatusintegerduration_msinteger
Loose#
A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.