wishlist: date filtering based on `posted` instead of `transacted_at`

[tianon]

I don't know if this is specific to the account I'm querying, but start-date and end-date (/accounts?start-date=...&end-date=...) appear to filter based on transacted_at -- this isn't clear in the protocol documentation (which is perhaps lower-hanging fruit), but it would actually be really nice for my own use case if I could somehow filter by posted instead. ❤️

Here's a slightly redacted (but otherwise 100% real) example transaction that doesn't show up if my start-date is 1754031600 (2025-08-01T07:00:00Z), but does show up if start-date is 1753945200 (2025-07-31T07:00:00Z).

I then tried even more specific start-date and end-date values to perfectly wrap this one transaction (transacted_at - 1 and transacted_at + 1 and then the same with posted) and got exactly the results I expected:

$ curl -fsSL "$url/accounts?account=$account&start-date=1753963199&end-date=1753963201" | jq '.accounts[].transactions | map(select(.payee == "Taco Bell") | .id |= gsub("[a-z0-9]"; "x") | .description |= "TACO BELL")'
[
  {
    "id": "TRN-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "posted": 1754049600,
    "amount": "-12.98",
    "description": "TACO BELL",
    "payee": "Taco Bell",
    "memo": "",
    "transacted_at": 1753963200
  }
]

$ curl -fsSL "$url/accounts?account=$account&start-date=1754049599&end-date=1754049601" | jq '.accounts[].transactions | map(select(.payee == "Taco Bell") | .id |= gsub("[a-z0-9]"; "x") | .description |= "TACO BELL")'
[]

(ie, start-date and end-date are based on transacted_at, not posted, and I don't see anything in the official protocol documentation that specifies whether that can be swapped 🙇)

It also comes back if I set end-date to 1753963200 exactly and leave start-date set to 1753963199, which is contrary to the documentation (and the same if I set start-date to 1753963200 and end-date to 1753963201):

Parameter	Required	Description
start-date	optional	If given, transactions will be restricted to those on or after this Unix epoch timestamp.
end-date	optional	If given, transactions will be restricted to those before (but not on) this Unix epoch timestamp.
pending	optional	If pending=1 is provided, pending transactions will be included (if supported). By default, pending transaction are NOT included.

So perhaps the documentation should also be updated to note that it's inclusive at both ends? 😅

---

That's all really rambly so here's the TLDR:

• start-date and end-date appear to filter based on transacted_at; it would be nice if the documentation mentioned this explicitly
• start-date and end-date appear to be inclusive at both ends, contrary to the documentation
• it would be really nice to be able to filter based on posted instead or as well as (especially since posted is the timestamp/date most bank web UIs show)

[iffy]

Thanks for filing this. I assumed that the date filtering was based on posted date, so I checked and it's ambiguous at our provider as well.

The other tricky thing is, while the spec lets you specify a timestamp with second precision, the SimpleFIN Bridge implementation (again, by virtue of what our provider allows) can only do day precision. I'm not sure if timestamps are "floored" or "ceiling'd" to the nearest midnight, but that's likely why you're seeing the strange behavior you mention.

That said, the API is meant to be a good start, but that apps will do whatever filtering is needed -- that is, apps should request slightly more of a window than they need (maybe a few days on either side) and filter the results locally.