# Core Concepts The Rekord API is built around nine core resources that work together to ingest evidence, resolve data, evaluate policies, and orchestrate decisions. This page explains each resource and how they connect. ## Workspaces Everything in the Rekord API is scoped to a workspace. A workspace is an isolated environment containing your organisation's configurations and data. Every API token operates within a single workspace, and data never crosses workspace boundaries. ## Models A model defines the shape of a type of data: its fields, their types, validation rules, resolution policies, and relationships to other models. Think of a model as a schema. An "Applicant" model might have fields for name, date of birth, and annual income. A "Property" model might have fields for address, purchase price, and estimated value. Once a model is configured, you can start ingesting data. That data arrives as contributions. ## Contributions A contribution is a piece of evidence. Every data point that enters the system, whether from a document extraction, a third-party integration, a manual entry, or an API write, is persisted as a contribution with the raw payload, per-field confidence scores, and source metadata. If a source sends corrected data, it arrives as a new contribution that supersedes the previous one. The original is preserved for audit. Contributions on their own are raw inputs. The platform is then responsible for assembling them into records. ## Records A record is the resolved view of a single entity, such as an individual applicant, or a specific property. It holds the authoritative value for every field, assembled from all the contributions the system has received for that entity. Records are read-only via the API. To change a value, submit a new contribution via `POST /contributions`. The platform records it as evidence with full lineage and re-runs resolution. The new contribution sits alongside every other contribution in the audit trail, so you can always trace how the resolved value was reached. How the platform decides which contribution wins for a given field is governed by resolution policies. ## Resolution When a contribution arrives, the platform binds it to a record and re-resolves every field on that record. If only one contribution has provided a value for a field, that value is used directly. When multiple contributions disagree, the model's resolution policy decides which value wins. | Policy | Behaviour | | -------------------- | ------------------------------------------------------------------------------------------- | | `highest_confidence` | The contribution with the highest per-field confidence score wins. Default for most fields. | | `latest_wins` | The most recently ingested contribution takes precedence, regardless of confidence. | | `all_must_match` | All contributions must agree. If they conflict, the field is flagged for manual review. | | `manual` | The field is never auto-resolved. Someone on your team must choose the correct value. | Resolution policies are configured per field on the model, giving you fine-grained control over how different types of data are handled. ### Freshness When a new contribution arrives, the platform re-resolves the affected record by re-evaluating every field against the full set of contributions and the model's resolution policies. This process is called the resolution cycle. Every record and context carries a `freshness` indicator that tracks where it sits in this cycle: | Value | Meaning | | ----------- | -------------------------------------------------------- | | `resolved` | All evidence has been processed. The data is current. | | `stale` | New evidence has arrived but has not been processed yet. | | `computing` | The platform is currently re-resolving the record. | If `freshness` is `stale` or `computing`, the record's field values may not yet reflect the latest evidence. Check this value before making decisions based on record data. Records rarely exist in isolation. They connect to each other through relationships. ## Relationships Relationships connect records across models, forming a traversable graph. An "Applicant" record might be linked to multiple "Employment" records and a "Property" record. These connections power cross-record operations: a computed field that sums salary across all linked employment records, or an aggregation that computes a loan-to-value ratio from the applicant's requested amount and the property's estimated value. Relationships are established by the platform during resolution. You can read relationship links through the API, but you do not create or remove them directly. All of these resources, records, contributions, relationships, and files, are grouped within a decisioning context. ## Decisioning Contexts A decisioning context groups everything related to a single decision: a mortgage application, a loan assessment, or an onboarding journey. It contains exactly the records, contributions, relationships, and policy evaluations relevant to that decision. Data in one context cannot leak into another. Contexts carry two independent status dimensions: | Dimension | Values | Controlled by | | ----------- | -------------------------------- | --------------- | | `status` | `active`, `locked`, `archived` | You, explicitly | | `freshness` | `resolved`, `stale`, `computing` | The platform | This separation means a case can be marked `locked` while late-arriving evidence is still being processed. The business decision is recorded, and the data continues to converge independently. Once a context has records and contributions, you can evaluate policies against them. ## Policies Policies are workspace-scoped expressions written in JSON Logic that evaluate against the full decisioning context. They answer questions like "does this applicant pass the affordability check?" or "is the loan-to-value ratio within policy?" Policies are scoped to a workspace and versioned independently from the records they evaluate. When a policy runs, the platform captures the expression, the resolved input values, and the boolean outcome as a full audit trace, so every pass or fail can be reconstructed end-to-end from the source contributions. ## Flows A flow is a reusable workflow definition composed of steps: automated tasks, review tasks, wait-for-signal steps, and branching logic. Flows orchestrate the sequence of operations needed to reach a decision within a context. Flows have versions, and only one version can be active at a time. Running a flow creates an instance that tracks execution state, advancing through steps and creating tasks as needed. Instances can be `pending` (waiting for a signal), `completed`, `cancelled`, or `failed`. {% hint style="info" %} Flows can be triggered manually via the API or declaratively, for example when a policy evaluation fails. {% endhint %} When a flow needs input from your team, it creates a task. ## Tasks Tasks are work items for your team. They are created by the platform, typically by a flow step or a system event, and actioned by users. A task represents a discrete unit of work: reviewing a document, approving an exception, uploading evidence, or making a judgement call. Tasks have a lifecycle: `open` (available in a queue), then `in_progress` (claimed or assigned), then `completed` or `cancelled`. Each task carries a priority (`low`, `medium`, `high`, `critical`) and an input schema describing what the assignee needs to provide. ## Files Files are binary objects: documents, images, extracts, and other attachments. They belong to a decisioning context and are linked to records via `file`-type fields. ## How they fit together ```plaintext Workspace └── Model (schema) └── defines shape of → Record (resolved data) ├── assembled from → Contributions (evidence) ├── connected via → Relationships (graph edges) └── attached → Data & Files (binary objects) └── Decisioning Context (decision boundary) ├── contains → Records, Contributions, Relationships, Files ├── evaluates → Policies → Policy Evaluations (outcomes) └── runs → Flow Instances └── creates → Tasks (work items for your team) ``` ### A mortgage application, end to end A lender configures an "Applicant" **model** and a "Property" **model** with fields, validation rules, and resolution policies. When a new application arrives, the platform creates a **decisioning context** to scope the decision. Evidence flows in as **contributions**: the applicant's identity details from an ID verification provider, employment and income data from payroll integrations, and a property valuation from a surveyor. Supporting documents are uploaded as **files**. The platform resolves these contributions into **records**, establishes **relationships** between the applicant, their employment history, and the property, then evaluates **policies** such as affordability checks and loan-to-value limits. If a policy fails, a **flow** kicks off a review workflow. The flow creates a **task** for an underwriter to review the exception and make a judgement call. Once the task is completed, the flow advances and the context reaches its final state. At any point, the lender can read the resolved records, policy evaluation outcomes, and task results through the API to inform the decision. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.rekordsoftware.com/rekord-api/core-concepts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.