Observation coverage

An observation coverage window is a declaration: "every operation on this account between these two dates has been supplied to you". It is a fact about an account and a period, not about a transaction. It has its own resource, POST /transactions/v1/coverage-windows, rather than a field on POST /transactions/v1/enrichments, because it exists precisely when there is no transaction to send: a month with no direct debit is the case where the declaration matters most.

Why an absence proves nothing

Transaction Intelligence can tell that an expected due date has not arrived. On its own, it cannot tell whether that is because nothing happened or because nobody sent it. Without that distinction, "the client stopped calling the API" and "the subscription stopped collecting" would be one and the same thing.

Coverage is never inferred from traffic: ten calls in October may be ten operations out of a hundred. It requires an explicit declaration per account and per period. Until one exists, lifecycle.state stays unknown, never late: "I saw nothing" does not become "nothing happened".

Declaring coverage

The body is a CoverageWindow, a closed schema: any unknown field is rejected (422).

The account is named through account_hint: iban when it has one, otherwise external_account_id, your own identifier for cards, wallets and rails without an IBAN. At least one of the two is required (account_identity_required). Neither is stored: Noryo keeps only an opaque fingerprint, scoped to your workspace, the same one computed on the enrichment. Use the same account_hint in both calls: a transaction sent without it has no source, and no coverage will ever meet it.

covered_from and covered_to are dates in the form 2026-07-01. A non-existent day is rejected (must_be_iso_date), and so is a reversed interval (after_covered_to). Noryo does not certify what has not happened yet: a covered_to beyond tomorrow, by the server's date in UTC, is rejected (interval_in_future).

The exact meaning of completeness

complete has a precise meaning: all operations on the account over the interval have been transmitted, including when there were none. It is the only value that allows an absence to be read as a miss.

Provenance is not an input

The response carries provenance: caller_asserted, always. It is not a field you choose: Noryo records what you assert, does not verify it, and you cannot declare anything else. Sending provenance in the body is rejected as unknown_field.

Response and interval merging

The response is a 200 in both cases, recorded on its own or merged with a neighbour. covered_from and covered_to are the bounds after merging. merged_intervals counts the pre-existing intervals the declaration absorbed:

Two intervals for the same account that touch or overlap become one: an hourly synchronisation does not manufacture intervals, and an exact replay returns 1 because the declaration absorbs its own copy. The call is idempotent by construction, with no Idempotency-Key header.

What coverage changes in a series

Coverage acts on the lifecycle axis of a recurring series (see Series lifecycle). For each closed due date, Noryo checks that every source of the series was covered complete over the whole expected window (expected_next_window, from from to to); a coverage that contains only part of the window does not allow a conclusion.

consecutive_misses only advances under complete coverage. ended is never produced by an accumulation of absences, with or without coverage: it requires explicit terminal evidence.

What coverage does not change: status (how much of a series this is) and history_coverage.sufficiency (whether the cadence can be trusted). Both readings depend on the occurrences observed, not on your declarations.

What Noryo does not verify

Noryo does not query your bank and does not compare your declarations with what you sent. A complete coverage declared over a period where operations were missing will produce late and inactive states that do not exist: the declaration is the caller's responsibility. The contract exposes no way to read back or withdraw a declaration: declare what you know, at the pace of your synchronisation.

Examples

A SEPA account, with July supplied in full:

curl -X POST https://api.noryo.app/transactions/v1/coverage-windows \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "covered_from": "2026-07-01",
    "covered_to": "2026-07-31",
    "completeness": "complete"
  }'

{
  "covered_from": "2026-07-01",
  "covered_to": "2026-07-31",
  "completeness": "complete",
  "provenance": "caller_asserted",
  "merged_intervals": 0,
  "policy_version": "cov_v1",
  "note": "",
  "request_id": "req_01J9…"
}

A prepaid card, named by your own identifier, partial synchronisation:

const response = await fetch("https://api.noryo.app/transactions/v1/coverage-windows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_hint: { external_account_id: "carte-4970" },
    covered_from: "2026-08-01",
    covered_to: "2026-08-31",
    completeness: "partial",
  }),
});

const coverage = await response.json();
console.log(response.status, coverage.merged_intervals, response.headers.get("noryo-request-id"));

Rejections specific to this route

A 422 returns a Problem of type invalid_input, where errors[].code names the rule: unknown_field (a field outside the schema, provenance included), required (account_hint missing or not an object), account_identity_required, malformed_iban, must_be_iso_date (date missing, malformed or a non-existent day), after_covered_to, interval_in_future, unknown_completeness. The full list, including must_be_object, must_be_non_empty_string, too_long and contains_control_character, is in the operation above and on /errors/invalid_input.

The other responses (400, 401, 403, 413, 415, 429, 500) are shared across the API. This route counts towards the rate limits; a 422 consumes a token, since the key was valid. Full catalogue: Errors.