@dossier-wiki/os-sdk 1.4.0 → 1.4.2-staging.5.1

package/docs/REFERENCE.md

@@ -44,8 +44,20 @@ the recorded event-time bounds.
 `status`, `preferredName`, `aliases`, `dateOfBirth`, `nationality[]`,
 `countryOfResidence[]`, `taxId`, `emails[]`, `phones[]`,
 `identificationDocuments[]`, `faceImageFileIds[]`, `addresses[]`, `tags[]`,
-`assignedToUserIds[]`, and `assignedToTeamIds[]`. Contact entries are
-`{ value, primary }`.
+`assignedToUserIds[]`, `assignedToTeamIds[]`, `profileTemplateKey`, `fields[]`,
+and `deferInitialScreening`. Contact entries are `{ value, primary }`.
+`deferInitialScreening: true` skips the initial screening that creation
+normally enqueues; use it when another path screens the customer, such as a
+stakeholder screened with its entity.
+
+`profileTemplateKey` names the customer's Profile Template (omit it to get the
+default `INDIVIDUAL` template, if one is set). `fields` are the template's
+typed profile fields (`TypedFieldValueInput[]`), validated Tier A against
+`ProfileTemplate.fieldConfig`; sending `fields` with no template is a 400. On
+`update`, `fields` merge (listed keys change, `value: null` clears, unlisted
+keys stay) and `profileTemplateKey` switches template. Responses carry
+`profileTemplateKey`, `fields` (`TypedFieldValue[]`) and `riskRatingSource`
+(`'MANUAL' | 'MATRIX' | null`).
 
 Legacy field names from the pre-1.0 contract are still accepted on create and
 map onto the canonical ones — `email` / `phone` scalars fold into `emails[]` /
@@ -81,8 +93,9 @@ whenever both are supplied. Prefer the canonical names in new integrations.
 `create(input)` requires `externalId` and `legalName`. Optional create fields
 are `status`, `tradingNames[]`, `registrationNumber`, `taxId`,
 `countryOfIncorporation`, `dateOfIncorporation`, `entityType`, `websites[]`,
-`stakeholders[]`, `locations[]`, `tags[]`, `assignedToUserIds[]`, and
-`assignedToTeamIds[]`. Each stakeholder has required `name` and uppercase
+`stakeholders[]`, `locations[]`, `tags[]`, `assignedToUserIds[]`,
+`assignedToTeamIds[]`, `profileTemplateKey`, and `fields[]` (same profile
+semantics as individuals, against an `ENTITY` template). Each stakeholder has required `name` and uppercase
 `role` (`SHAREHOLDER`, `UBO`, or `DIRECTOR`). Entity locations use the same
 `AddressInputDto` shape as individual addresses.
 
@@ -144,9 +157,45 @@ for (const m of matches.filter((m) => m.disposition === 'FALSE_POSITIVE')) {
 
 The assessment only ever eliminates on a contradiction — never on a missing attribute, never on geography alone, and never on a sanctions listing unless the contradiction is hard. A `retain` is not a confirmation, only the absence of grounds to eliminate, and an absent `disambiguation` means the match was never assessed. `resolvedBy` distinguishes the automation from your users.
 
-`customers.riskRating` — `update(customerId, input)` → `PUT .../risk-rating`
+`customers.kyc`
 
-`customers.riskAssessments` — `list`, `create` on `.../risk-assessments`
+| Method | Endpoint |
+| --- | --- |
+| `start(customerId, { providerConfigId?, workflowId? })` | `POST .../kyc/sessions` — returns the hosted `sessionUrl` to hand to the customer |
+| `list(customerId)` | `GET .../kyc/sessions` |
+| `refresh(customerId, sessionId)` | `POST .../kyc/sessions/{sessionId}/refresh` |
+| `review(customerId, sessionId, { decision, reason?, notifyCustomer?, customerMessage? })` | `POST .../kyc/sessions/{sessionId}/review` — needs `customer:update` |
+| `report(customerId, sessionId)` | `GET .../kyc/sessions/{sessionId}/report` — PDF bytes (`Uint8Array`); needs `report:read` |
+| `evidenceBundle(customerId, sessionId)` | `GET .../kyc/sessions/{sessionId}/evidence` — ZIP bytes (`Uint8Array`); needs `report:read` |
+| `delete(customerId, sessionId)` | `DELETE .../kyc/sessions/{sessionId}` — unfinished sessions only |
+
+The OS keeps every session after it ends, so `report` and `evidenceBundle` work after the provider has deleted its copy. The bundle holds `report.pdf`, every archived evidence file at full resolution under `evidence/` (document pages, faces, liveness video, signature) and the raw data under `data/`.
+
+`customers.riskRating`
+
+| Method | Endpoint |
+| --- | --- |
+| `update(customerId, { riskRating, justification? })` | `PUT .../risk-rating` — sets a sticky officer override (`riskRatingSource: 'MANUAL'`); returns `UpdateRiskRatingResponseDto` |
+| `clearOverride(customerId)` | `DELETE .../risk-rating/override` — hands the rating back to the risk matrix; returns the latest matrix assessment |
+
+`customers.riskAssessments`
+
+| Method | Endpoint |
+| --- | --- |
+| `list(customerId)` | `GET .../risk-assessments` — questionnaires and matrix runs, newest first |
+| `create(customerId, input)` | `POST .../risk-assessments` — submit a questionnaire |
+| `evaluate(customerId)` | `POST .../risk-assessments/evaluate` — run the Profile Template risk matrix now; returns the latest matrix assessment |
+
+`CustomerRiskAssessmentResponseDto.method` is `QUESTIONNAIRE` or `MATRIX`.
+Matrix runs add `compositeScore`, `breakdown` (`RiskMatrixBreakdown`: per
+factor `input → criterion → level → score → weighted`, the composite, the
+preliminary rating, escalations that fired, incomplete factors, final rating
+and outcome), `profileTemplateVersion`, `trigger` (`PROFILE_UPDATED`,
+`KYC_SYNC`, `SCHEDULED`, `TEMPLATE_CHANGED`, `MANUAL`), `requiredDueDiligence`
+(`SDD | CDD | EDD`) and `nextReviewAt`. The matrix records its computed
+rating on every run but never overwrites a `MANUAL` rating. `evaluate` and
+`clearOverride` return 400 when the customer has no Profile Template with a
+risk matrix.
 
 `customers.expectedActivity` — `get`, `update` on `.../expected-activity`
 
@@ -188,6 +237,8 @@ observation contracts.
 
 Standing assignment can also be stamped at create via `assignedToUserIds` / `assignedToTeamIds` on `individuals.create` / `entities.create`.
 
+`customers.assignProfileTemplate({ customerIds, profileTemplateKey })` — `POST /v1/customers/profile-template-assignment` puts up to 500 existing customers on a live profile template. Values the template can hold are kept and defaults applied; required fields left empty come back per customer in `assigned[].missingFields` instead of refusing it (the next `fields` update must fill them). Customers already on the template are `unchanged`; other party types, archived customers and unknown ids are `skipped` with a `reason`. Requires `customer:update`.
+
 `individuals.create(input, { screening: 'sync' })` / `entities.create(input, { screening: 'sync' })` run the INITIAL screening inline and return it under `screening` (`InitialScreeningResultDto`: run status, `alertId`, and the `matches` array in the `listResults` shape). Without the option the call queues the screening as before and the response has no `screening` field.
 
 `targets` must contain at least one non-empty `userIds` or `teamIds` array.
@@ -199,7 +250,10 @@ writes require `customer:update`; archived customers return 422.
 ### `identificationDocuments` (document-scoped)
 
 Top-level resource for operating on a single identification document by its id
-— the review workflow's surface. Customer-scoped create/update/delete also
+— the review workflow's surface. Stage definitions may carry an optional
+`returnAssignment` (`RULE` | `RESTORE` | `ASK`) saying what happens to
+assignees when an alert is returned to that stage; omission means `RULE`, and
+Resolved stages never carry it. Customer-scoped create/update/delete also
 exist on `individuals.identificationDocuments` / `entities.identificationDocuments`.
 
 | Method | Endpoint |
@@ -532,6 +586,55 @@ schema. Editing `fields` never re-validates existing alerts — new required
 fields apply to alerts raised afterwards. Archive is refused (409) while any
 alert of the type is OPEN.
 
+`config.profileTemplates` — the template a customer is created against
+(Customer → Profile Template parallels Account → Product).
+
+| Method | Endpoint |
+| --- | --- |
+| `list({ partyType?, includeArchived? })` | `GET /v1/config/profile-templates` |
+| `get(id)` | `GET /v1/config/profile-templates/{id}` |
+| `getByKey(key)` | `GET /v1/config/profile-templates/by-key/{key}` (404 when absent) |
+| `versions(id)` | `GET /v1/config/profile-templates/{id}/versions` (newest first, each with `changes`) |
+| `version(id, version)` | `GET /v1/config/profile-templates/{id}/versions/{version}` |
+| `restoreVersion(id, version)` | `POST /v1/config/profile-templates/{id}/versions/{version}/restore` (republish as the newest version) |
+| `create(input)` | `POST /v1/config/profile-templates` (409 when `key` is taken) |
+| `update(id, input)` | `PATCH /v1/config/profile-templates/{id}` |
+| `archive(id)` | `DELETE /v1/config/profile-templates/{id}` (archive; no hard delete) |
+| `previewRiskMatrix(input)` | `POST /v1/config/profile-templates/preview-risk-matrix` (dry run for one customer; nothing saved) |
+| `riskMatrixImpact(id, input)` | `POST /v1/config/profile-templates/{id}/risk-matrix-impact` (dry run for every live customer on the template; at most 5,000) |
+
+A factor may read a platform-derived `input` (`customer.nationality`,
+`customer.productKeys`, `customer.expectedMonthlyVolume`) instead of a profile
+`field`. Individual and entity responses carry `nextReviewAt`, the customer's
+next periodic review; the daily sweep opens a `periodic-review` Task when it
+falls due.
+
+A template carries an immutable org-unique `key`, `partyType` (`INDIVIDUAL` \|
+`ENTITY`), `isDefault` (at most one live default per party type),
+`fieldConfig` (`TypedFieldDefinition[]`), an optional `riskMatrix`
+(`RiskMatrix`: `scale`, `bands`, `factors`, `escalations`, `outcomes`; each
+`RiskFactor` is `field` + `levels` for select or yes/no fields — BOOLEAN
+options `"true"` / `"false"`, a multi-select scores its highest-scoring
+selected option — `field` + `ranges` (`RiskRange`: min inclusive, max
+exclusive, open ends, no overlaps; money in major units) for NUMBER / MONETARY
+fields, or `criteria`; any option, range or criterion may set its own `score`
+to override its level's scale score) and
+`kycWorkflows` (`KycWorkflowBinding[]`, one per purpose; only `ONBOARDING` is
+used today), plus the creation setup of the simple create form for its party
+type: `individualCreation` (`SimpleCustomerCreationPreferences`, `INDIVIDUAL`
+templates) or `entityCreation` (`SimpleEntityCreationPreferences`, `ENTITY`
+templates) — the other is always `null`. Writes take
+`UpdateSimpleCustomerCreationPreferencesInput` /
+`UpdateSimpleEntityCreationPreferencesInput` (full replacement); sending the
+other party type's field is a 400. `create` without one copies the org's
+current Simple Customer Creation preference; `update` with `null` clears it
+(the org-wide preference applies again). The whole definition is validated on
+save and every problem is returned in one 400. Changing `fieldConfig`,
+`riskMatrix`, `kycWorkflows` or the creation setup publishes a new immutable
+version (`versions` snapshots carry fields, matrix and workflows only); only
+`fieldConfig` / `riskMatrix` changes re-assess the template's customers.
+Archiving keeps existing customers on the template and clears `isDefault`.
+
 `config.currencies`
 
 | Method | Endpoint |
@@ -591,7 +694,7 @@ Entry fields: `name` (required), `entryType` (`INDIVIDUAL` \| `ENTITY`, default
 
 ### `reports`
 
-On-demand PDF reports. Every method resolves to the raw PDF bytes as a `Uint8Array`; write them to disk (`fs.writeFileSync`) or stream them to your own download response. Gated on `report:read`. Each call records a `report.generated` activity on the subject record.
+On-demand PDF reports. Every method resolves to the raw PDF bytes as a `Uint8Array`; write them to disk (`fs.writeFileSync`) or stream them to your own download response. The API key needs the `reports:read` permission (part of the Full Access preset; a key without it gets `403`). Each call records a `report.generated` activity on the subject record, attributed to the key.
 
 | Method | Endpoint |
 | --- | --- |
@@ -654,6 +757,14 @@ type TypedFieldStored =
     | { key: string; type: 'monetary'; amountMinor: number; currency: string; precision: number };
 
 interface UntypedKeyValueDto { key: string; value: unknown }
+
+// Read shape on customer profile fields — the canonical uppercase tag.
+type TypedFieldValue =
+    | { key: string; type: 'TEXT' | 'DATE' | 'CURRENCY' | 'SINGLE_SELECT'; value: string }
+    | { key: string; type: 'NUMBER'; value: number }
+    | { key: string; type: 'BOOLEAN'; value: boolean }
+    | { key: string; type: 'LIST' | 'MULTI_SELECT' | 'SET'; value: string[] }
+    | { key: string; type: 'MONETARY'; amountMinor: number; currency: string; precision: number };
 ```
 
 DTOs that carry these:
@@ -665,6 +776,9 @@ DTOs that carry these:
 | `CreateEventDefinitionDto` / `UpdateEventDefinitionDto` | `properties` (`TypedFieldDefinition[]`) | schema |
 | `CreateCustomAlertTypeDto` / `UpdateCustomAlertTypeDto` | `fields` (`TypedFieldDefinition[]`) | schema |
 | `CreateCustomAlertDto` / `AlertResponseDto` | `fields` | A |
+| `CreateProfileTemplateInput` / `UpdateProfileTemplateInput` / `ProfileTemplate` | `fieldConfig` (`TypedFieldDefinition[]`) | schema |
+| `CreateIndividualInput` / `UpdateIndividualDto` / `CreateEntityInput` / `UpdateEntityDto` | `fields` (`TypedFieldValueInput[]`) | A |
+| `IndividualResponseDto` / `EntityResponseDto` | `fields` (`TypedFieldValue[]`) | A |
 | `CounterpartyResponseDto` | `otherProperties` | C |
 | Event ingestion (`POST /v1/events`) | `fields` | B |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dossier-wiki/os-sdk",
-  "version": "1.4.0",
+  "version": "1.4.2-staging.5.1",
   "description": "TypeScript SDK for the Dossiers OS API — customers, accounts, transactions, rules, screening, and configuration.",
   "license": "MIT",
   "type": "module",