An integration that sends documents eventually has to account for them: how many agreements went out this month, which of them are still unsigned, who they are waiting on, how long signing takes. This chapter covers the two endpoints that answer such questions directly, instead of walking through documents one at a time.
Two ways to read the same activity
-
Reports are itemized. One row per document, carrying the document's own data, its transaction, every recipient and the counts that go with them. You filter them down to a period, a category or a status, and page through the result. This is what you feed into your own tables, chase lists and monthly summaries.
-
Dashboards are aggregated. Each one is a predefined set of figures — documents by state, transactions per user — computed and returned as labeled data series ready to plot. No filters, no rows, just the numbers.
Both are read-only, and both are derived: they are computed from the documents and transactions that already exist, so nothing you do here changes anything. The vocabulary is the one the earlier chapters established — transactions, recipients, purposes and statuses — with figures wrapped around it.
Two neighbouring things live elsewhere, and the distinction is worth keeping straight. Exports produce files rather than figures, and are covered in Documents & Files. Audit logs record who did what, which is a different question from where the work stands; they are in Administration.
Worth knowing across the chapter
-
Both surfaces read the whole organization, so the key has to belong to an account inside one: an account that sits in no organization is refused with
403, however much else it may be allowed to do. Reports additionally need a permission of their own, beyond the one an ordinary document call takes; a dashboard needs no more than that ordinary permission. -
Reports are a collection like any other, with the same envelope, the same filters-must-all-match rule and the same cursor for walking a long result set — see Page through collections.
-
Figures are computed when you ask, so a report or a dashboard describes the moment you asked. Store what you need in order to compare one moment with another.
Where to start
Start with Report on your organization's transactions, which covers the filters, the anatomy of a row and how a transaction looks once it is over. Turn to Read a dashboard's data when you want figures to display rather than rows to process — it is the shorter of the two, and its output shape never varies.