Skip to main content
An attestation is a filable, monthly record that a watch was actually evaluated during a period, with the office-data horizon it covered and the outcome (including the negative outcome). It is the artifact a law firm keeps on file to show that a monitoring instruction was in force and was executed.
Requires an API key with the portfolios:manage scope. The period is a UTC calendar month. Omit period to get the previous (most recently closed) month.

​
What it proves, and what it does not

An attestation certifies that evaluation occurred against the stated data horizons: which query was in force, how many times it ran, the sync runs it consumed, and the office-data coverage timestamps it reached. It does not certify that every relevant mark was surfaced. Recall is bounded by connector coverage and the match strategy you configured. This is a deliberate bright line: the attestation is evidence of diligence and process, not a guarantee of exhaustive detection. The statement field states this in plain language, and the wording is subject to founder and counsel review.

​
The “no alert” versus “not looking” model

The whole point of an attestation is to make silence provable. If you received no alert for a period, the attestation shows whether that silence means “we looked and found nothing” or “we were not looking”.
  • We looked and found nothing. evaluations_count is greater than zero, changes_evaluated shows the volume assessed, match_count is 0, and there are no gaps. That is a real negative result you can rely on.
  • We were not looking. The period carries a gaps[] entry (see below), the office is marked no_evaluations (a supported office with zero evaluations in the period, disclosed with a full-period gap and no coverage claims), or the office is marked unsupported. A single office sync run that was skipped because it was too large to evaluate is disclosed the same way, as a budget_declined gap naming that run. Silence never implies coverage that did not happen.
If the watch is paused or disabled at the moment you fetch the artifact, the response carries watch_status_at_generation so the current state is on the record. Pause history within the period itself is not reconstructable in this version (there is no status audit trail yet); that is a documented limitation.

​
Per-office fields

Each entry in offices[] reports one office in the watch scope.

​
changes_evaluated is candidacy volume

changes_evaluated is the count of candidate changes assessed against your query, summed across the evaluations in the period. It is not a claim about how many records exist at the office. It tells you the volume of change the watch weighed before deciding there was nothing to alert on.

​
Coverage gaps

gaps[] is where honest degradation is disclosed. A gap is an interval in the period where the office-data coverage the watch had evaluated through fell behind the internal freshness target for that office. Gap disclosure is permanent: it stays in the artifact for that period even after coverage recovers, because it is a fact about what happened.
  • reason: "office_lagging" means coverage was stale beyond the office target for that interval.
  • reason: "evaluation_missing" means no evaluation ran for that interval at all, although one should have: an eligible office sync run has no evaluation receipt for this watch (a pause, a credit lock, or lease starvation), or there is no evaluation evidence for longer than the continuity backstop. Silence is never read as coverage.
  • reason: "budget_declined" means a specific office sync run was not evaluated at all. A run carrying an abnormally large number of changes (a bulk reload, for example) exceeds the evaluator’s per-run ceiling and is declined rather than partially processed. The gap names the run in sync_run_id and opens at the start of that run’s own office-data window, which is where the un-evaluated changes are. Later coverage does not close it: a subsequent run’s data horizon says nothing about the changes in the declined run. A decline that is still outstanding when a month ends is disclosed again in the following month’s attestation, clipped to that month, until it is closed.
  • resolved: true means coverage caught back up within the period (for office_lagging), or an operator closed the decline within the period (for budget_declined). resolved: false means it was still outstanding at the period boundary.
  • resolution appears on a resolved budget_declined gap and says how it was closed: redriven (the run was re-evaluated with a raised budget, so the changes were eventually assessed) or suppressed (an operator recorded the deliberate decision that this run will never be evaluated). Those are not the same claim, so we never collapse them into a bare resolved: true.
  • A declined run is disclosed once: it carries the richer budget_declined gap and is never also reported as evaluation_missing, even though it is by construction an eligible run without a receipt.
totals.declined_runs and totals.declined_runs_unresolved count these across every office in scope, and the statement says so in prose, so a declined run can never be lost in a per-office detail block. A period’s coverage_through timestamps are still exactly what the evaluations recorded; they simply do not attest to a declined window, which is what the gap makes explicit. What a closed month says about evaluation never changes retroactively: if a declined run is re-evaluated in August, the June and July artifacts still show the gap that was open at the time. August’s artifact is where the resolution appears. (Re-fetching an old period reproduces the same content_hash as long as the watch configuration and the office metadata have not changed since; see the integrity section below.) Evaluations that failed outright do not write a receipt and have no ledger of their own, so they are not reconstructed as gaps. The evaluation_failed reason is reserved for a future version. Two special gap shapes to know:
  • A supported office with zero evaluations in the period is marked no_evaluations and carries a single gap spanning the whole period. In the month the watch was created, the gap starts when the watch was created: nothing before a watch existed is a gap. That gap stays resolved: false permanently, because nothing that happens later can evaluate a month that has already passed. The same holds for a gap that runs to the end of a closed period on an office that was evaluated: the silence after its last evaluation is part of that month’s record, and a later evaluation does not retroactively fill it. Whether evaluation resumed afterwards is reported separately, on every supported office, as evaluation_resumed_after_period, a fact about now rather than about the period, and therefore excluded from content_hash.
  • Evaluations recorded before coverage snapshots existed cannot state what office-data horizon they covered. They are disclosed as incomplete coverage evidence (a gap with a null coverage_through), never presented as covered.

​
Unsupported offices

If a watch is scoped to an office Signa does not currently ingest, that office appears with status: "unsupported" and no evaluation claims at all. Signa will never render a clean, zero-alert attestation for an office it does not cover, because that would read as “we looked and found nothing” when the truth is “we do not cover this office yet”. If every office in the scope is unsupported, the endpoint returns 422 attestation_unsupported_scope rather than an empty artifact.

​
Configuration changes and the fingerprint

The query_fingerprint is a stable hash of the watch query and trigger events. Its fingerprint_basis is current_configuration: it describes the configuration as it exists when you fetch the artifact, because a full evaluated-time configuration history is not stored yet. Two flags keep this honest:
  • configuration_changed_in_period: true means the configuration changed during the period (the receipts carry more than one evaluation epoch); the epochs_in_period array lists them.
  • configuration_changed_since_period: true means the configuration changed after the period closed. The fingerprint in the artifact then describes the current configuration, not the one that was in force during the period.
Practical rule for firms: fetch and file the attestation promptly after the month closes, before making configuration changes. A filed artifact with both flags false pins the fingerprint to the period unambiguously.

​
Reconciliation

The artifact cross-checks the alert counts recorded on the evaluation receipts against the alert rows stored for the period, scoped to the same supported offices the artifact reports on. When they agree, reconciliation is consistent. When they disagree, it is mismatch, surfaced honestly rather than silently reconciled to one number. One caveat: alerts that cannot be attributed to an office (their ingestion-run reference is null, for example because the run record aged out) are included in the cross-check total. In rare cases this can produce a mismatch that reflects attribution loss rather than a missing or extra alert.

​
Verifying integrity with content_hash

The content_hash is a SHA-256 over the canonical, sorted-key form of the artifact, excluding the fields that describe the moment of generation rather than the period: generated_at, request_id, the hash itself, watch_status_at_generation, watch.name (display-only), watch.configuration_changed_since_period, and offices[].evaluation_resumed_after_period. The artifact is computed deterministically from stored evaluation records, and everything a closed period claims about evaluation is clipped to that period, so that part of the hash is fixed the moment the period ends. To verify a filed copy: re-fetch the JSON for the same period and compare the content_hash to the value on the copy you filed. A match proves the artifact was not altered after issue. One caveat to know when you compare: a few inputs are still read at generation time rather than snapshotted for the period. Those are the watch’s current configuration (the fingerprint and trigger events), the offices currently in scope, and office names and support status. If any of them changes after you file, a later re-fetch produces a different hash even though the period’s evaluation history is untouched. That is the disclosure working as intended, not tampering: the artifact also reports configuration_changed_since_period: true. Keep the filed copy as the record of what was issued. This proves the integrity of the artifact. It is not a third-party authenticity signature. Cryptographically signed and timestamped documents (for example RFC 3161 timestamps) are on the roadmap.

​
Filing the PDF

For a business record you can file, request the PDF:
You can also request it with Accept: application/pdf. The PDF is rendered from the same data as the JSON, so the numbers match. It includes the configuration, a per-office coverage table, the gaps, the totals, the statement, and the content_hash with instructions for verifying it against the JSON endpoint. A typical firm workflow: fetch the PDF once a month for the closed period, file it in the matter record, and store the JSON alongside it so an auditor can re-fetch and hash-verify later.

​
Periods and errors

  • Periods are closed UTC calendar months. The default is the previous month.
  • The current, in-progress month returns 422 attestation_period_open. Pass partial=true to get an interim artifact marked "partial": true.
  • A period beyond the 25-month retention window returns 410 attestation_expired. The window is rolling (day-granular, matching the evidence retention clock): once any part of a month is past the horizon, the whole month is treated as expired. File monthly, within the window.
  • A period that ended before the watch existed returns 422 period_before_watch: there was no monitoring to attest. Evaluations recorded in the period count as proof the watch existed then.
  • An unknown watch, or a watch belonging to another organization, returns 404.