dimesumdevelopers API reference Console Open the app

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#

GET/v1/mescope: read

The account the key belongs to.

200OK

An object of type Me.

  • idstring · uuid
  • display_namestring
  • emailstring · email
  • timezonestring
    Example "Asia/Kolkata"
  • preferred_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • avatar_urlstring · uri
Example response
Illustrative values
{
  "id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
  "display_name": "Asha",
  "preferred_currency": "INR"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/me" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Groups#

List groups#

GET/v1/groupsscope: read

Every group you are in, with your position in each.

200OK
  • groupsarray of object (GroupRow)
    Child fields of groups
    • idstring · uuid
    • namestring
    • default_currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • kindstring
      One of "GROUP" "QUICK"
    • member_countinteger
    • created_atstring · date-time
    • read_onlyboolean
    • archivedboolean
      You archived it in the app: hidden from your own home screen and pickers, nobody else's. Its money still counts everywhere.
    • squareboolean
      True 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_position
      • currencystring
        ISO 4217 code.
        Pattern ^[A-Z]{3}$Example "INR"
      • net_minorinteger · int64
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Example response
Illustrative values
{
  "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
        }
      ]
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Create a group#

POST/v1/groupsscope: write

You are its first member and owner.

  • idstring · uuidrequired
    A 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.
  • namestringrequired
    Up to 60 characters
  • default_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • timezonestring
201Created

An object of type GroupDetail.

  • idstring · uuid
  • namestring
  • default_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • timezonestring
  • kindstring
  • my_member_idstring · uuid
    Your own member id in this group.
  • owner_member_idstring · uuid
  • read_onlyboolean
  • membersarray of object (Member)
    Child fields of members
    • idstring · uuid
      The member id. Bills and payments name people by this.
    • display_namestring
    • is_ghostboolean
      A kept place: somebody without an account (yet).
    • user_idstring · uuid
      The account behind the member, when there is one.
    • avatar_urlstring · uri
Example response
Illustrative values
{
  "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"
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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"
}
EOF

Try it in the console

Get a group#

GET/v1/groups/{groupID}scope: read

Members (with member ids), currency and settings.

  • groupIDstring · uuid · in pathrequired
    The group's id.
200OK

An object of type GroupDetail.

  • idstring · uuid
  • namestring
  • default_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • timezonestring
  • kindstring
  • my_member_idstring · uuid
    Your own member id in this group.
  • owner_member_idstring · uuid
  • read_onlyboolean
  • membersarray of object (Member)
    Child fields of members
    • idstring · uuid
      The member id. Bills and payments name people by this.
    • display_namestring
    • is_ghostboolean
      A kept place: somebody without an account (yet).
    • user_idstring · uuid
      The account behind the member, when there is one.
    • avatar_urlstring · uri
Example response
Illustrative values
{
  "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"
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Add a kept place#

POST/v1/groups/{groupID}/membersscope: write

A 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.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • idstring · uuidrequired
    A 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_namestringrequired
  • emailstring
  • phonestring
    E.164
  • offer_user_idstring · uuid
201Created

An object of type Member.

  • idstring · uuid
    The member id. Bills and payments name people by this.
  • display_namestring
  • is_ghostboolean
    A kept place: somebody without an account (yet).
  • user_idstring · uuid
    The account behind the member, when there is one.
  • avatar_urlstring · uri
Example response
Illustrative values
{
  "id": "0192f3a4-1b7d-7e22-8c31-6a9d0e4f2b17",
  "display_name": "Asha",
  "is_ghost": true,
  "user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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

Try it in the console

Who can edit bills#

GET/v1/groups/{groupID}/editorsscope: read

The group's editor policy. Anyone may always change a bill they added.

  • groupIDstring · uuid · in pathrequired
    The group's id.
200OK

An object of type Editors.

  • modestring
    OWNER: 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
Illustrative values
{
  "mode": "OWNER",
  "member_ids": [
    "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01"
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/editors" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Expenses#

List bills#

GET/v1/groups/{groupID}/expensesscope: read

Newest first, paged. Deleted bills stay in the list with deleted=true.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • limitinteger · in query
    1 to 100, 20 by default.
  • cursorstring · in query
    From next_cursor.
200OK

An object of type ExpensePage.

  • expensesarray of object (Expense)
    Child fields of expenses
    • idstring · uuid
    • group_idstring · uuid
    • versioninteger
      Bumps on every edit; an edit must name the version it read.
    • deletedboolean
    • descriptionstring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • group_currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • fx_ratestring
      Group currency per unit of this bill's currency, as a decimal string.
    • amount_group_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • needs_fx_rateboolean
    • display_currencystring
      The 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_ratestring
      The 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 · date
      The date the rate was published for.
    • display_rate_sourcestring
      Who published the rate, e.g. ECB.
    • split_typestring
      One of "EQUAL" "EXACT" "PERCENT" "SHARES"
    • occurred_onstring · date
      A calendar date, YYYY-MM-DD.
    • created_atstring · date-time
    • created_by_member_idstring · uuid
    • read_onlyboolean
    • locationobject (Location)
      Child fields of location
      • namestring
      • latnumber
      • lngnumber
    • categorystring or null
      What the bill was for, from a fixed list. Null: uncategorised.
      One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
    • category_sourcestring or null
      USER: 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" null
    • can_editboolean
      On 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 splits
      • member_idstring · uuid
      • share_minorinteger · int64
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
      • paid_minorinteger · int64
        Money 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 items
      • descriptionstring
      • amount_minorinteger · int64required
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
      • assigneesarray of string · uuid
        Who 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 shares
        • member_idstring · uuidrequired
        • valueintegerrequired
    • poolsarray of object (Pool)
      On a single bill by item: its tax, tip, fees and discounts, in order.
      Child fields of pools
      • kindstringrequired
        One of "TAX" "TIP" "FEE" "DISCOUNT"
      • labelstring
        The bill's own word for it, e.g. GST.
      • amount_minorinteger
        A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
      • rate_bpinteger
        A 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_cursorstring
    Pass as ?cursor= for the next page; absent on the last.
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses?limit=50" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Add a bill#

POST/v1/groups/{groupID}/expensesscope: write

Split equally among everyone unless you say otherwise; you paid unless payers says otherwise.

  • groupIDstring · uuid · in pathrequired
    The group's id.

An object of type ExpenseCreate.

  • idstring · uuidrequired
    A 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.
  • descriptionstringrequired
    Up to 120 characters
  • amount_minorinteger
    In the currency's minor unit. Required unless the bill is by item (items).
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"Default "EQUAL"
  • participantsarray of string · uuid
    Member 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 payers
    • member_idstring · uuidrequired
    • paid_minorinteger · int64required
      Money 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 shares
    • member_idstring · uuidrequired
    • valueintegerrequired
  • percentsarray of object (MemberValue)
    PERCENT: basis points (100% = 10000).
    Child fields of percents
    • member_idstring · uuidrequired
    • valueintegerrequired
  • weightsarray of object (MemberValue)
    SHARES: relative weights.
    Child fields of weights
    • member_idstring · uuidrequired
    • valueintegerrequired
  • 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    With items: tax, tip, fees and discounts, in the order the bill prints them.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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 · date
    A calendar date, YYYY-MM-DD.
  • fx_ratestring
    For a bill converted into another currency: convert_to's currency (the group's when convert_to is left out) per unit.
  • convert_tostring
    The 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 location
    • namestring
    • latnumber
    • lngnumber
  • categorystring
    Optional. 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"
201Created

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses" \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "id": "$(uuidgen)",
  "description": "Dinner at Thalassa",
  "amount_minor": 120000,
  "currency": "INR",
  "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

Try it in the console

Get a bill#

GET/v1/groups/{groupID}/expenses/{expenseID}scope: read

With its split inputs, version and can_edit for you.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.
200OK

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Edit a bill#

PATCH/v1/groups/{groupID}/expenses/{expenseID}scope: write

Restate 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'.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.

An object of type ExpenseAmend.

  • revision_idstring · uuidrequired
    A 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
    The version you read. A stale one is refused (409 stale_version).
  • descriptionstringrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • fx_ratestring
    As on create.
  • convert_tostring
    The 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_typestringrequired
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • participantsarray of string · uuidrequired
  • payersarray of object (Payer)
    Child fields of payers
    • member_idstring · uuidrequired
    • paid_minorinteger · int64required
      Money 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 shares
    • member_idstring · uuidrequired
    • valueintegerrequired
  • percentsarray of object (MemberValue)
    Child fields of percents
    • member_idstring · uuidrequired
    • valueintegerrequired
  • weightsarray of object (MemberValue)
    Child fields of weights
    • member_idstring · uuidrequired
    • valueintegerrequired
  • itemsarray of object (Item)
    Restate the lines, or the bill stops being by item.
    Child fields of items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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 null
    The 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
200OK

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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

Try it in the console

Delete a bill#

DELETE/v1/groups/{groupID}/expenses/{expenseID}scope: write

A tombstone: the ledger reverses it and the history keeps it.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.

An object of type ExpenseDelete.

  • revision_idstring · uuidrequired
    A 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
200OK

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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

Try it in the console

A bill's history#

GET/v1/groups/{groupID}/expenses/{expenseID}/revisionsscope: read

One snapshot per version.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.
200OK
  • revisionsarray of object (Revision)
    Child fields of revisions
    • versioninteger
    • actionstring
    • atstring · date-time
Example response
Illustrative values
{
  "revisions": [
    {
      "version": 1,
      "action": "string",
      "at": "2026-09-28T09:30:00Z"
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/revisions" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

A bill's comments#

GET/v1/groups/{groupID}/expenses/{expenseID}/commentsscope: read

Oldest first; deleted ones stay as tombstones.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.
200OK
  • commentsarray of object (Comment)
    Child fields of comments
    • idstring · uuid
    • author_member_idstring · uuid
    • bodystring
    • created_atstring · date-time
    • editedboolean
    • deletedboolean
Example response
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/expenses/$EXPENSE_ID/comments" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Comment on a bill#

POST/v1/groups/{groupID}/expenses/{expenseID}/commentsscope: write

Up to 30 per member per hour, 200 per bill.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.

An object of type CommentCreate.

  • idstring · uuidrequired
    A 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.
  • bodystringrequired
    Up to 1000 characters
201Created

An object of type Comment.

  • idstring · uuid
  • author_member_idstring · uuid
  • bodystring
  • created_atstring · date-time
  • editedboolean
  • deletedboolean
Example response
Illustrative values
{
  "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
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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

Try it in the console

Set a bill's rate#

PUT/v1/groups/{groupID}/expenses/{expenseID}/fx-ratescope: write

For a bill in another currency: group currency per unit, e.g. "0.5624".

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • expenseIDstring · uuid · in pathrequired
    The bill's id.
  • ratestringrequired
200OK

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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"
}'

Try it in the console

Balances#

Balances across every group#

GET/v1/me/balancesscope: read

Every 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.

  • cursorstring · in query
    From next_cursor.
200OK

An object of type MeBalances.

  • groupsarray of object
    Child fields of groups
    • group_idstring · uuid
    • namestring
    • default_currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • my_member_idstring · uuid
    • membersarray of object (MemberBalance)
      Child fields of members
      • member_idstring · uuid
      • display_namestring
      • is_ghostboolean
      • balancesarray of object (CurrencyBalance)
        Per currency. Positive: the group owes this member; negative: they owe the group.
        Child fields of balances
        • currencystring
          ISO 4217 code.
          Pattern ^[A-Z]{3}$Example "INR"
        • balance_minorinteger · int64
          Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • next_cursorstring
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/me/balances" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Group balances#

GET/v1/groups/{groupID}/balancesscope: read

Each member's balance per currency.

  • groupIDstring · uuid · in pathrequired
    The group's id.
200OK

An object of type Balances.

  • balancesarray of object (MemberBalance)
    Child fields of balances
    • member_idstring · uuid
    • display_namestring
    • is_ghostboolean
    • balancesarray of object (CurrencyBalance)
      Per currency. Positive: the group owes this member; negative: they owe the group.
      Child fields of balances
      • currencystring
        ISO 4217 code.
        Pattern ^[A-Z]{3}$Example "INR"
      • balance_minorinteger · int64
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
Example response
Illustrative values
{
  "balances": [
    {
      "member_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d02",
      "display_name": "Asha",
      "is_ghost": true,
      "balances": [
        {
          "currency": "INR",
          "balance_minor": 1
        }
      ]
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/balances" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Settling#

Payments#

GET/v1/groups/{groupID}/settlementsscope: read

Newest first, paged.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • cursorstring · in query
    From next_cursor.
200OK
  • settlementsarray of object (Settlement)
    Child fields of settlements
    • idstring · uuid
    • from_member_idstring · uuid
    • to_member_idstring · uuid
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • statusstring
      One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
    • methodstring
    • referencestring
    • batch_idstring · uuid
      Set when this payment is one leg of a transfer that cleared several groups.
    • created_atstring · date-time
  • next_cursorstring
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/settlements" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Record a payment#

POST/v1/groups/{groupID}/settlementsscope: write

Something you paid in your own app or in cash. Any positive amount: more than you owe leaves them owing you the difference.

  • groupIDstring · uuid · in pathrequired
    The group's id.

An object of type SettlementCreate.

  • idstring · uuidrequired
    A 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 · uuidrequired
    Must be your own member id.
  • to_member_idstring · uuidrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • methodstring
    One of "UPI" "CASH" "OTHER" "PAYPAL" "VENMO" "CASHAPP" "WISE" "REVOLUT" "ZELLE" "PAYNOW" "PIX" "IBAN" "BANK"
  • referencestring
    The payment app's reference, for the other person to find.
  • notestring
  • batch_idstring · uuid
    Optional. 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).
201Created

An object of type Settlement.

  • idstring · uuid
  • from_member_idstring · uuid
  • to_member_idstring · uuid
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • statusstring
    One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
  • methodstring
  • referencestring
  • batch_idstring · uuid
    Set when this payment is one leg of a transfer that cleared several groups.
  • created_atstring · date-time
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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

Try it in the console

Confirm a payment#

POST/v1/groups/{groupID}/settlements/{settlementID}/confirmscope: write

As the person paid.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • settlementIDstring · uuid · in pathrequired
    The payment's id.

An empty object: send {}.

200OK

An object of type Settlement.

  • idstring · uuid
  • from_member_idstring · uuid
  • to_member_idstring · uuid
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • statusstring
    One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
  • methodstring
  • referencestring
  • batch_idstring · uuid
    Set when this payment is one leg of a transfer that cleared several groups.
  • created_atstring · date-time
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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 '{}'

Try it in the console

Dispute a payment#

POST/v1/groups/{groupID}/settlements/{settlementID}/disputescope: write

As the person paid: the money did not arrive. The payment is reversed.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • settlementIDstring · uuid · in pathrequired
    The payment's id.

An empty object: send {}.

200OK

An object of type Settlement.

  • idstring · uuid
  • from_member_idstring · uuid
  • to_member_idstring · uuid
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • statusstring
    One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
  • methodstring
  • referencestring
  • batch_idstring · uuid
    Set when this payment is one leg of a transfer that cleared several groups.
  • created_atstring · date-time
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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 '{}'

Try it in the console

One payment across groups#

GET/v1/settlement-batches/{batchID}scope: read

Every leg of a transfer that cleared several groups, in the groups you share.

  • batchIDstring · uuid · in pathrequired
    The transfer's batch id.
200OK

An object of type SettlementBatch.

  • batch_idstring · uuid
  • legsarray of object
    Child fields of legs
    • idstring · uuid
    • group_idstring · uuid
    • group_namestring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • statusstring
      One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
    • fromobject
      Child fields of from
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
    • toobject
      Child fields of to
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
Example response
Illustrative values
{
  "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"
      }
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Confirm a payment across groups#

POST/v1/settlement-batches/{batchID}/confirmscope: write

As the other person: confirms every leg you are the counterparty of, once.

  • batchIDstring · uuid · in pathrequired
    The transfer's batch id.

An empty object: send {}.

200OK

An object of type SettlementBatch.

  • batch_idstring · uuid
  • legsarray of object
    Child fields of legs
    • idstring · uuid
    • group_idstring · uuid
    • group_namestring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • statusstring
      One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
    • fromobject
      Child fields of from
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
    • toobject
      Child fields of to
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
Example response
Illustrative values
{
  "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"
      }
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID/confirm" \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Try it in the console

Dispute a payment across groups#

POST/v1/settlement-batches/{batchID}/disputescope: write

As the other person: the money did not arrive. Every leg is reversed.

  • batchIDstring · uuid · in pathrequired
    The transfer's batch id.

An empty object: send {}.

200OK

An object of type SettlementBatch.

  • batch_idstring · uuid
  • legsarray of object
    Child fields of legs
    • idstring · uuid
    • group_idstring · uuid
    • group_namestring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • statusstring
      One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
    • fromobject
      Child fields of from
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
    • toobject
      Child fields of to
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
Example response
Illustrative values
{
  "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"
      }
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/settlement-batches/$BATCH_ID/dispute" \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Try it in the console

Forgiven debts#

GET/v1/groups/{groupID}/write-offsscope: read

Debts a creditor forgave (write-offs are made in the app).

  • groupIDstring · uuid · in pathrequired
    The group's id.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/write-offs" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Repeats#

Repeats#

GET/v1/groups/{groupID}/recurringscope: read

The group's standing instructions (rent, subscriptions).

  • groupIDstring · uuid · in pathrequired
    The group's id.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/recurring" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Create a repeat#

POST/v1/groups/{groupID}/recurringscope: write

Posts an ordinary bill on schedule; each occurrence is idempotent per period.

  • groupIDstring · uuid · in pathrequired
    The group's id.

An object of type RecurringCreate.

  • idstring · uuidrequired
    A 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.
  • descriptionstringrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • split_typestring
  • participantsarray of string · uuid
  • freqstringrequired
    One of "DAILY" "WEEKLY" "MONTHLY"
  • day_of_monthinteger
    1 to 28
  • weekdayinteger
    0 to 6
  • start_onstring · date
    A calendar date, YYYY-MM-DD.
  • source_expense_idstring · uuid
    The bill this repeats, when switched on from one.
201Created

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/recurring" \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "id": "$(uuidgen)",
  "description": "Rent",
  "amount_minor": 4500000,
  "currency": "INR",
  "freq": "MONTHLY",
  "day_of_month": 1
}
EOF

Try it in the console

Capture#

Read a line into a draft#

POST/v1/capturesscope: write

A 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.

An object of type CaptureCreate.

  • idstring · uuidrequired
    A 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 · uuidrequired
  • textstringrequired
    A line in plain words, e.g. "dinner 1200 with Ravi and Priya, I paid".
    Up to 2000 characters
201Created

An object of type Suggestion.

  • idstring · uuid
  • group_idstring · uuid
  • statusstring
    One of "PENDING" "CONFIRMED" "DISMISSED"
  • descriptionstring
  • amount_minorinteger or null
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • textstring
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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"
}
EOF

Try it in the console

Suggestions#

GET/v1/suggestionsscope: read

Drafts waiting to be confirmed.

200OK
  • suggestionsarray of object (Suggestion)
    Child fields of suggestions
    • idstring · uuid
    • group_idstring · uuid
    • statusstring
      One of "PENDING" "CONFIRMED" "DISMISSED"
    • descriptionstring
    • amount_minorinteger or null
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • textstring
Example response
Illustrative values
{
  "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"
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/suggestions" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

A suggestion#

GET/v1/suggestions/{suggestionID}scope: read
  • suggestionIDstring · uuid · in pathrequired
    The suggestion's id.
200OK

An object of type Suggestion.

  • idstring · uuid
  • group_idstring · uuid
  • statusstring
    One of "PENDING" "CONFIRMED" "DISMISSED"
  • descriptionstring
  • amount_minorinteger or null
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • textstring
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/suggestions/$SUGGESTION_ID" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Confirm a suggestion#

POST/v1/suggestions/{suggestionID}/confirmscope: write

Posts it as a bill, with anything you correct. Idempotent: the bill's id comes from the suggestion's.

  • suggestionIDstring · uuid · in pathrequired
    The suggestion's id.

An object of type SuggestionConfirm.

  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • descriptionstring
  • participantsarray of string · uuid
200OK

An object of type Expense.

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
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"
}'

Try it in the console

Dismiss a suggestion#

POST/v1/suggestions/{suggestionID}/dismissscope: write
  • suggestionIDstring · uuid · in pathrequired
    The suggestion's id.

An empty object: send {}.

200OK

An object of type Suggestion.

  • idstring · uuid
  • group_idstring · uuid
  • statusstring
    One of "PENDING" "CONFIRMED" "DISMISSED"
  • descriptionstring
  • amount_minorinteger or null
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • textstring
Example response
Illustrative values
{
  "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"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/suggestions/$SUGGESTION_ID/dismiss" \
  -H "Authorization: Bearer $DIMESUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Try it in the console

Activity#

Your activity feed#

GET/v1/me/activityscope: read

What happened across your groups, newest last, as a delta from a cursor.

  • sincestring · in query
    A cursor from the previous read.
  • limitinteger · in query
    Up to 500.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/me/activity?limit=50" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

A group's activity feed#

GET/v1/groups/{groupID}/activityscope: read

Bills, edits, payments and members joining, as a delta from a cursor.

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • sincestring · in query
    Cursor.
  • limitinteger · in query
    Up to 500.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/activity?limit=50" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Insights#

Your spending insights#

GET/v1/me/insightsscope: read

Your 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).

  • monthstring · in query
    YYYY-MM; this month by default.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/me/insights?month=2026-09" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Group insights#

GET/v1/groups/{groupID}/insightsscope: read

The group's spending for a month: totals, by member, by day, by category (by_category, my_by_category; category null is the uncategorised bucket).

  • groupIDstring · uuid · in pathrequired
    The group's id.
  • monthstring · in query
    YYYY-MM.
200OK

An object of type Loose.

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/groups/$GROUP_ID/insights?month=2026-09" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

People#

People you keep#

GET/v1/peoplescope: read

People added by their code or phone number, outside any group.

200OK
  • peoplearray of object (Person)
    Child fields of people
    • user_idstring · uuid
    • display_namestring
    • avatar_urlstring
    • viastring
      One of "CODE" "PHONE"
    • sincestring · date-time
Example response
Illustrative values
{
  "people": [
    {
      "user_id": "0192f3a1-7c2e-7d4b-9a10-5b8e2f6c1d01",
      "display_name": "Asha",
      "via": "CODE",
      "since": "2026-09-28T09:30:00Z"
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/people" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Rates#

A market rate#

GET/v1/fx/quotescope: read

The latest published rate between two currencies, for reference.

  • fromstring · in query
    ISO code.
  • tostring · in query
    ISO code.
200OK

An object of type FXQuote.

  • fromstring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • tostring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • ratestring
  • as_ofstring · date
    A calendar date, YYYY-MM-DD.
Example response
Illustrative values
{
  "from": "INR",
  "to": "INR",
  "rate": "0.5624",
  "as_of": "2026-09-28"
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/fx/quote?from=USD&to=INR" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

Developer#

This key#

GET/v1/developer/keyscope: read

Which key is calling, its scopes, its limits and its recent requests.

200OK

An object of type DeveloperKey.

  • keyobject
    Child fields of key
    • idstring · uuid
    • namestring
    • prefixstring
      Example "dms_live_Ab3x"
    • scopesarray of string
    • enabledboolean
    • created_atstring · date-time
    • last_used_atstring · date-time
  • user_idstring · uuid
  • rate_limitobject
    Child fields of rate_limit
    • per_secondnumber
    • burstinteger
  • requestsarray of object
    Child fields of requests
    • atstring · date-time
    • methodstring
    • pathstring
    • statusinteger
    • duration_msinteger
Example response
Illustrative values
{
  "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
    }
  ]
}
4XXA refusal with a stable code: the error envelope. See error codes.
curl
curl "https://api.dimesum.com/v1/developer/key" \
  -H "Authorization: Bearer $DIMESUM_API_KEY"

Try it in the console

MCP endpoint#

POST/mcpscope: read

Model 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.

  • jsonrpcstring
    One of "2.0"
  • idany
  • methodstring
  • paramsobject
200OK

An object. The fields worth knowing are in Concepts: report objects.

4XXA refusal with a stable code: the error envelope. See error codes.
curl
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"
}'

Try it in the console

Objects#

Every named schema the operations above refer to.

Error#

  • errorobjectrequired
    Child fields of error
    • codestringrequired
      A stable, machine-readable reason, e.g. not_found, api_key_read_only, not_editor.
    • messagestringrequired
      A sentence for a person.

Money#

  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • net_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.

Me#

  • idstring · uuid
  • display_namestring
  • emailstring · email
  • timezonestring
    Example "Asia/Kolkata"
  • preferred_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • avatar_urlstring · uri

GroupRow#

  • idstring · uuid
  • namestring
  • default_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • kindstring
    One of "GROUP" "QUICK"
  • member_countinteger
  • created_atstring · date-time
  • read_onlyboolean
  • archivedboolean
    You archived it in the app: hidden from your own home screen and pickers, nobody else's. Its money still counts everywhere.
  • squareboolean
    True 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_position
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • net_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.

Member#

  • idstring · uuid
    The member id. Bills and payments name people by this.
  • display_namestring
  • is_ghostboolean
    A kept place: somebody without an account (yet).
  • user_idstring · uuid
    The account behind the member, when there is one.
  • avatar_urlstring · uri

GroupDetail#

  • idstring · uuid
  • namestring
  • default_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • timezonestring
  • kindstring
  • my_member_idstring · uuid
    Your own member id in this group.
  • owner_member_idstring · uuid
  • read_onlyboolean
  • membersarray of object (Member)
    Child fields of members
    • idstring · uuid
      The member id. Bills and payments name people by this.
    • display_namestring
    • is_ghostboolean
      A kept place: somebody without an account (yet).
    • user_idstring · uuid
      The account behind the member, when there is one.
    • avatar_urlstring · uri

Split#

  • member_idstring · uuid
  • share_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • paid_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.

Location#

  • namestring
  • latnumber
  • lngnumber

Expense#

  • idstring · uuid
  • group_idstring · uuid
  • versioninteger
    Bumps on every edit; an edit must name the version it read.
  • deletedboolean
  • descriptionstring
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • group_currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • fx_ratestring
    Group currency per unit of this bill's currency, as a decimal string.
  • amount_group_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • needs_fx_rateboolean
  • display_currencystring
    The 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_ratestring
    The 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 · date
    The date the rate was published for.
  • display_rate_sourcestring
    Who published the rate, e.g. ECB.
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • created_atstring · date-time
  • created_by_member_idstring · uuid
  • read_onlyboolean
  • locationobject (Location)
    Child fields of location
    • namestring
    • latnumber
    • lngnumber
  • categorystring or null
    What the bill was for, from a fixed list. Null: uncategorised.
    One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
  • category_sourcestring or null
    USER: 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" null
  • can_editboolean
    On 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 splits
    • member_idstring · uuid
    • share_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • paid_minorinteger · int64
      Money 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    On a single bill by item: its tax, tip, fees and discounts, in order.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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 expenses
    • idstring · uuid
    • group_idstring · uuid
    • versioninteger
      Bumps on every edit; an edit must name the version it read.
    • deletedboolean
    • descriptionstring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • group_currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • fx_ratestring
      Group currency per unit of this bill's currency, as a decimal string.
    • amount_group_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • needs_fx_rateboolean
    • display_currencystring
      The 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_ratestring
      The 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 · date
      The date the rate was published for.
    • display_rate_sourcestring
      Who published the rate, e.g. ECB.
    • split_typestring
      One of "EQUAL" "EXACT" "PERCENT" "SHARES"
    • occurred_onstring · date
      A calendar date, YYYY-MM-DD.
    • created_atstring · date-time
    • created_by_member_idstring · uuid
    • read_onlyboolean
    • locationobject (Location)
      Child fields of location
      • namestring
      • latnumber
      • lngnumber
    • categorystring or null
      What the bill was for, from a fixed list. Null: uncategorised.
      One of "food_dining" "groceries" "transport" "travel" "stay" "rent" "utilities" "entertainment" "shopping" "other" null
    • category_sourcestring or null
      USER: 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" null
    • can_editboolean
      On 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 splits
      • member_idstring · uuid
      • share_minorinteger · int64
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
      • paid_minorinteger · int64
        Money 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 items
      • descriptionstring
      • amount_minorinteger · int64required
        Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
      • assigneesarray of string · uuid
        Who 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 shares
        • member_idstring · uuidrequired
        • valueintegerrequired
    • poolsarray of object (Pool)
      On a single bill by item: its tax, tip, fees and discounts, in order.
      Child fields of pools
      • kindstringrequired
        One of "TAX" "TIP" "FEE" "DISCOUNT"
      • labelstring
        The bill's own word for it, e.g. GST.
      • amount_minorinteger
        A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
      • rate_bpinteger
        A 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_cursorstring
    Pass as ?cursor= for the next page; absent on the last.

Payer#

  • member_idstring · uuidrequired
  • paid_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.

MemberValue#

  • member_idstring · uuidrequired
  • valueintegerrequired

Item#

One line of a bill by item.

  • descriptionstring
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • assigneesarray of string · uuid
    Who 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 shares
    • member_idstring · uuidrequired
    • valueintegerrequired

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.

  • kindstringrequired
    One of "TAX" "TIP" "FEE" "DISCOUNT"
  • labelstring
    The bill's own word for it, e.g. GST.
  • amount_minorinteger
    A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
  • rate_bpinteger
    A 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 · uuidrequired
    A 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.
  • descriptionstringrequired
    Up to 120 characters
  • amount_minorinteger
    In the currency's minor unit. Required unless the bill is by item (items).
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • split_typestring
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"Default "EQUAL"
  • participantsarray of string · uuid
    Member 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 payers
    • member_idstring · uuidrequired
    • paid_minorinteger · int64required
      Money 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 shares
    • member_idstring · uuidrequired
    • valueintegerrequired
  • percentsarray of object (MemberValue)
    PERCENT: basis points (100% = 10000).
    Child fields of percents
    • member_idstring · uuidrequired
    • valueintegerrequired
  • weightsarray of object (MemberValue)
    SHARES: relative weights.
    Child fields of weights
    • member_idstring · uuidrequired
    • valueintegerrequired
  • 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 items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    With items: tax, tip, fees and discounts, in the order the bill prints them.
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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 · date
    A calendar date, YYYY-MM-DD.
  • fx_ratestring
    For a bill converted into another currency: convert_to's currency (the group's when convert_to is left out) per unit.
  • convert_tostring
    The 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 location
    • namestring
    • latnumber
    • lngnumber
  • categorystring
    Optional. 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 · uuidrequired
    A 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
    The version you read. A stale one is refused (409 stale_version).
  • descriptionstringrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • occurred_onstring · date
    A calendar date, YYYY-MM-DD.
  • fx_ratestring
    As on create.
  • convert_tostring
    The 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_typestringrequired
    One of "EQUAL" "EXACT" "PERCENT" "SHARES"
  • participantsarray of string · uuidrequired
  • payersarray of object (Payer)
    Child fields of payers
    • member_idstring · uuidrequired
    • paid_minorinteger · int64required
      Money 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 shares
    • member_idstring · uuidrequired
    • valueintegerrequired
  • percentsarray of object (MemberValue)
    Child fields of percents
    • member_idstring · uuidrequired
    • valueintegerrequired
  • weightsarray of object (MemberValue)
    Child fields of weights
    • member_idstring · uuidrequired
    • valueintegerrequired
  • itemsarray of object (Item)
    Restate the lines, or the bill stops being by item.
    Child fields of items
    • descriptionstring
    • amount_minorinteger · int64required
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • assigneesarray of string · uuid
      Who 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 shares
      • member_idstring · uuidrequired
      • valueintegerrequired
  • poolsarray of object (Pool)
    Child fields of pools
    • kindstringrequired
      One of "TAX" "TIP" "FEE" "DISCOUNT"
    • labelstring
      The bill's own word for it, e.g. GST.
    • amount_minorinteger
      A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate.
    • rate_bpinteger
      A 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 null
    The 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 · uuidrequired
    A 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#

  • versioninteger
  • actionstring
  • atstring · date-time

Comment#

  • idstring · uuid
  • author_member_idstring · uuid
  • bodystring
  • created_atstring · date-time
  • editedboolean
  • deletedboolean

CommentCreate#

  • idstring · uuidrequired
    A 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.
  • bodystringrequired
    Up to 1000 characters

CurrencyBalance#

  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • balance_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.

MemberBalance#

  • member_idstring · uuid
  • display_namestring
  • is_ghostboolean
  • balancesarray of object (CurrencyBalance)
    Per currency. Positive: the group owes this member; negative: they owe the group.
    Child fields of balances
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • balance_minorinteger · int64
      Money 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 balances
    • member_idstring · uuid
    • display_namestring
    • is_ghostboolean
    • balancesarray of object (CurrencyBalance)
      Per currency. Positive: the group owes this member; negative: they owe the group.
      Child fields of balances
      • currencystring
        ISO 4217 code.
        Pattern ^[A-Z]{3}$Example "INR"
      • balance_minorinteger · int64
        Money 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 object
    Child fields of groups
    • group_idstring · uuid
    • namestring
    • default_currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • my_member_idstring · uuid
    • membersarray of object (MemberBalance)
      Child fields of members
      • member_idstring · uuid
      • display_namestring
      • is_ghostboolean
      • balancesarray of object (CurrencyBalance)
        Per currency. Positive: the group owes this member; negative: they owe the group.
        Child fields of balances
        • currencystring
          ISO 4217 code.
          Pattern ^[A-Z]{3}$Example "INR"
        • balance_minorinteger · int64
          Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • next_cursorstring

Settlement#

  • idstring · uuid
  • from_member_idstring · uuid
  • to_member_idstring · uuid
  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • statusstring
    One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
  • methodstring
  • referencestring
  • batch_idstring · uuid
    Set 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 · uuid
  • legsarray of object
    Child fields of legs
    • idstring · uuid
    • group_idstring · uuid
    • group_namestring
    • amount_minorinteger · int64
      Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
    • currencystring
      ISO 4217 code.
      Pattern ^[A-Z]{3}$Example "INR"
    • statusstring
      One of "RECORDED" "POSTED" "CONFIRMED" "REVERSED"
    • fromobject
      Child fields of from
      • member_idstring · uuid
      • user_idstring · uuid
      • display_namestring
    • toobject
      Child fields of to
      • member_idstring · uuid
      • user_idstring · uuid
      • display_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 · uuidrequired
    A 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 · uuidrequired
    Must be your own member id.
  • to_member_idstring · uuidrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • methodstring
    One of "UPI" "CASH" "OTHER" "PAYPAL" "VENMO" "CASHAPP" "WISE" "REVOLUT" "ZELLE" "PAYNOW" "PIX" "IBAN" "BANK"
  • referencestring
    The payment app's reference, for the other person to find.
  • notestring
  • batch_idstring · uuid
    Optional. 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 · uuidrequired
    A 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.
  • descriptionstringrequired
  • amount_minorinteger · int64required
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • split_typestring
  • participantsarray of string · uuid
  • freqstringrequired
    One of "DAILY" "WEEKLY" "MONTHLY"
  • day_of_monthinteger
    1 to 28
  • weekdayinteger
    0 to 6
  • start_onstring · date
    A calendar date, YYYY-MM-DD.
  • source_expense_idstring · uuid
    The bill this repeats, when switched on from one.

CaptureCreate#

  • idstring · uuidrequired
    A 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 · uuidrequired
  • textstringrequired
    A 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 · uuid
  • group_idstring · uuid
  • statusstring
    One of "PENDING" "CONFIRMED" "DISMISSED"
  • descriptionstring
  • amount_minorinteger or null
  • currencystring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • textstring

SuggestionConfirm#

  • amount_minorinteger · int64
    Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.
  • descriptionstring
  • participantsarray of string · uuid

Person#

  • user_idstring · uuid
  • display_namestring
  • avatar_urlstring
  • viastring
    One of "CODE" "PHONE"
  • sincestring · date-time

Editors#

  • modestring
    OWNER: the owner and member_ids may change anybody's bill. EVERYONE: all members may.
    One of "OWNER" "EVERYONE"
  • member_idsarray of string · uuid

FXQuote#

  • fromstring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • tostring
    ISO 4217 code.
    Pattern ^[A-Z]{3}$Example "INR"
  • ratestring
  • as_ofstring · date
    A calendar date, YYYY-MM-DD.

DeveloperKey#

  • keyobject
    Child fields of key
    • idstring · uuid
    • namestring
    • prefixstring
      Example "dms_live_Ab3x"
    • scopesarray of string
    • enabledboolean
    • created_atstring · date-time
    • last_used_atstring · date-time
  • user_idstring · uuid
  • rate_limitobject
    Child fields of rate_limit
    • per_secondnumber
    • burstinteger
  • requestsarray of object
    Child fields of requests
    • atstring · date-time
    • methodstring
    • pathstring
    • statusinteger
    • duration_msinteger

Loose#

A report object; see the guide for its fields. The fields worth knowing are in Concepts: report objects.