> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amlok.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses and data conventions

> Interpret envelopes, exact amounts, missing values, coverage, and record versions.

## Envelopes

Financial-data and reporting operations use a consistent envelope. Single responses contain `data` and `meta`. Collection responses also contain `page`. Errors contain `error` and `meta`. The public healthcheck and service-status endpoints use their lightweight status schemas without a `data` / `meta` wrapper; see their individual response definitions.

```json theme={null}
{
  "data": [],
  "page": {"next_cursor": null, "has_more": false, "limit": 100},
  "meta": {
    "request_id": "req_example",
    "schema_version": "1.4.2",
    "generated_at": "2026-10-23T14:00:00Z",
    "data_status": "complete"
  }
}
```

This example is a completed, known-empty collection. An unqueried source or a failed connection must not be represented as an empty successful result.

Canonical normalized financial-data records inherit `id`, `object`, `created_at`, `updated_at`, `record_version`, `source_refs`, `data_status`, `missing_fields`, and `schema_version`. Subject context, provenance, and other optional fields appear when relevant and authorized. Reporting, manifests, monitoring periods, checkpoints, workload reports, calculation jobs and signed links use their own documented schemas inside `data`.

## Missing, empty, and redacted values

| Value | Interpretation |
| - | - |
| `null` | A value is unavailable or unknown. Consult `missing_fields`. |
| `0` or `"0.00"` | A known numeric zero with evidence. |
| `false` | A known false condition. |
| `[]` | A collection was queried and is known to be empty. |
| Omitted field | Optional, not selected, or not authorized; inspect the contract and entitlements. |

Denied sensitive values are omitted. Missing-field explanations must not leak the hidden value. `data_status: partial` means you must inspect the available coverage before using the result.

## Money and time

```json theme={null}
{"amount": {"amount": "1250.00", "currency": "CAD"}, "direction": "inflow"}
```

Monetary amounts and decimal ratios use strings. Preserve exact precision and currency. Bank-transaction amounts are absolute magnitudes with a separate direction; other resources can define signed values. Do not apply one sign rule to every domain or sum currencies without explicit FX inputs.

Dates preserve source calendar dates. Timestamps use RFC 3339 UTC. `generated_at` is response generation time, `retrieved_at` is collection time, and `as_of` / `observed_at` describe evidence timing when known. A retrieval timestamp is not proof that a balance is real time.

## Coverage and provenance

`source_refs` identifies the evidence origin. Optional field provenance records the source path and transformation. Coverage records the actual sources, time interval, and completed jurisdictions.

An observed zero lien count for one completed jurisdiction says nothing about an unqueried or failed jurisdiction. An unavailable DSCR is not zero and is not an approval. See [worked payloads](https://docs.amlok.io/api-reference/examples.md).

## Versions and projections

`record_version` tracks a particular resource. `schema_version` identifies the serialization contract. Use the quoted ETag with `If-Match` for supported mutable configuration.

The `fields` parameter selects comma-separated **top-level field names** while preserving required identity and metadata. For example, `fields=id,amount` returns the mandatory metadata and the complete `amount` object when authorized. Nested paths, wildcards, and unknown field names return `400 validation_error`.

GET endpoints for canonical financial-data records use a dedicated `*Read` schema whose domain fields can be omitted by projection. Present fields retain their canonical types, nullability, and nested requirements. Full canonical schemas remain available for complete objects and mutation responses. Omitting `fields` returns the full authorized representation. This uses standard OpenAPI 3.1 Schema Objects, so generated clients must treat unselected properties as absent rather than null.

`include` permits `provenance` and `missing_fields`; it does not grant access or allow arbitrary relationship expansion. The [data dictionary](https://docs.amlok.io/data-model/field-dictionary.md) describes full objects. See the [OpenAPI Schema Object specification](https://spec.openapis.org/oas/v3.1.1.html#schema-object) for the schema vocabulary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.