> ## 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.

# Shared Types

> Reusable nested fields for addresses, money, provenance, and other shared structures.

## Address

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `line1` | `string` Optional | Street or delivery address line one. | `123 Example Street` |
| `line2` | `string` Optional | Suite, unit or second address line. | `Suite 100` |
| `city` | `string` Optional | Locality. | `Toronto` |
| `region` | `string` Optional | Subdivision or province code/name; preserve raw when unmapped. | `ON` |
| `postal_code` | `string` Optional | Postal code as a string with leading zeroes preserved. | `M5V 0A1` |
| `country` | `string` Optional | ISO 3166-1 alpha-2 country when established. | `CA` |
| `raw_address` | `string` Optional | Unparsed source address if structured fields are unavailable. | `123 Example Street, Toronto` |

## SourceRef

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `provider_id` | `string` Required | Inventory or supplemental provider identifier; AMLOK or CLIENT for internal evidence. | `BANK-02` |
| `connection_id` | `id` Optional | Authorized provider connection. | `cnn_example` |
| `source_record_id` | `string` Optional | Upstream record identifier scoped by provider, connection and record type. | `upstream_123` |
| `source_record_type` | `string` Optional | Provider object or report type. | `transaction` |
| `source_updated_at` | `datetime` Optional | Source update time; do not replace with retrieval time. | Not specified |
| `retrieved_at` | `datetime` Required | Time AMLOK retrieved this evidence. | Not specified |
| `document_id` | `id` Optional | Evidence document when applicable. | `doc_example` |
| `source_api_version` | `string` Optional | Version of provider API/schema used. | `2026-10` |

## FieldProvenance

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `field_path` | `string` Required | Relative path in the normalized resource. | `amount.amount` |
| `source_ref_index` | `integer` Required | Zero-based index into source\_refs. | `0` |
| `source_field_path` | `string` Optional | Actual field path or document locator. | `added[].amount` |
| `transformation_id` | `string` Optional | Versioned conversion/mapping rule. | `plaid_amount_abs_v1` |
| `evidence_level` | `enum:evidence_level` Required | Provenance class for the resulting value. | `source_record` |
| `confidence` | `decimal` Optional | Calibrated extraction or matching confidence, if available. | `null` |
| `source_timezone` | `string` Optional | Original timezone where needed to interpret local time. | `America/Toronto` |

## MissingField

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `field_path` | `string` Required | Unavailable relative field path. | `available.amount` |
| `reason` | `enum:null_reason` Required | Specific reason the field has no value. | `not_provided` |
| `detail` | `string` Optional | Sanitized explanation useful to the caller. | `Institution did not return available balance.` |

## Identifier

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `type` | `string` Required | Identifier scheme such as CA\_BN or US\_EIN. | `CA_BN` |
| `value_token` | `string` Optional | Vault token for restricted identifiers. | `tok_example` |
| `masked_value` | `string` Optional | Masked identifier for an authorized caller. | `*****1234` |
| `country` | `string` Required | Issuing country code. | `CA` |
| `jurisdiction` | `string` Optional | Registry or subdivision when necessary. | `CA-ON` |

## IndustryCode

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `taxonomy` | `string` Required | Classification system; NAICS, SIC, MCC, NACE or named local scheme. | `NAICS` |
| `version` | `string` Optional | Edition of the classification system. | `2022` |
| `code` | `string` Required | Identifier preserved as a string. | `332710` |
| `description` | `string` Optional | Label supplied by source or a versioned dictionary. | `Machine shops` |
| `is_primary` | `boolean` Optional | Source-designated primary industry. | `true` |

## Money

| Field | Type / presence | Definition | Example | |
| - | - | - | - | - |
| `amount` | `decimal` Required | Exact decimal string in major units; signed only where field definition specifies. | `1234.56` | |
| `currency` | \`string | null\` Required | Uppercase ISO 4217 currency when known; null blocks monetary aggregation and requires missing\_fields reason. | `CAD` |

## InvoiceLine

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `id` | `string` Optional | Line identifier within parent document. | `line_1` |
| `product_id` | `id` Optional | Normalized item if resolved. | `prd_example` |
| `description` | `string` Optional | Original line description. | `Consulting services` |
| `quantity` | `decimal` Optional | Line quantity in the supplied unit. | `10` |
| `unit_of_measure` | `string` Optional | Quantity unit. | `hour` |
| `unit_price` | `Money` Optional | Unit charge under document tax convention. | `{"amount":"100.00","currency":"CAD"}` |
| `tax_amount` | `Money` Optional | Line tax amount. | `{"amount":"130.00","currency":"CAD"}` |
| `line_total` | `Money` Optional | Source extended amount; retain whether tax is included. | `{"amount":"1130.00","currency":"CAD"}` |
| `ledger_account_id` | `id` Optional | Source ledger classification if exposed. | `gla_sales` |
| `tax_code` | `string` Optional | Jurisdiction-specific source tax code. | `HST_ON` |

## PurchaseLine

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `product_id` | `id` Optional | Ordered item. | `prd_example` |
| `description` | `string` Optional | Purchase line description. | `Components` |
| `quantity_ordered` | `decimal` Optional | Ordered quantity. | `100` |
| `quantity_received` | `decimal` Optional | Recorded received quantity. | `50` |
| `unit_of_measure` | `string` Optional | Quantity unit. | `each` |
| `unit_price` | `Money` Optional | Price per ordered unit. | `{"amount":"10.00","currency":"CAD"}` |
| `line_total` | `Money` Optional | Total ordered line amount. | `{"amount":"1000.00","currency":"CAD"}` |

## ShipmentLine

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `product_id` | `id` Optional | Item shipped or received. | `prd_example` |
| `quantity` | `decimal` Required | Quantity in this shipment. | `50` |
| `unit_of_measure` | `string` Required | Unit for the quantity. | `each` |
| `order_line_id` | `id` Optional | Sales line being fulfilled. | `oli_example` |

## Allocation

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `resource_type` | `enum:receivable_kind` Required | Type of accounting document receiving allocation. | `invoice` |
| `resource_id` | `id` Required | Normalized accounting document. | `inv_example` |
| `amount` | `Money` Required | Amount applied in the target document currency. | `{"amount":"100.00","currency":"CAD"}` |

## LienParty

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `role` | `string` Required | Recorded debtor, secured party, assignee or other role. | `debtor` |
| `name` | `string` Required | Party name exactly as recorded. | `Example Manufacturing Inc.` |
| `entity_id` | `id` Optional | Resolved AMLOK party only when established. | `biz_example` |
| `address` | `Address` Optional | Address in registry evidence. | `null` |
| `source_party_id` | `string` Optional | Source identifier if provided. | `null` |

## Error

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `code` | `string` Required | Stable machine-readable error code. | `source_unavailable` |
| `message` | `string` Required | Safe caller-facing explanation. | `The upstream source is temporarily unavailable.` |
| `field` | `string` Optional | Invalid request field when relevant. | `jurisdictions` |
| `retryable` | `boolean` Required | Whether retry may succeed without changing the request. | `true` |
| `request_id` | `string` Required | Correlation identifier for support. | `req_example` |

## Page

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `next_cursor` | `string` Optional | Opaque cursor for subsequent page; null after final page. | `cur_example` |
| `has_more` | `boolean` Required | Whether more authorized records remain. | `true` |
| `limit` | `integer` Required | Applied result limit, from 1 to 200. | `100` |

## ResponseMeta

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `request_id` | `string` Required | AMLOK request correlation ID. | `req_example` |
| `schema_version` | `string` Required | Serialization contract version. | `1.4.2` |
| `generated_at` | `datetime` Required | Response generation time, not source data freshness. | Not specified |
| `data_status` | `enum:data_status` Required | Completeness of this response within its declared scope. | `partial` |
| `coverage` | `Coverage` Optional | Requested and achieved source/time coverage. | `null` |

## Coverage

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `requested_from` | `date` Optional | Inclusive start requested. | `2026-09-01` |
| `requested_to` | `date` Optional | Exclusive end requested. | `2026-10-01` |
| `available_from` | `date` Optional | Earliest actual coverage. | `2026-09-05` |
| `available_to` | `date` Optional | Exclusive end of actual coverage. | `2026-10-01` |
| `source_ids[]` | `array<string>` Required | Sources actually contributing. | `["BANK-02"]` |
| `missing_intervals[]` | `array<Interval>` Required | Known gaps within requested scope. | `[]` |
| `jurisdictions_completed[]` | `array<string>` Optional | Completed geographic search scope when applicable. | `["US-DE"]` |

## Interval

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `from` | `date` Required | Inclusive interval start. | `2026-09-01` |
| `to` | `date` Required | Exclusive interval end. | `2026-09-05` |

## WebhookEvent

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `id` | `id` Required | Globally unique event ID within tenant for deduplication. | `evt_example` |
| `type` | `string` Required | Event key in the Events tab. | `verification.completed` |
| `created_at` | `datetime` Required | Event creation time. | Not specified |
| `schema_version` | `string` Required | Webhook contract version. | `1.4.2` |
| `resource_type` | `string` Required | Type of changed object. | `verification` |
| `resource_id` | `id` Required | Object to retrieve for full authorized detail. | `ver_example` |
| `resource_version` | `integer` Required | Version that triggered the event. | `2` |
| `data` | `JSON` Required | Minimal event details; sensitive evidence retrieved separately. | `{"status":"approved"}` |

## Action

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `type` | `string` Required | Next applicant interaction such as authorize\_connection. | `authorize_connection` |
| `url` | `string` Required | Short-lived authorized HTTPS interaction URL. | `https://connect.example.com/session` |
| `expires_at` | `datetime` Required | Expiry of interaction URL. | Not specified |

## DownloadLink

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `document_id` | `id` Required | Evidence document requested. | `doc_example` |
| `url` | `string` Required | Short-lived signed download URL returned only to an authorized caller. | `https://evidence.example.com/temporary` |
| `expires_at` | `datetime` Required | Expiry of download capability. | Not specified |

## CalculationJob

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `id` | `id` Required | Calculation job identifier. | `calc_example` |
| `status` | `enum:sync_status` Required | Calculation execution state. | `queued` |
| `subject_id` | `id` Required | Subject assessed. | `biz_example` |
| `attribute_ids[]` | `array<id>` Required | Resulting values, including unavailable outputs. | `[]` |
| `errors[]` | `array<Error>` Required | Calculation failures. | `[]` |

## WebhookEndpoint

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `id` | `id` Required | Tenant event destination identifier. | `whk_example` |
| `url` | `string` Required | Validated HTTPS delivery destination. | `https://client.example.com/amlok-events` |
| `event_types[]` | `array<string>` Required | Subscribed event keys. | `["verification.completed"]` |
| `status` | `string` Required | active or disabled. | `active` |
| `secret` | `string` Conditional | Signing secret returned once at creation only; omitted thereafter. | `<generated-once>` |

## WebhookReplay

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `event_id` | `id` Required | Original event being redelivered. | `evt_example` |
| `endpoint_id` | `id` Required | Authorized destination. | `whk_example` |
| `status` | `string` Required | queued, delivered or failed. | `queued` |

## ProviderCapability

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `provider_id` | `string` Required | Configured integration ID. | `BANK-02` |
| `resources[]` | `array<string>` Required | Resources actually enabled for this tenant. | `["bank_account","bank_transaction"]` |
| `countries[]` | `array<string>` Required | Validated country availability for this entitlement. | `["CA"]` |
| `status` | `string` Required | enabled, unavailable or pending\_setup. | `enabled` |
| `limitations[]` | `array<string>` Required | Account/product-specific constraints. | `[]` |

## ChangePage

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `data[]` | `array<Change>` Required | Ordered authorized normalized changes. | `[]` |
| `page` | `Page` Required | Tenant-scoped continuation information. | `{"next_cursor":null,"has_more":false,"limit":100}` |
| `meta` | `ResponseMeta` Required | Response context and completeness. | `null` |

\| `resume_cursor` | `string`\
Required | Durable change-feed position, including after an empty response. | `changes_after_sequence_42` |
\| `cursor_expires_at` | `datetime`\
Required | Explicit expiry; create a new checkpoint and bootstrap after expiry. | `2026-11-01T14:00:00Z` |

## Change

| Field | Type / presence | Definition | Example |
| - | - | - | - |
| `resource_type` | `string` Required | Changed resource type. | `bank_transaction` |
| `resource_id` | `id` Required | Changed resource ID. | `btx_example` |
| `resource_version` | `integer` Required | Version changed. | `2` |
| `action` | `enum:event_action` Required | created, updated or deleted. | `updated` |
| `changed_at` | `datetime` Required | AMLOK change timestamp. | Not specified |

\| `sequence` | `integer`\
Required | Monotonic workspace change sequence; filtered streams may contain gaps. | `42` |

## Processing and reporting helpers

Calculation jobs also return `processing_context` and nullable `stop_reason`. Product context, monitoring periods, workload reports, frozen manifests and billing records use dedicated schemas in the [OpenAPI download](https://docs.amlok.io/openapi/amlok-v1.json). See [product scope](https://docs.amlok.io/api-reference/products-and-endpoints.md), [workload reporting](https://docs.amlok.io/api-reference/workload-reporting.md), and [export formats](https://docs.amlok.io/api-reference/export-formats.md).


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