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

# Concepts

> Cases, references, environments, documents, policies and checks, and which ones the API reaches.

| Concept | What it is | Via the Partner API v0.2.0 |
| - | - | - |
| Case | One client file. Created when a call carries a `reference`. | Created by `extract`, `verify`, `assess`, `eid` |
| Document | A file you upload, read into fields with checks. Gets a `document_id` once filed. | `extract` |
| Verdict | `passed`, the checks, the flags and the completeness of a profile. | `verify`, `assess` |
| Assessment | Risk tolerance, capacity, compliance risk and suitability. | `assess` |
| eID check | A remote identity check of a Canadian client. | `eid` |
| Policy | The workspace's rules and thresholds for each call. | Applied to every call; edited in the console |
| Connection | A bank account linked with the customer's consent. | Console only |
| Score | Out of 1000, with a risk level and eligible amount. | Console only |

## Reference

`reference` is your own stable id for the client, 1 to 64 characters of `A-Z a-z 0-9 _ . : -`. With one, the call files a case where your staff look. Without one, nothing is stored on your workspace and no webhook is sent.

Pick a reference that does not change and is not a personal value. A database id (`client-0001`, `acct:8812`) works. An email address does not (the `@` is not allowed, and it would put personal data in your logs and in webhooks).

## Case

A case is unique per workspace, environment and reference. The first call with a reference creates it. Later calls update it:

* `/extract` adds a document, its read fields and its checks.
* `/verify` and `/assess` file the verdict, and the assessment for `/assess`. Documents whose `document_id` you send back are linked to the case.
* `/eid` files the eID request as pending, and a poll records the outcome.

A name sent in `subject` replaces the stored name. A call without a name keeps the stored one. If no `subject` is sent, the name is built from the read fields.

A status that a person set in the console (`approved`, `refused`) is never changed by a new verdict.

## Environment

`environment` is `sandbox` (default) or `production`. The same reference in the two environments is two cases. See [Sandbox and production](/sandbox) for what else the field changes.

## Document and fields

A document is read into fields from a fixed vocabulary of keys (names, dates, address, bank details, entity numbers and more). Every value is a string. The reader omits what it cannot read. See [Document types and fields](/guides/document-types).

## Verdict and severity

Every check has a severity. `critical` blocks, `warning` flags for a person, `info` is for the record. `passed` is true when no critical check failed. See [Verify a profile](/guides/verification).

## Policy

Every call runs under your workspace policy for the client kind (`kyc` or `kyb`) and the environment. A request switch can add checks, but cannot turn off one the policy locks. A refused switch is listed in `policy.overrides_refused` and is not an error. The policy decides thresholds (days), locks, required documents and the strictness of the risk bands. It is edited in **Settings, KYC policy** in the console.

## Kinds of client

| `kind` | Document that establishes the client | Required data points |
| - | - | - |
| `individual` | A government photo ID | 26, plus either-or groups |
| `corporation`, `charitable_org` | Articles or a business registration | 21 |
| `partnership` | Partnership agreement or business registration | 21 |
| `trust` | Trust deed | 17 |
| `estate` | Grant of probate or letters of administration | 21 |

## What the API does not do

* It does not decide. It returns checks and a verdict. Your policy decides what to do.
* It does not return a per-field confidence.
* It has no bank connection endpoint and no 1000-point score. Those are console products.
* It has no batch endpoint and no idempotency key.


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