{"openapi":"3.0.0","paths":{"/api/v1/risk/policy-schema":{"get":{"operationId":"RiskController_policySchema_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskPolicySchemaDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Discover policy format version 1 and its JSON Schema","tags":["Risk"]}},"/api/v1/risk/policies/validate":{"post":{"operationId":"RiskController_validatePolicy_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRiskPolicyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskPolicyValidationDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Validate a policy without saving; no idempotency key required","tags":["Risk"]}},"/api/v1/risk/policies/simulate":{"post":{"operationId":"RiskController_simulatePolicy_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateRiskPolicyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskPolicySimulationDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Evaluate synthetic scenarios only; saves no records and emits no actions or webhooks. No idempotency key required.","tags":["Risk"]}},"/api/v1/risk/verification-inputs":{"get":{"operationId":"RiskController_verificationInputs_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"offset","required":false,"in":"query","description":"Workflow offset returned by the preceding catalog page.","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskVerificationInputListDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List extractable Korala verification fields in this workspace and mode","tags":["Risk"]}},"/api/v1/risk/investigation-ai-settings":{"get":{"operationId":"RiskController_investigationAiSettings_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskInvestigationAiSettingsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read organization consent for AI-assisted investigations","tags":["Risk"]},"post":{"operationId":"RiskController_setInvestigationAiSettings_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetRiskInvestigationAiSettingsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskInvestigationAiSettingsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Organization owner: enable or disable AI-assisted investigations","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/investigations":{"post":{"operationId":"RiskController_investigate_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartRiskInvestigationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Start a durable reviewer investigation","tags":["Risk"]}},"/api/v1/risk/investigations/{id}/state":{"get":{"operationId":"RiskController_investigationState_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskInvestigationStateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Check whether an investigation snapshot is out of date","tags":["Risk"]}},"/api/v1/risk/investigations/{id}/reviews":{"post":{"operationId":"RiskController_reviewInvestigation_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRiskInvestigationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Record an immutable finding review (owner/admin); never changes risk decisions","tags":["Risk"]}},"/api/v1/risk/action-queue":{"get":{"operationId":"RiskController_actionQueue_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"policyKey","required":false,"in":"query","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"default":"open","type":"string","enum":["open","requested","acknowledged","failed","completed","cancelled","all"]}},{"name":"offset","required":false,"in":"query","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskActionQueueDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List risk actions across customers, oldest first","tags":["Risk"]}},"/api/v1/risk/{resource}":{"get":{"operationId":"RiskController_list_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"resource","required":true,"in":"path","schema":{"enum":["sources","contexts","subjects","policies","evidence","assessments","overrides","actions","events","investigations","investigation-reviews"],"type":"string"}},{"name":"resourceId","required":false,"in":"query","description":"Filter events by the resource whose history is requested.","schema":{"format":"uuid","type":"string"}},{"name":"investigationId","required":false,"in":"query","description":"Filter investigation review records by their run.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Literal case-insensitive search: subject/context external ID or policy key.","schema":{"type":"string"}},{"name":"subjectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Offset; pages contain at most 100 rows and may be shorter to respect the response byte limit.","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordListDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List risk resources in the authenticated environment","tags":["Risk"]}},"/api/v1/risk/{resource}/{id}":{"get":{"operationId":"RiskController_get_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"resource","required":true,"in":"path","schema":{"enum":["sources","contexts","subjects","policies","evidence","assessments","overrides","actions","events","investigations","investigation-reviews"],"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read a risk resource, including immutable history","tags":["Risk"]}},"/api/v1/risk/assessments/{id}/state":{"get":{"operationId":"RiskController_state_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskAssessmentStateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read assessment freshness and its effective decision","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/journey":{"get":{"operationId":"RiskController_journey_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["activity","evidence","assessments","actions","overrides"]}},{"name":"before","required":false,"in":"query","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskJourneyDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read a subject compliance timeline in receipt order","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/events/{eventId}/assessments":{"get":{"operationId":"RiskController_eventAssessments_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}},{"name":"resourceId","required":false,"in":"query","description":"Filter events by the resource whose history is requested.","schema":{"format":"uuid","type":"string"}},{"name":"investigationId","required":false,"in":"query","description":"Filter investigation review records by their run.","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","description":"Literal case-insensitive search: subject/context external ID or policy key.","schema":{"type":"string"}},{"name":"subjectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"offset","required":false,"in":"query","description":"Offset; pages contain at most 100 rows and may be shorter to respect the response byte limit.","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordListDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `eventId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read assessments linked to a subject event or evidence snapshot","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/activities":{"post":{"operationId":"RiskController_activity_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordRiskActivityDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Record reported compliance activity with authenticated provenance","tags":["Risk"]}},"/api/v1/risk/subjects":{"post":{"operationId":"RiskController_subject_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskSubjectDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create an independent risk subject","tags":["Risk"]}},"/api/v1/risk/contexts":{"post":{"operationId":"RiskController_createContext_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskContextDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Register a journey context; does not assign a policy or scope evidence","tags":["Risk"]}},"/api/v1/risk/contexts/{id}/subjects":{"post":{"operationId":"RiskController_addContextSubject_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRiskContextSubjectDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContextSubjectDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Attach an existing same-workspace, same-mode subject to a context","tags":["Risk"]},"get":{"operationId":"RiskController_contextSubjects_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Offset; pages contain at most 100 rows and may be shorter to respect the response byte limit.","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContextSubjectListDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List context memberships; follow nextOffset for the next page","tags":["Risk"]}},"/api/v1/risk/contexts/{id}/policies":{"get":{"operationId":"RiskController_contextPolicies_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContextPoliciesDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read pinned context policy versions; scoped evaluation remains unavailable","tags":["Risk"]},"post":{"operationId":"RiskController_configureContextPolicies_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureRiskContextPoliciesDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskContextPoliciesDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Replace context policy pins using the current revision (owner/admin); does not evaluate participants","tags":["Risk"]}},"/api/v1/risk/policies":{"post":{"operationId":"RiskController_policy_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskPolicyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create an immutable draft policy version (owner/admin)","tags":["Risk"]}},"/api/v1/risk/policies/{id}/publish":{"post":{"operationId":"RiskController_publish_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Publish a validated policy version (owner/admin)","tags":["Risk"]}},"/api/v1/risk/sources":{"post":{"operationId":"RiskController_createSource_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRiskSourceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Owner/admin: register immutable fact schemas and API-key submission bindings","tags":["Risk"]}},"/api/v1/risk/sources/{id}/bindings":{"post":{"operationId":"RiskController_updateSourceBindings_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRiskSourceBindingsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Owner/admin: rotate or disable submission bindings; historical receipts remain unchanged","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/evidence":{"post":{"operationId":"RiskController_evidence_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRiskEvidenceDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Append assertions through a registered source authorized for the submitting API key","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/evidence/batch":{"post":{"operationId":"RiskController_evidenceBatch_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRiskEvidenceBatchDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskEvidenceBatchDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Atomically append distinct facts through one registered source; retries return the original receipts","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/policy-selection":{"post":{"operationId":"RiskController_selectPolicies_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectRiskPoliciesDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Select applicable published policies from a pinned candidate set; records an audit event, not authorization","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/monitoring":{"get":{"operationId":"RiskController_monitoring_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskMonitoringDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List the customer’s explicitly assigned automatic risk policies","tags":["Risk"]},"post":{"operationId":"RiskController_configureMonitoring_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureRiskMonitoringDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Enable or pause automatic reassessment of a pinned published policy; returns its audit event","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/verification-decisions":{"post":{"operationId":"RiskController_recordVerificationDecision_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordRiskVerificationDecisionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Owner/admin: review a completed linked verification attempt independently of the overall session","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/assessments":{"post":{"operationId":"RiskController_assess_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessRiskDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Evaluate a published policy using persisted evidence","tags":["Risk"]}},"/api/v1/risk/subjects/{id}/session-checks":{"post":{"operationId":"RiskController_importCheck_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportRiskCheckDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Import a persisted, subject-bound Korala session check (same tenant and execution mode)","tags":["Risk"]}},"/api/v1/risk/assessments/{id}/overrides":{"post":{"operationId":"RiskController_override_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverrideRiskDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Record an expiring decision override (owner/admin)","tags":["Risk"]}},"/api/v1/risk/overrides/{id}/revoke":{"post":{"operationId":"RiskController_revoke_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskReasonDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Revoke an override with an audit reason (owner/admin)","tags":["Risk"]}},"/api/v1/risk/actions/{id}/transitions":{"post":{"operationId":"RiskController_transition_v1","parameters":[{"name":"Idempotency-Key","in":"header","description":"Required on mutation POSTs; validation and simulation are read-only exceptions. Retry the same request with the same key; changed input returns 409.","required":false,"schema":{"type":"string"}},{"name":"X-Risk-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode.","required":false,"schema":{"type":"string"}},{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRiskActionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskRecordDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Acknowledge, complete, fail, retry or cancel a required action","tags":["Risk"]}},"/api/v1/screening/runs":{"post":{"operationId":"ScreeningController_createRun_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"Idempotency-Key","in":"header","description":"Retry the same request with the same key to get the same run; a changed request returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScreeningRunDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningRunDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Screen a subject against the sanctions lists you name","tags":["Screening"]},"get":{"operationId":"ScreeningController_listRuns_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ScreeningRunStatus"}},{"name":"sessionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"riskSubjectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"maximum":100000,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedScreeningRunsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List screening runs, newest first","tags":["Screening"]}},"/api/v1/screening/runs/{id}":{"get":{"operationId":"ScreeningController_getRun_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningRunDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get a screening run with its matches","tags":["Screening"]}},"/api/v1/screening/matches/{id}/decision":{"post":{"description":"An organization owner or admin, signed in to the dashboard. API keys and members are refused (403).","operationId":"ScreeningController_decide_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Retry the same decision with the same key; a changed decision returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideScreeningMatchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningRunDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Confirm a match or mark it a false positive, with a reason","tags":["Screening"]}},"/api/v1/screening/sources":{"get":{"operationId":"ScreeningController_sources_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningSourceDto"}}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Each list: its active version, publication date, staleness and anything an operator must look at","tags":["Screening"]}},"/api/v1/screening/adverse-media/runs":{"post":{"description":"On request, for enhanced due diligence: findings go to review with their citations and never decline a customer. Test mode uses simulated articles and sends nothing to a search API or a model. Live mode answers 503 until adverse media is configured.","operationId":"AdverseMediaController_createRun_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"Idempotency-Key","in":"header","description":"Retry the same request with the same key to get the same run; a changed request returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdverseMediaRunDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaRunDto"}}}},"409":{"description":"Either the Idempotency-Key was used for a different request (permanent: use a new key), or the same request is still in progress and another retry is already waiting for it (`error: \"request_in_progress\"`, with Retry-After: retry later with the same key).","headers":{"Retry-After":{"description":"Sent with `request_in_progress` only: seconds to wait before retrying with the same key.","schema":{"type":"integer"}}}},"429":{"description":"Too many runs this minute or hour, or as many live runs in progress as the organization may have at once.","headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Search news for a subject and judge each article","tags":["Screening"]},"get":{"operationId":"AdverseMediaController_listRuns_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"status","required":false,"in":"query","schema":{"$ref":"#/components/schemas/AdverseMediaRunStatus"}},{"name":"sessionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"riskSubjectId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"maximum":100000,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedAdverseMediaRunsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List adverse media runs, newest first","tags":["Screening"]}},"/api/v1/screening/adverse-media/runs/{id}":{"get":{"operationId":"AdverseMediaController_getRun_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaRunDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get an adverse media run with its findings","tags":["Screening"]}},"/api/v1/screening/adverse-media/findings/{id}/decision":{"post":{"description":"An organization owner or admin, signed in to the dashboard. API keys and members are refused (403).","operationId":"AdverseMediaController_decide_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Retry the same decision with the same key; a changed decision returns 409.","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideAdverseMediaFindingDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaRunDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Confirm a finding or mark it a false positive, with a reason","tags":["Screening"]}},"/api/v1/catalog/forms":{"get":{"operationId":"CatalogController_listForms_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFormSummaryDto"}}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List standard forms available to clone","tags":["Catalog"]}},"/api/v1/catalog/forms/{versionId}/fields":{"get":{"description":"The signer roles and fields a clone of this version will have, so you can prepare your data before creating a template. Each field gives the canonical name you set values against, which role fills it, and any length or pattern it enforces. Positions and the PDF's internal AcroForm names are not returned: you fill by canonical name.","operationId":"CatalogController_getFormFields_v1","parameters":[{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogFormFieldsDto"}}}},"400":{"description":"Malformed UUID in path parameter (`versionId`)."},"404":{"description":"No published version with that ID"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List the fields of a catalog form version","tags":["Catalog"]}},"/api/v1/catalog/forms/{versionId}/create-template":{"post":{"description":"Copies the curated seed PDF into your organization and creates a template with the form's mapped fields and signer roles. Creating a template is free; usage is metered when you generate documents. Use the returned template with the normal generate/sign flow.","operationId":"CatalogController_createTemplate_v1","parameters":[{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateFromCatalogDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`versionId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create an org template from a catalog form version","tags":["Catalog"]}},"/api/v1/templates/markdown/preview":{"post":{"operationId":"TemplatesController_previewMarkdown_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownSourceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkdownPreviewDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Validate Markdown/Liquid and preview a PDF without saving or sending","tags":["Templates"]}},"/api/v1/templates/markdown":{"post":{"operationId":"TemplatesController_createMarkdown_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMarkdownTemplateDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a Markdown template and its source-defined signer roles and fields","tags":["Templates"]}},"/api/v1/templates/{id}/markdown":{"patch":{"operationId":"TemplatesController_updateMarkdown_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMarkdownTemplateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Save a new Markdown source revision and refresh the PDF and signing fields","tags":["Templates"]}},"/api/v1/templates/upload-url":{"post":{"operationId":"TemplatesController_createUploadUrl_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateUploadUrlDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateUploadUrlResponseDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get presigned URL for template upload","tags":["Templates"]}},"/api/v1/templates/{id}/confirm":{"post":{"operationId":"TemplatesController_confirmUpload_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Confirm template upload and set metadata","tags":["Templates"]}},"/api/v1/templates/{id}/replace-file":{"post":{"operationId":"TemplatesController_createReplaceFileUrl_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceTemplateFileDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceTemplateFileResponseDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get presigned URL to replace template file","tags":["Templates"]}},"/api/v1/templates/{id}/confirm-replace":{"post":{"operationId":"TemplatesController_confirmReplaceFile_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmReplaceTemplateFileDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Confirm template file replacement","tags":["Templates"]}},"/api/v1/templates/{id}/duplicate":{"post":{"description":"Copies the file, signer roles and fields into a new template. The copy is created in the mode of the calling key unless `sandbox` says otherwise, so a sandbox template can be promoted to live.","operationId":"TemplatesController_duplicate_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateTemplateDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Duplicate a template","tags":["Templates"]}},"/api/v1/templates":{"get":{"operationId":"TemplatesController_findAll_v1","parameters":[{"name":"sandbox","required":false,"in":"query","description":"Filter by mode: true returns only sandbox (test) templates, false only live ones. Omit to return both.","schema":{"default":false,"type":"boolean"}},{"name":"collectionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"collectionIds","required":false,"in":"query","description":"Match any listed collection, without duplicate resources. Comma-separated UUIDs or repeated query parameters. Cannot be combined with collectionId or unassigned=true.","schema":{"minItems":1,"maxItems":100,"uniqueItems":true,"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"unassigned","required":false,"in":"query","description":"No memberships, including archived collections. Cannot be combined with collectionId or collectionIds.","schema":{"type":"boolean"}},{"name":"includeCollections","required":false,"in":"query","description":"Include collectionIds for the returned page.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match against the template name and description.","schema":{"maxLength":255,"example":"W-8BEN","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/TemplateSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTemplatesDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all templates","tags":["Templates"]}},"/api/v1/templates/{id}":{"get":{"operationId":"TemplatesController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateWithDetailsDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get template with details","tags":["Templates"]},"patch":{"operationId":"TemplatesController_update_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update template metadata","tags":["Templates"]},"delete":{"operationId":"TemplatesController_delete_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Template deleted successfully"},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a template","tags":["Templates"]}},"/api/v1/templates/{id}/merge-fields":{"get":{"description":"Returns the auto-detected {{placeholder}} merge fields from the DOCX template body. Only available for DOCX templates.","operationId":"TemplatesController_getMergeFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DetectedMergeFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get detected merge fields for a DOCX template","tags":["Templates"]}},"/api/v1/templates/{id}/signer-roles":{"post":{"operationId":"TemplatesController_addSignerRole_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignerRoleDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSignerRoleDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add a signer role to the template","tags":["Templates"]},"get":{"operationId":"TemplatesController_getSignerRoles_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSignerRoleDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get all signer roles for a template","tags":["Templates"]}},"/api/v1/templates/{id}/signer-roles/{roleId}":{"patch":{"operationId":"TemplatesController_updateSignerRole_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"roleId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSignerRoleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateSignerRoleDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `roleId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a signer role","tags":["Templates"]},"delete":{"operationId":"TemplatesController_deleteSignerRole_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"roleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Signer role deleted successfully"},"400":{"description":"Malformed UUID in path parameter (`id`, `roleId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a signer role","tags":["Templates"]}},"/api/v1/templates/{id}/fields":{"post":{"operationId":"TemplatesController_addField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateFieldDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add a field to the template","tags":["Templates"]},"get":{"operationId":"TemplatesController_getFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get all fields for a template","tags":["Templates"]}},"/api/v1/templates/{id}/bookmarks":{"get":{"description":"Renders the DOCX template and reports the named destinations that reached the PDF. A bookmark is invisible in the document and in the rendered output, so this is how you confirm a name exists and see the form the converter rewrote it to.","operationId":"TemplatesController_getBookmarks_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateBookmarksDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List Word bookmarks available for bookmark placement","tags":["Templates"]}},"/api/v1/templates/{id}/form-fields":{"get":{"description":"Fillable PDFs (e.g. IRS tax forms like the W-9 or W-8BEN) embed their form fields in the file. This returns each field with its exact position, type, and name, so template fields can be created with acroFieldName links instead of guessed coordinates. Returns an empty list for flat PDFs.","operationId":"TemplatesController_getFormFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AcroFormFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List embedded AcroForm fields of the base PDF","tags":["Templates"]}},"/api/v1/templates/{id}/form-fields/parties":{"get":{"description":"The template counterpart of the document endpoint: reads the parties the base PDF names so each section can be handed to the right signer role. Empty for a single-party form.","operationId":"TemplatesController_getFormFieldParties_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFormFieldPartyDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"How the template fields divide between the parties it names","tags":["Templates"]}},"/api/v1/templates/{id}/form-fields/parties/assign":{"post":{"description":"The template counterpart of the document endpoint: the split is re-read here rather than taken from the caller, an unlabelled layout section carries a stamp of the split it came from so a stale one is refused, and either every party in the request moves or none does.","operationId":"TemplatesController_assignFormFieldParties_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignTemplateFormFieldPartiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFormFieldPartyDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Move each party's fields to the role that fills them","tags":["Templates"]}},"/api/v1/templates/{id}/form-fields/import":{"post":{"description":"Places every importable embedded form field as a template field, keeping the position, type, option list, character limit and font size the PDF declares. Read-only form fields are skipped. This runs automatically when a fillable PDF is confirmed, so call it only to assign the form to a different signer role or to redo an import.","operationId":"TemplatesController_importFormFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportTemplateFormFieldsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create template fields from the base PDF's embedded form","tags":["Templates"]}},"/api/v1/templates/{id}/fields/{fieldId}":{"patch":{"operationId":"TemplatesController_updateField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateFieldDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a template field","tags":["Templates"]},"delete":{"operationId":"TemplatesController_deleteField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Field deleted successfully"},"400":{"description":"Malformed UUID in path parameter (`id`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a template field","tags":["Templates"]}},"/api/v1/templates/{id}/create-document":{"post":{"operationId":"TemplatesController_createDocument_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentFromTemplateDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a document from this template","tags":["Templates"]}},"/api/v1/templates/{id}/generate":{"post":{"description":"Generates a PDF with template fields filled in using provided variables. This endpoint is for document generation only - no signing workflow is initiated.","operationId":"TemplatesController_generateDocument_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDocumentDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedDocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Generate a PDF from template with filled values (no signing)","tags":["Templates"]}},"/api/v1/collections":{"post":{"operationId":"CollectionsController_create_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}},"409":{"description":"externalId is already reserved in this organization and mode, including archived collections. Retrieve it using by-external-id."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a collection","tags":["Collections"]},"get":{"operationId":"CollectionsController_list_v1","parameters":[{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}},{"name":"search","required":false,"in":"query","schema":{"maxLength":255,"type":"string"}},{"name":"archiveStatus","required":false,"in":"query","schema":{"default":"active","type":"string","enum":["active","archived","all"]}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/CollectionSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCollectionsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List collections with member counts","tags":["Collections"]}},"/api/v1/collections/by-external-id":{"get":{"operationId":"CollectionsController_byExternalId_v1","parameters":[{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}},{"name":"externalId","required":true,"in":"query","schema":{"minLength":1,"maxLength":255,"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Find a collection by exact external ID, including archived collections","tags":["Collections"]}},"/api/v1/collections/{id}":{"get":{"operationId":"CollectionsController_get_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get a collection and member counts","tags":["Collections"]},"patch":{"operationId":"CollectionsController_update_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update collection metadata","tags":["Collections"]}},"/api/v1/collections/{id}/archive":{"post":{"operationId":"CollectionsController_archive_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Archive a collection without changing its contents or packets","tags":["Collections"]}},"/api/v1/collections/{id}/restore":{"post":{"operationId":"CollectionsController_restore_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Restore a collection","tags":["Collections"]}},"/api/v1/collections/{id}/documents":{"get":{"operationId":"CollectionsController_listDocuments_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}},{"name":"includeCollections","required":false,"in":"query","description":"Include collectionIds for the returned page.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Matches the document's name, or the name or email of anyone signing it.","schema":{"maxLength":255,"type":"string"}},{"name":"templateId","required":false,"in":"query","description":"Only documents created from this template.","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["draft","pending","completing","completed","failed","voided","expired"]}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/DocumentSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedDocumentsDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List collection documents","tags":["Collections"]}},"/api/v1/collections/{id}/templates":{"get":{"operationId":"CollectionsController_listTemplates_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Filter by mode: true returns only sandbox (test) templates, false only live ones. Omit to return both.","schema":{"default":false,"type":"boolean"}},{"name":"includeCollections","required":false,"in":"query","description":"Include collectionIds for the returned page.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match against the template name and description.","schema":{"maxLength":255,"example":"W-8BEN","type":"string"}},{"name":"isActive","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/TemplateSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTemplatesDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List collection templates","tags":["Collections"]}},"/api/v1/collections/{id}/documents/add":{"post":{"operationId":"CollectionsController_addDocuments_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDocumentsMutationDto"}}}},"responses":{"204":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add 1–100 existing documents atomically; repeated additions are harmless","tags":["Collections"]}},"/api/v1/collections/{id}/documents/remove":{"post":{"operationId":"CollectionsController_removeDocuments_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDocumentsMutationDto"}}}},"responses":{"204":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Remove document memberships atomically, preserving the documents","tags":["Collections"]}},"/api/v1/collections/{id}/templates/add":{"post":{"operationId":"CollectionsController_addTemplates_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionTemplatesMutationDto"}}}},"responses":{"204":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add 1–100 existing templates atomically; repeated additions are harmless","tags":["Collections"]}},"/api/v1/collections/{id}/templates/remove":{"post":{"operationId":"CollectionsController_removeTemplates_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionTemplatesMutationDto"}}}},"responses":{"204":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Remove template memberships atomically, preserving the templates","tags":["Collections"]}},"/api/v1/documents/upload-url":{"post":{"operationId":"DocumentsController_createUploadUrl_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadUrlDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadUrlResponseDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get presigned URL for document upload","tags":["Documents"]}},"/api/v1/documents/{id}/upload-url":{"post":{"description":"For a document created with POST upload-url whose file was never sent: returns a fresh presigned URL for the same document. Korala uses it when an AI assistant starts a document and the person uploads the PDF in the browser. Answers 409 once the file is there.","operationId":"DocumentsController_reissueUploadUrl_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadUrlResponseDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."},"404":{"description":"No such document"},"409":{"description":"The document is not a draft, or already has its file"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get a new upload URL for a draft that has no file yet","tags":["Documents"]}},"/api/v1/documents/{id}/confirm":{"post":{"operationId":"DocumentsController_confirmUpload_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmUploadDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Confirm document upload","tags":["Documents"]}},"/api/v1/documents":{"get":{"operationId":"DocumentsController_findAll_v1","parameters":[{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}},{"name":"collectionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"collectionIds","required":false,"in":"query","description":"Match any listed collection, without duplicate resources. Comma-separated UUIDs or repeated query parameters. Cannot be combined with collectionId or unassigned=true.","schema":{"minItems":1,"maxItems":100,"uniqueItems":true,"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"unassigned","required":false,"in":"query","description":"No memberships, including archived collections. Cannot be combined with collectionId or collectionIds.","schema":{"type":"boolean"}},{"name":"includeCollections","required":false,"in":"query","description":"Include collectionIds for the returned page.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Matches the document's name, or the name or email of anyone signing it.","schema":{"maxLength":255,"type":"string"}},{"name":"templateId","required":false,"in":"query","description":"Only documents created from this template.","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["draft","pending","completing","completed","failed","voided","expired"]}},{"name":"sortBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/DocumentSortBy"}},{"name":"sortOrder","required":false,"in":"query","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedDocumentsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all documents","tags":["Documents"]}},"/api/v1/documents/{id}":{"get":{"operationId":"DocumentsController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get document by ID","tags":["Documents"]},"patch":{"operationId":"DocumentsController_update_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update document metadata","tags":["Documents"]}},"/api/v1/documents/{id}/signers":{"post":{"operationId":"DocumentsController_addSigner_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSignerDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignerDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add a signer to the document","tags":["Documents"]},"get":{"operationId":"DocumentsController_getSigners_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SignerDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get all signers for a document","tags":["Documents"]}},"/api/v1/documents/{id}/fields":{"post":{"operationId":"DocumentsController_addField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFieldDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add a signature field to the document","tags":["Documents"]},"get":{"operationId":"DocumentsController_getFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get all fields for a document","tags":["Documents"]}},"/api/v1/documents/{id}/fields/batch":{"post":{"description":"Each entry is placed either at coordinates or against text, and each is judged on its own: an entry that cannot be placed is reported with its reason while the rest are placed. The file is read once however many entries are anchored.","operationId":"DocumentsController_addFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFieldsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFieldsResultDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Place many fields in one request","tags":["Documents"]}},"/api/v1/documents/{id}/fields/values":{"post":{"description":"Writes the data the sender already knows, so the signer is left with the signature. Works while the document is a draft and while it is out for signature. A signature or initials field belongs to the person who signs and is refused here, as is a field the signer has already filled. Each value is judged on its own and validated the same way a signer's fill is.","operationId":"DocumentsController_fillFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FillFieldsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FillFieldsResultDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Fill fields on behalf of the sender","tags":["Documents"]}},"/api/v1/documents/{id}/fields/anchored":{"post":{"description":"Names a phrase in the uploaded PDF (\"Tenant signature\") and where the field goes relative to it; the server works out the coordinates. For callers that cannot see the page. Use GET :id/text first when the phrase may appear more than once.","operationId":"DocumentsController_addAnchoredField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAnchoredFieldDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Add a field placed against text in the PDF","tags":["Documents"]}},"/api/v1/documents/{id}/blanks":{"get":{"description":"Reads the printed page and returns every ruled line and labelled blank, each with the words printed against it, the line it sits on and a box to place a field in. It does not decide what any blank is for: the label is returned so the caller can. A rule drawn as a graphic is not in the text layer and is not found here; use the text search to locate its label instead.","operationId":"DocumentsController_findBlanks_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentBlanksDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Where the document is waiting to be filled in","tags":["Documents"]}},"/api/v1/documents/{id}/text":{"get":{"description":"Returns every page size and, when `text` is given, each place it appears: page, box in points from the top-left, and the line it sits on. Flat PDFs carry no form fields to read positions from; this is how a caller that cannot see the page finds the signature line.","operationId":"DocumentsController_findText_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"text","required":false,"in":"query","description":"Text to look for. Matching ignores case and collapses whitespace, and a phrase must sit on one line. Omit it to get the page sizes only.","schema":{"example":"Tenant signature","type":"string"}},{"name":"texts","required":false,"in":"query","description":"Several phrases in one request (`?texts=Signature&texts=Date`), up to ten. The file is downloaded and parsed once for all of them, so ask together for what you would otherwise ask for one at a time. Each match says which phrase it is for, and `occurrence` counts per phrase.","schema":{"example":["Signature","Date"],"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTextDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Find text in the uploaded PDF, with page sizes","tags":["Documents"]}},"/api/v1/documents/{id}/text/pages":{"get":{"description":"Returns the text of each page as someone reading it would see it. One answer holds about 20,000 characters and at most 50 pages, in whole pages; `nextPage` says where to continue, so the number of pages is no limit. The file itself may be up to 25 MB. Pages without a text layer come back empty, and `hasText` is false when all of the returned ones are.","operationId":"DocumentsController_readText_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fromPage","required":false,"in":"query","description":"First page to read. Defaults to 1.","schema":{"example":1,"type":"number"}},{"name":"toPage","required":false,"in":"query","description":"Last page to read. Defaults to as many pages as fit in one answer; `nextPage` says where to continue.","schema":{"example":3,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPagesTextDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Read the text of the uploaded PDF, a run of pages at a time","tags":["Documents"]}},"/api/v1/documents/{id}/pages/{pageNumber}/image":{"get":{"description":"Renders one page of the uploaded PDF as a PNG. Rulers labelled in points from the top-left corner are drawn on it, which is the frame field positions use, so a caller that places fields by eye reads coordinates off the page instead of converting pixels. Fields already placed are outlined, so it can check its own work.","operationId":"DocumentsController_getPageImage_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"pageNumber","required":true,"in":"path","schema":{"type":"number"}},{"name":"rulers","required":false,"in":"query","description":"Draw rulers labelled in points from the top-left corner, the frame field positions use","schema":{"default":true,"type":"boolean"}},{"name":"fields","required":false,"in":"query","description":"Outline the fields already placed on this page","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageImageDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `pageNumber`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"A page as an image, with rulers and the fields placed on it","tags":["Documents"]}},"/api/v1/documents/{id}/form-fields":{"get":{"description":"Fillable PDFs (e.g. IRS tax forms like the W-9 or W-8BEN) embed their form fields in the file. This returns each field with its exact position, type, and name, so fields can be created with acroFieldName links instead of guessed coordinates. Returns an empty list for flat PDFs.","operationId":"DocumentsController_getFormFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AcroFormFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List embedded AcroForm fields of the uploaded PDF","tags":["Documents"]}},"/api/v1/documents/{id}/form-fields/parties":{"get":{"description":"A fillable PDF says where every box is but never who fills it, so an automatic import assigns the whole form to the first signer. This reads the parties the form itself names — employer and employee, landlord and tenant — from each field's tooltip and its name, so a sender can hand each section to the right signer. A form that names nobody is offered its own layout instead, cut along its widest breaks into as many unlabelled sections as there are signers. Returns an empty list for a single-party form such as a W-9, which is the common case.","operationId":"DocumentsController_getFormFieldParties_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FormFieldPartyDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"How the placed fields divide between the parties the form names","tags":["Documents"]}},"/api/v1/documents/{id}/form-fields/parties/assign":{"post":{"description":"Send which party goes to which signer; the split is re-read here, so a field added or removed since the parties were fetched cannot be missed or moved by a stale list. An unlabelled layout section carries a stamp of the split it came from, so one read before the form changed is refused rather than applied to different fields — refetch the parties and resend. Either every party in the request moves or none does. Returns the parties as they stand afterwards.","operationId":"DocumentsController_assignFormFieldParties_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignFormFieldPartiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FormFieldPartyDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Move each party's fields to the signer who fills them","tags":["Documents"]}},"/api/v1/documents/{id}/form-fields/import":{"post":{"description":"Places every importable embedded form field as a real field assigned to the given signer, keeping the position, type, option list, character limit and font size the PDF declares. Read-only form fields are skipped. This runs automatically for the first signer added to an uploaded fillable PDF, so call it only to assign the form to a different signer or to redo an import.","operationId":"DocumentsController_importFormFields_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportFormFieldsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create fields for a signer from the PDF's embedded form","tags":["Documents"]}},"/api/v1/documents/{id}/fields/{fieldId}":{"patch":{"operationId":"DocumentsController_updateField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFieldDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a field position or size","tags":["Documents"]},"delete":{"operationId":"DocumentsController_removeField_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Field removed successfully"},"400":{"description":"Malformed UUID in path parameter (`id`, `fieldId`)."},"404":{"description":"No such field on this document"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Remove a field from the document","tags":["Documents"]}},"/api/v1/documents/{id}/signers/{signerId}":{"patch":{"operationId":"DocumentsController_updateSigner_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"signerId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSignerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignerDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `signerId`)."},"404":{"description":"No such signer on this document"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Rename a signer or change their signing order (draft only)","tags":["Documents"]},"delete":{"operationId":"DocumentsController_removeSigner_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"signerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Signer removed successfully"},"400":{"description":"Malformed UUID in path parameter (`id`, `signerId`)."},"404":{"description":"No such signer on this document"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Remove a signer from the document","tags":["Documents"]}},"/api/v1/documents/{id}/send":{"post":{"operationId":"DocumentsController_send_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Send document for signing","tags":["Documents"]}},"/api/v1/documents/{id}/audit-trail":{"get":{"operationId":"DocumentsController_getAuditTrail_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get audit trail for a document","tags":["Documents"]}},"/api/v1/documents/bulk-sign":{"post":{"operationId":"DocumentsController_bulkSign_v1","parameters":[{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSignRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSignResponseDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Sign multiple documents at once using a saved signature","tags":["Documents"]}},"/api/v1/documents/{id}/void":{"post":{"operationId":"DocumentsController_voidDocument_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Void a document","tags":["Documents"]}},"/api/v1/webhooks":{"post":{"operationId":"WebhooksController_create_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecretDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a new webhook","tags":["Webhooks"]},"get":{"operationId":"WebhooksController_findAll_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDto"}}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all webhooks","tags":["Webhooks"]}},"/api/v1/webhooks/{id}":{"get":{"operationId":"WebhooksController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get webhook by ID","tags":["Webhooks"]},"patch":{"operationId":"WebhooksController_update_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a webhook","tags":["Webhooks"]},"delete":{"operationId":"WebhooksController_delete_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted successfully"},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a webhook","tags":["Webhooks"]}},"/api/v1/webhooks/{id}/deliveries":{"get":{"operationId":"WebhooksController_getDeliveries_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryListDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get webhook delivery history","tags":["Webhooks"]}},"/api/v1/webhooks/{id}/test":{"post":{"operationId":"WebhooksController_sendTestEvent_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Send a test webhook event","tags":["Webhooks"]}},"/api/v1/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"operationId":"WebhooksController_retryDelivery_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"deliveryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `deliveryId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Retry a failed or retrying webhook delivery","tags":["Webhooks"]}},"/api/v1/billing/usage":{"get":{"operationId":"BillingController_getUsage_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get current billing period usage","tags":["Billing"]}},"/api/v1/billing/sandbox-usage":{"get":{"operationId":"BillingController_getSandboxUsage_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxUsageDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get sandbox (test mode) usage for current period","tags":["Billing"]}},"/api/v1/billing/plan":{"get":{"operationId":"BillingController_getPlan_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get current plan details","tags":["Billing"]}},"/api/v1/documents/{documentId}/field-detection":{"post":{"operationId":"FieldDetectionController_triggerDetection_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerFieldDetectionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDetectionJobDto"}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Trigger AI field detection for a document","tags":["Field Detection"]}},"/api/v1/documents/{documentId}/field-detection/status":{"get":{"operationId":"FieldDetectionController_getStatus_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDetectionJobDto"}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get field detection job status","tags":["Field Detection"]}},"/api/v1/documents/{documentId}/field-detection/proposed":{"get":{"operationId":"FieldDetectionController_getProposedFields_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProposedFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get proposed fields from AI detection","tags":["Field Detection"]}},"/api/v1/documents/{documentId}/field-detection/proposed/{fieldId}/accept":{"patch":{"operationId":"FieldDetectionController_acceptField_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptProposedFieldDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposedFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Accept a proposed field","tags":["Field Detection"]}},"/api/v1/documents/{documentId}/field-detection/proposed/{fieldId}/reject":{"patch":{"operationId":"FieldDetectionController_rejectField_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposedFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Reject a proposed field","tags":["Field Detection"]}},"/api/v1/documents/{documentId}/field-detection/proposed/accept-all":{"post":{"operationId":"FieldDetectionController_acceptAllFields_v1","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptAllProposedFieldsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptAllResultDto"}}}},"400":{"description":"Malformed UUID in path parameter (`documentId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Accept all proposed fields above confidence threshold","tags":["Field Detection"]}},"/api/v1/templates/{templateId}/field-detection":{"post":{"operationId":"TemplateFieldDetectionController_triggerDetection_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerFieldDetectionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDetectionJobDto"}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Trigger AI field detection for a template","tags":["Template Field Detection"]}},"/api/v1/templates/{templateId}/field-detection/status":{"get":{"operationId":"TemplateFieldDetectionController_getStatus_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldDetectionJobDto"}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get field detection job status","tags":["Template Field Detection"]}},"/api/v1/templates/{templateId}/field-detection/proposed":{"get":{"operationId":"TemplateFieldDetectionController_getProposedFields_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProposedFieldDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get proposed fields from AI detection","tags":["Template Field Detection"]}},"/api/v1/templates/{templateId}/field-detection/proposed/{fieldId}/accept":{"patch":{"operationId":"TemplateFieldDetectionController_acceptField_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptTemplateProposedFieldDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposedFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Accept a proposed field","tags":["Template Field Detection"]}},"/api/v1/templates/{templateId}/field-detection/proposed/{fieldId}/reject":{"patch":{"operationId":"TemplateFieldDetectionController_rejectField_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fieldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposedFieldDto"}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`, `fieldId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Reject a proposed field","tags":["Template Field Detection"]}},"/api/v1/templates/{templateId}/field-detection/proposed/accept-all":{"post":{"operationId":"TemplateFieldDetectionController_acceptAllFields_v1","parameters":[{"name":"templateId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptAllTemplateProposedFieldsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptAllResultDto"}}}},"400":{"description":"Malformed UUID in path parameter (`templateId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Accept all proposed fields above confidence threshold","tags":["Template Field Detection"]}},"/api/v1/signatures":{"post":{"operationId":"SignaturesController_create_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSavedSignatureDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedSignatureDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a saved signature","tags":["Signatures"]},"get":{"operationId":"SignaturesController_findAll_v1","parameters":[{"name":"email","required":false,"in":"query","description":"Filter by signer email","schema":{"example":"ceo@company.com","type":"string"}},{"name":"kind","required":false,"in":"query","description":"Filter by kind","schema":{"type":"string","enum":["signature","initials"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SavedSignatureDto"}}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List saved signatures","tags":["Signatures"]}},"/api/v1/signatures/{id}":{"get":{"operationId":"SignaturesController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedSignatureDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get a saved signature","tags":["Signatures"]},"delete":{"operationId":"SignaturesController_delete_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Signature deleted successfully"},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a saved signature","tags":["Signatures"]}},"/api/v1/signing-packets":{"post":{"operationId":"SigningPacketsController_create_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSigningPacketDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a multi-document signing packet","tags":["Signing Packets"]},"get":{"operationId":"SigningPacketsController_findAll_v1","parameters":[{"name":"sandbox","required":false,"in":"query","description":"Dashboard mode. API keys always use their authenticated mode.","schema":{"default":false,"type":"boolean"}},{"name":"sourceCollectionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["draft","sent","viewed","processing","partially_completed","recipient_completed","voided","expired"]}},{"name":"search","required":false,"in":"query","description":"Search packet or recipient details","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSigningPacketsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List signing packets","tags":["Signing Packets"]}},"/api/v1/signing-packets/eligible-documents":{"get":{"operationId":"SigningPacketsController_eligibleDocuments_v1","parameters":[{"name":"documentIds","required":false,"in":"query","description":"Explicit document selection, encoded as comma-separated UUIDs.","schema":{"maxItems":50,"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"collectionId","required":false,"in":"query","schema":{"format":"uuid","type":"string"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"recipientEmail","required":false,"in":"query","description":"Return signer records for this email","schema":{"type":"string"}},{"name":"sandbox","required":false,"in":"query","description":"Filter by live or test mode","schema":{"type":"boolean"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEligiblePacketDocumentsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List documents eligible for a signing packet","tags":["Signing Packets"]}},"/api/v1/signing-packets/{id}":{"get":{"operationId":"SigningPacketsController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get a signing packet","tags":["Signing Packets"]},"patch":{"operationId":"SigningPacketsController_update_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSigningPacketDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a draft signing packet","tags":["Signing Packets"]}},"/api/v1/signing-packets/{id}/send":{"post":{"operationId":"SigningPacketsController_send_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSigningPacketDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Freeze and send a signing packet","tags":["Signing Packets"]}},"/api/v1/signing-packets/{id}/remind":{"post":{"operationId":"SigningPacketsController_remind_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Send another packet access email","tags":["Signing Packets"]}},"/api/v1/signing-packets/{id}/void":{"post":{"operationId":"SigningPacketsController_void_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Void a signing packet","tags":["Signing Packets"]}},"/api/v1/signing-packets/{id}/audit":{"get":{"operationId":"SigningPacketsController_audit_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SigningPacketAuditDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get the packet audit trail","tags":["Signing Packets"]}},"/api/v1/workflows":{"post":{"operationId":"WorkflowsController_createDefinition_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowDefinitionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDefinitionDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a new workflow definition","tags":["Workflows"]},"get":{"operationId":"WorkflowsController_findAllDefinitions_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"includePublic","required":false,"in":"query","description":"Include public workflows in results","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedWorkflowDefinitionsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all workflow definitions","tags":["Workflows"]}},"/api/v1/workflows/{slug}":{"get":{"operationId":"WorkflowsController_findDefinitionBySlug_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDefinitionDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get workflow definition by slug","tags":["Workflows"]},"patch":{"operationId":"WorkflowsController_updateDefinition_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkflowDefinitionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDefinitionDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a workflow definition","tags":["Workflows"]},"delete":{"operationId":"WorkflowsController_deleteDefinition_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Workflow deleted successfully"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a workflow definition","tags":["Workflows"]}},"/api/v1/workflows/{slug}/run":{"post":{"description":"Creates a new workflow run and returns an upload URL. Upload your document to the URL, then call confirm to start processing.","operationId":"WorkflowsController_startRun_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponseDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Start a new workflow run","tags":["Workflows"]}},"/api/v1/workflows/runs":{"get":{"operationId":"WorkflowsController_findAllRuns_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"workflowDefinitionId","required":false,"in":"query","description":"Filter by workflow definition ID","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedWorkflowRunsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all workflow runs","tags":["Workflows"]}},"/api/v1/workflows/runs/{id}":{"get":{"description":"Returns the current status and results of a workflow run.","operationId":"WorkflowsController_findRunById_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunWithStepsDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"summary":"Get workflow run by ID","tags":["Workflows"]}},"/api/v1/workflows/runs/{id}/confirm":{"post":{"description":"Call this after uploading the document to start the workflow execution.","operationId":"WorkflowsController_confirmUpload_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmWorkflowUploadDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."},"409":{"description":"The run has already started: an earlier confirm was accepted."}},"summary":"Confirm upload and start workflow processing","tags":["Workflows"]}},"/api/v1/workflows/runs/{id}/steps":{"get":{"operationId":"WorkflowsController_getRunSteps_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStepRunDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"summary":"Get all step runs for a workflow run","tags":["Workflows"]}},"/api/v1/workflows/runs/{id}/artifacts":{"get":{"operationId":"WorkflowsController_getRunArtifacts_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunArtifactDto"}}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get artifacts for a workflow run","tags":["Workflows"]}},"/api/v1/workflows/runs/{id}/review":{"post":{"description":"Approve or reject a workflow run that is paused at a review step.","operationId":"WorkflowsController_submitReview_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewWorkflowStepDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunWithStepsDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Submit review for a paused workflow run","tags":["Workflows"]}},"/api/v1/public/workflows":{"get":{"operationId":"PublicWorkflowsController_findAllPublicDefinitions_v1","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"includePublic","required":false,"in":"query","description":"Include public workflows in results","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedWorkflowDefinitionsDto"}}}}},"summary":"List public workflow definitions","tags":["Public Workflows"]}},"/api/v1/public/workflows/{slug}":{"get":{"operationId":"PublicWorkflowsController_findPublicDefinitionBySlug_v1","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDefinitionDto"}}}}},"summary":"Get public workflow definition by slug","tags":["Public Workflows"]}},"/api/v1/public/workflows/{slug}/run":{"post":{"description":"Creates a new workflow run for a public workflow. Upload your document to the returned URL, then call confirm.","operationId":"PublicWorkflowsController_startPublicRun_v1","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRunResponseDto"}}}}},"summary":"Start a new public workflow run","tags":["Public Workflows"]}},"/api/v1/sessions":{"post":{"operationId":"SessionsController_createSession_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetailDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a new session","tags":["Sessions"]},"get":{"operationId":"SessionsController_findAllSessions_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"originContextId","required":false,"in":"query","description":"Filter by registered originating risk context.","schema":{"type":"string"}},{"name":"subjectId","required":false,"in":"query","description":"Filter by explicitly linked Korala risk subject ID.","schema":{"type":"string"}},{"name":"externalUserId","required":false,"in":"query","description":"Filter by external user ID","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by session status","schema":{"$ref":"#/components/schemas/SessionStatus"}},{"name":"resolution","required":false,"in":"query","description":"Filter by resolution","schema":{"$ref":"#/components/schemas/SessionResolution"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSessionsDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List all sessions","tags":["Sessions"]}},"/api/v1/sessions/{id}":{"get":{"operationId":"SessionsController_findSessionById_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetailDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get session detail by ID","tags":["Sessions"]}},"/api/v1/sessions/{id}/expire":{"post":{"operationId":"SessionsController_expireSession_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Session expired successfully"},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Force-expire a session","tags":["Sessions"]}},"/api/v1/sessions/{id}/resolve":{"post":{"operationId":"SessionsController_resolveSession_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveSessionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetailDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Set session resolution (approved/rejected)","tags":["Sessions"]}},"/api/v1/sessions/{id}/workflows/{swId}/resubmit":{"post":{"operationId":"SessionsController_requestResubmission_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResubmitSessionWorkflowDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetailDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `swId`)."},"409":{"description":"The session has a decision by your team or integration; pass reopen: true to withdraw it and resubmit"}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Request resubmission for a workflow within a session","tags":["Sessions"]}},"/api/v1/sessions/{id}/workflows/{swId}/document":{"get":{"operationId":"SessionsController_getDocumentUrl_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"400":{"description":"Malformed UUID in path parameter (`id`, `swId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get download URL for uploaded document in a session workflow","tags":["Sessions"]}},"/api/v1/sessions/{id}/workflows/{swId}/artifacts":{"get":{"operationId":"SessionsController_getWorkflowArtifacts_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionWorkflowArtifactListDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`, `swId`)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List uploaded artifacts for a session workflow","tags":["Sessions"]}},"/api/v1/session-configurations":{"post":{"operationId":"SessionConfigurationsController_createConfiguration_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionConfigurationDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionConfigurationDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Create a session configuration","tags":["Session Configurations"]},"get":{"operationId":"SessionConfigurationsController_listConfigurations_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SessionConfigurationDto"}}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"List session configurations","tags":["Session Configurations"]}},"/api/v1/session-configurations/{slug}":{"get":{"operationId":"SessionConfigurationsController_getConfiguration_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionConfigurationDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get session configuration by slug","tags":["Session Configurations"]},"patch":{"operationId":"SessionConfigurationsController_updateConfiguration_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSessionConfigurationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionConfigurationDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Update a session configuration","tags":["Session Configurations"]},"delete":{"operationId":"SessionConfigurationsController_deleteConfiguration_v1","parameters":[{"name":"X-Korala-Mode","in":"header","description":"Dashboard JWT: live (default) or test. API keys are pinned to their credential mode. Mode cannot be changed after creation.","required":false,"schema":{"type":"string","enum":["live","test"]}},{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Delete a session configuration","tags":["Session Configurations"]}},"/api/v1/v/{token}":{"get":{"operationId":"SessionAccessController_getSession_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionAccessDto"}}}}},"summary":"Get session by access token","tags":["Session Access"]}},"/api/v1/v/{token}/handoff":{"post":{"description":"A link and QR code, valid for ten minutes, that open this session on another device at the step it has reached. The link carries no access token.","operationId":"SessionAccessController_createHandoff_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionHandoffDto"}}}}},"summary":"Continue a session on another device","tags":["Session Access"]}},"/api/v1/v/handoff/{code}":{"post":{"description":"Exchanges the code from a handoff link for the session it opens.","operationId":"SessionAccessController_redeemHandoff_v1","parameters":[{"name":"code","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionHandoffRedeemedDto"}}}},"400":{"description":"Not a genuine handoff link"},"410":{"description":"The link, or the session, has expired"}},"summary":"Open a session from a handoff link","tags":["Session Access"]}},"/api/v1/v/{token}/workflows/{swId}/start":{"post":{"description":"Creates a new workflow run and returns an upload URL. Only the current sequential workflow can be started.","operationId":"SessionAccessController_startWorkflow_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSessionWorkflowDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSessionWorkflowResponseDto"}}}},"400":{"description":"Not the current step; the binding asks for a document choice that is missing, malformed or not allowed; or the choice leaves nothing to capture."},"409":{"description":"The step is already running: follow it with the status route."}},"summary":"Start a workflow within a session","tags":["Session Access"]}},"/api/v1/v/{token}/workflows/{swId}/confirm":{"post":{"operationId":"SessionAccessController_confirmUpload_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}},{"name":"user-agent","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmSessionWorkflowUploadDto"}}}},"responses":{"200":{"description":""},"400":{"description":"Malformed UUID in path parameter (`swId`)."},"409":{"description":"The workflow has already started: an earlier confirm was accepted."}},"summary":"Confirm upload and start workflow processing","tags":["Session Access"]}},"/api/v1/v/{token}/workflows/{swId}/liveness/start":{"post":{"description":"For a slot flagged livenessSession: opens a live camera check session bound to this run and returns the session id with credentials that can only stream it. Three attempts per slot; each is billed.","operationId":"SessionAccessController_startLiveness_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartLivenessSessionDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivenessSessionDto"}}}},"400":{"description":"Not a Face Liveness slot, or no attempts left"},"409":{"description":"The run has started, or the slot is already filled"}},"summary":"Open a Face Liveness session for a capture slot","tags":["Session Access"]}},"/api/v1/v/{token}/workflows/{swId}/liveness/complete":{"post":{"description":"Call as soon as the check finishes in the browser: the API fetches the liveness result (available for three minutes), stores the reference frame as the slot's capture and reports whether the slot is filled or the check can be retried.","operationId":"SessionAccessController_completeLiveness_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteLivenessSessionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivenessSessionOutcomeDto"}}}},"400":{"description":"Not the session opened for this slot"},"409":{"description":"The session was already completed"}},"summary":"Complete a Face Liveness session","tags":["Session Access"]}},"/api/v1/v/{token}/workflows/{swId}/status":{"get":{"operationId":"SessionAccessController_getWorkflowStatus_v1","parameters":[{"name":"token","required":true,"in":"path","schema":{"type":"string"}},{"name":"swId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionWorkflowRunStatusDto"}}}},"400":{"description":"Malformed UUID in path parameter (`swId`)."}},"summary":"Get workflow run status within a session","tags":["Session Access"]}},"/api/v1/google-workspace/imports":{"post":{"operationId":"GoogleWorkspaceController_create_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleImportRequestDto"}}}},"responses":{"202":{"description":"Durable import accepted. Poll GET /google-workspace/imports/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleImportDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"tags":["Google Workspace"]}},"/api/v1/google-workspace/imports/{id}":{"get":{"operationId":"GoogleWorkspaceController_get_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleImportDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"tags":["Google Workspace"]}},"/api/v1/google-workspace/imports/{id}/values":{"post":{"operationId":"GoogleWorkspaceController_values_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleValuesDto"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleImportDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"tags":["Google Workspace"]}},"/api/v1/google-workspace/imports/{id}/publish":{"post":{"operationId":"GoogleWorkspaceController_publish_v1","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GooglePublishDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleImportDto"}}}},"400":{"description":"Malformed UUID in path parameter (`id`)."}},"security":[{"api-key":[]},{"bearer":[]}],"tags":["Google Workspace"]}}},"info":{"title":"Korala Public API","description":"Public API for Korala document signing service","version":"1.0.0","contact":{}},"tags":[],"servers":[{"url":"https://api.korala.ai","description":"Production"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-Key"},"timestamp":{"type":"apiKey","in":"header","name":"X-Timestamp"},"signature":{"type":"apiKey","in":"header","name":"X-Signature"}},"schemas":{"RiskPolicySchemaDto":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1"]},"schema":{"type":"object","additionalProperties":true},"description":{"type":"string"}},"required":["schemaVersion","schema","description"]},"ValidateRiskPolicyDto":{"type":"object","properties":{"definition":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","bands","rules"],"additionalProperties":false}]}},"required":["definition"]},"RiskPolicyValidationErrorDto":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]},"RiskPolicyValidationDto":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/RiskPolicyValidationErrorDto"}},"definition":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","match","weight","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","aggregation","floor","ceiling","bands","rules","missingEvidence"],"additionalProperties":false}],"nullable":true}},"required":["valid","errors","definition"]},"SimulateRiskPolicyDto":{"type":"object","properties":{"definition":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","bands","rules"],"additionalProperties":false}]},"scenarios":{"type":"array","$schema":"https://json-schema.org/draft/2020-12/schema","minItems":1,"maxItems":20,"items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"observations":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"source":{"type":"string","minLength":1,"maxLength":200},"value":{"anyOf":[{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]},{"type":"null"}]},"status":{"type":"string","enum":["available","unavailable","revoked"]},"observedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"receivedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"expiresAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"modelProvenance":{"type":"object","properties":{"provider":{"type":"string","minLength":1,"maxLength":100},"model":{"type":"string","minLength":1,"maxLength":100},"criteriaVersion":{"type":"string","minLength":1,"maxLength":100},"inputDigest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"runId":{"type":"string","minLength":1,"maxLength":200}},"required":["provider","model","criteriaVersion","inputDigest","runId"],"additionalProperties":false},"provenance":{"type":"object","properties":{"sourceRegistrationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"sourceRevision":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"assertedBy":{"type":"string","pattern":"^api_key:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"adapter":{"type":"string","const":"registered-external-v1"},"evidenceClass":{"type":"string","const":"assertion"}},"required":["sourceRegistrationId","sourceRevision","assertedBy","adapter","evidenceClass"],"additionalProperties":false}},"required":["fact","source","value","status","observedAt"],"additionalProperties":false}},"expected":{"type":"object","properties":{"status":{"type":"string","enum":["complete","incomplete"]},"decision":{"type":"string","enum":["none","review","restrict","reject","awaiting_evidence"]},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"band":{"anyOf":[{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},{"type":"null"}]},"actions":{"maxItems":2040,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}},"applicability":{"type":"string","enum":["matched","not_matched","unknown"]}},"additionalProperties":false}},"required":["name","at","observations"],"additionalProperties":false}}},"required":["definition","scenarios"]},"RiskMissingFactDto":{"type":"object","properties":{"fact":{"type":"string"},"reason":{"type":"string"}},"required":["fact","reason"]},"RiskReceiptProvenanceDto":{"type":"object","properties":{"sourceRegistrationId":{"type":"string","format":"uuid"},"sourceRevision":{"type":"number"},"assertedBy":{"type":"string"},"adapter":{"type":"string","enum":["registered-external-v1"]},"evidenceClass":{"type":"string","enum":["assertion"]}},"required":["sourceRegistrationId","sourceRevision","assertedBy","adapter","evidenceClass"]},"RiskModelProvenanceDto":{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"criteriaVersion":{"type":"string"},"inputDigest":{"type":"string","description":"SHA-256 of the exact model input snapshot"},"runId":{"type":"string"}},"required":["provider","model","criteriaVersion","inputDigest","runId"]},"RiskEvaluationInputDto":{"type":"object","properties":{"provenance":{"$ref":"#/components/schemas/RiskReceiptProvenanceDto"},"providerRef":{"type":"string","nullable":true},"modelProvenance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskModelProvenanceDto"}]},"id":{"type":"string","format":"uuid"},"fact":{"type":"string"},"value":{"nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}]},"source":{"type":"string"},"status":{"type":"string","enum":["available","unavailable","revoked"]},"observedAt":{"type":"string","format":"date-time"},"receivedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","fact","value","source","status","observedAt","receivedAt","expiresAt"]},"RiskInputCoverageDto":{"type":"object","properties":{"fact":{"type":"string"},"requirement":{"type":"string","enum":["required","supporting"]},"status":{"type":"string","enum":["available","unavailable"]},"reason":{"type":"string","nullable":true}},"required":["fact","requirement","status","reason"]},"RiskFactorResultDto":{"type":"object","properties":{"id":{"type":"string"},"points":{"type":"number"},"weight":{"type":"number"},"contribution":{"type":"number"},"matchedCases":{"type":"array","items":{"type":"number"}}},"required":["id","points","weight","contribution","matchedCases"]},"RiskRuleResultDto":{"type":"object","properties":{"id":{"type":"string"},"matched":{"type":"boolean","nullable":true},"reason":{"type":"string"}},"required":["id","matched","reason"]},"RiskEvaluationDto":{"type":"object","properties":{"evaluatorVersion":{"type":"string","enum":["risk-v1"]},"status":{"type":"string","enum":["complete","incomplete"]},"score":{"type":"number","nullable":true},"band":{"type":"string","nullable":true},"decision":{"type":"string","enum":["none","review","restrict","reject","awaiting_evidence"]},"missing":{"type":"array","items":{"$ref":"#/components/schemas/RiskMissingFactDto"}},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/RiskEvaluationInputDto"}},"coverage":{"type":"array","items":{"$ref":"#/components/schemas/RiskInputCoverageDto"}},"factors":{"type":"array","items":{"$ref":"#/components/schemas/RiskFactorResultDto"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/RiskRuleResultDto"}},"actions":{"type":"array","items":{"type":"string"}},"validUntil":{"type":"string","nullable":true,"format":"date-time"}},"required":["evaluatorVersion","status","score","band","decision","missing","inputs","factors","rules","actions","validUntil"]},"RiskSimulationScenarioResultDto":{"type":"object","properties":{"name":{"type":"string"},"applicability":{"type":"object","additionalProperties":true},"result":{"$ref":"#/components/schemas/RiskEvaluationDto"},"checks":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["status","decision","score","band","actions","applicability"]},"expected":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"actual":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"matched":{"type":"boolean"}},"required":["field","expected","actual","matched"],"additionalProperties":false}},{"type":"null"}],"description":"Expected-outcome comparisons, or null when no expectations were supplied. These check synthetic behavior only."}},"required":["name","applicability","result","checks"]},"RiskPolicySimulationDto":{"type":"object","properties":{"simulation":{"type":"number","enum":[true]},"schemaVersion":{"type":"string","enum":["1"]},"scenarios":{"type":"array","items":{"$ref":"#/components/schemas/RiskSimulationScenarioResultDto"}}},"required":["simulation","schemaVersion","scenarios"]},"RiskVerificationInputDto":{"type":"object","properties":{"source":{"type":"string","description":"Canonical trusted source for this exact field binding. Copy into acceptedSources."},"ageSource":{"type":"string","description":"Canonical trusted source when deriving age_years from date of birth."},"stepType":{"type":"string","description":"Workflow step type, or workflow for the overall decision"},"workflowDefinitionId":{"type":"string","format":"uuid"},"workflowName":{"type":"string"},"workflowUpdatedAt":{"type":"string","format":"date-time"},"stepIndex":{"type":"number"},"field":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","list"]},"itemType":{"type":"string","enum":["string","number","boolean"]},"description":{"type":"string"}},"required":["source","stepType","workflowDefinitionId","workflowName","workflowUpdatedAt","stepIndex","field","label","type","description"]},"RiskVerificationInputListDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RiskVerificationInputDto"}},"nextOffset":{"type":"number","nullable":true}},"required":["items","nextOffset"]},"RiskInvestigationAiSettingsDto":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]},"SetRiskInvestigationAiSettingsDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Owner opt-in for advisory TypeSafe/Jev processing of risk evidence"}},"required":["enabled"]},"StartRiskInvestigationDto":{"type":"object","properties":{"provider":{"type":"string","enum":["jev"]},"confirmExternalProcessing":{"type":"boolean","description":"Reviewer confirmation to send selected evidence fact/value pairs to TypeSafe for advisory comparison"}},"required":["confirmExternalProcessing"]},"RiskContextDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"kind":{"type":"string"},"externalId":{"type":"string"},"createdBy":{"type":"string"},"policyRevision":{"type":"number","description":"Revision of the context policy configuration."}},"required":["id","organizationId","sandbox","createdAt","kind","externalId","createdBy","policyRevision"]},"RiskSourceScopesDto":{"type":"object","properties":{"subject":{"type":"boolean","description":"Permit general subject evidence."},"contextKinds":{"description":"Reserved journey types. Context intake remains unsupported.","type":"array","items":{"type":"string"}}},"required":["subject","contextKinds"]},"RiskSourceFactDto":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","list"]},"itemType":{"type":"string","enum":["string","number","boolean"]}},"required":["key","type"]},"RiskSourceDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"scopes":{"$ref":"#/components/schemas/RiskSourceScopesDto"},"key":{"type":"string"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/RiskSourceFactDto"}},"apiKeyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"enabled":{"type":"boolean"},"revision":{"type":"number"},"createdBy":{"type":"string"},"updatedBy":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","sandbox","createdAt","scopes","key","facts","apiKeyIds","enabled","revision","createdBy","updatedBy","updatedAt"]},"RiskInvestigationEvidenceDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fact":{"type":"string"},"source":{"type":"string"},"status":{"type":"string","enum":["available","unavailable","revoked"]},"value":{"nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}]},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","fact","source","status","value","expiresAt"]},"RiskInvestigationAssessmentDto":{"type":"object","properties":{"id":{"type":"string"},"policyKey":{"type":"string"},"policyVersionId":{"type":"string"},"band":{"type":"string","nullable":true},"decision":{"type":"string"},"validUntil":{"type":"string","nullable":true,"format":"date-time"},"missing":{"type":"array","items":{"$ref":"#/components/schemas/RiskMissingFactDto"}}},"required":["id","policyKey","policyVersionId","band","decision","validUntil","missing"]},"RiskInvestigationActionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"status":{"type":"string","enum":["requested","acknowledged","completed","failed","cancelled"]},"revision":{"type":"number"}},"required":["id","key","status","revision"]},"RiskInvestigationSnapshotDto":{"type":"object","properties":{"capturedAt":{"type":"string","format":"date-time"},"evidenceRevision":{"type":"number"},"assessmentRevision":{"type":"number"},"eventId":{"type":"string","nullable":true},"eventCount":{"type":"number"},"truncated":{"type":"boolean"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/RiskInvestigationEvidenceDto"}},"assessments":{"type":"array","items":{"$ref":"#/components/schemas/RiskInvestigationAssessmentDto"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/RiskInvestigationActionDto"}}},"required":["capturedAt","evidenceRevision","assessmentRevision","eventId","eventCount","truncated","evidence","assessments","actions"]},"RiskInvestigationSourceDto":{"type":"object","properties":{"resource":{"type":"string","enum":["evidence","assessments","actions","events"]},"id":{"type":"string","format":"uuid"}},"required":["resource","id"]},"RiskInvestigationFindingDto":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["rule","comparison_candidate","mock_judgment","ai_judgment"]},"title":{"type":"string"},"detail":{"type":"string"},"outcome":{"type":"string","enum":["attention","uncertain"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/RiskInvestigationSourceDto"}},"suggestedQuestion":{"type":"string"}},"required":["id","kind","title","detail","outcome","sources","suggestedQuestion"]},"RiskInvestigationDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","format":"uuid"},"requestedBy":{"type":"string"},"externalProcessingConfirmedAt":{"type":"string","nullable":true,"format":"date-time"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"provider":{"type":"string"},"questionVersion":{"type":"string"},"snapshot":{"$ref":"#/components/schemas/RiskInvestigationSnapshotDto"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/RiskInvestigationFindingDto"}},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"failure":{"type":"string","nullable":true}},"required":["id","organizationId","sandbox","createdAt","subjectId","requestedBy","externalProcessingConfirmedAt","status","provider","questionVersion","snapshot","findings","completedAt","failure"]},"RiskInvestigationReviewDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","format":"uuid"},"investigationId":{"type":"string","format":"uuid"},"findingId":{"type":"string"},"disposition":{"type":"string","enum":["accepted","dismissed"]},"reason":{"type":"string"},"actor":{"type":"string"}},"required":["id","organizationId","sandbox","createdAt","subjectId","investigationId","findingId","disposition","reason","actor"]},"RiskSubjectDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"kind":{"type":"string"},"externalId":{"type":"string"},"evidenceRevision":{"type":"number"},"assessmentRevision":{"type":"number"}},"required":["id","organizationId","sandbox","createdAt","kind","externalId","evidenceRevision","assessmentRevision"]},"RiskPolicyDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"key":{"type":"string"},"version":{"type":"number"},"definition":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","match","weight","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","aggregation","floor","ceiling","bands","rules","missingEvidence"],"additionalProperties":false}]},"status":{"type":"string","enum":["draft","published"]},"createdBy":{"type":"string"},"publishedBy":{"type":"string","nullable":true},"publishedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","organizationId","sandbox","createdAt","key","version","definition","status","createdBy","publishedBy","publishedAt"]},"RiskEvidenceDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"provenance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskReceiptProvenanceDto"}]},"subjectId":{"type":"string","format":"uuid"},"fact":{"type":"string"},"source":{"type":"string"},"status":{"type":"string","enum":["available","unavailable","revoked"]},"value":{"nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}]},"observedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"providerRef":{"type":"string","nullable":true},"modelProvenance":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskModelProvenanceDto"}]},"revision":{"type":"number"},"supersedesId":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","organizationId","sandbox","createdAt","provenance","subjectId","fact","source","status","value","observedAt","expiresAt","providerRef","modelProvenance","revision","supersedesId"]},"RiskAssessmentDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","format":"uuid"},"policyVersionId":{"type":"string","format":"uuid"},"policyKey":{"type":"string"},"policySnapshot":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","match","weight","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"required":["decision","actions"],"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","aggregation","floor","ceiling","bands","rules","missingEvidence"],"additionalProperties":false}]},"previousId":{"type":"string","nullable":true,"format":"uuid"},"evidenceRevision":{"type":"number"},"sequence":{"type":"number"},"trigger":{"type":"string"},"result":{"$ref":"#/components/schemas/RiskEvaluationDto"},"validUntil":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","organizationId","sandbox","createdAt","subjectId","policyVersionId","policyKey","policySnapshot","previousId","evidenceRevision","sequence","trigger","result","validUntil"]},"RiskOverrideDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","format":"uuid"},"assessmentId":{"type":"string","format":"uuid"},"sequence":{"type":"number"},"decision":{"type":"string","enum":["none","review","restrict","reject"]},"reason":{"type":"string"},"actor":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","organizationId","sandbox","createdAt","subjectId","assessmentId","sequence","decision","reason","actor","expiresAt","revokedAt"]},"RiskActionDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","format":"uuid"},"assessmentId":{"type":"string","format":"uuid"},"key":{"type":"string"},"status":{"type":"string","enum":["requested","acknowledged","completed","failed","cancelled"]},"revision":{"type":"number"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","sandbox","createdAt","subjectId","assessmentId","key","status","revision","updatedAt"]},"RiskEventDataDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"subjectId":{"type":"string","nullable":true,"format":"uuid"},"resourceId":{"type":"string","format":"uuid"},"type":{"type":"string"},"actor":{"type":"string"},"detail":{"type":"object","additionalProperties":true}},"required":["id","organizationId","sandbox","createdAt","subjectId","resourceId","type","actor","detail"]},"RiskRecordDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"resource":{"type":"string","enum":["sources","contexts","subjects","policies","evidence","assessments","overrides","actions","events","investigations","investigation-reviews"]},"data":{"oneOf":[{"$ref":"#/components/schemas/RiskContextDataDto"},{"$ref":"#/components/schemas/RiskSourceDataDto"},{"$ref":"#/components/schemas/RiskInvestigationDataDto"},{"$ref":"#/components/schemas/RiskInvestigationReviewDataDto"},{"$ref":"#/components/schemas/RiskSubjectDataDto"},{"$ref":"#/components/schemas/RiskPolicyDataDto"},{"$ref":"#/components/schemas/RiskEvidenceDataDto"},{"$ref":"#/components/schemas/RiskAssessmentDataDto"},{"$ref":"#/components/schemas/RiskOverrideDataDto"},{"$ref":"#/components/schemas/RiskActionDataDto"},{"$ref":"#/components/schemas/RiskEventDataDto"}],"description":"Typed persisted resource. Use the resource discriminator to select its data schema."}},"required":["id","resource","data"]},"RiskInvestigationStateDto":{"type":"object","properties":{"stale":{"type":"boolean"},"changed":{"type":"boolean"},"expired":{"type":"boolean"}},"required":["stale","changed","expired"]},"ReviewRiskInvestigationDto":{"type":"object","properties":{"findingId":{"type":"string"},"disposition":{"type":"string","enum":["accepted","dismissed"]},"reason":{"type":"string"}},"required":["findingId","disposition","reason"]},"RiskActionQueueItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subjectId":{"type":"string","format":"uuid"},"externalId":{"type":"string"},"subjectKind":{"type":"string"},"assessmentId":{"type":"string","format":"uuid"},"policyKey":{"type":"string"},"key":{"type":"string"},"status":{"type":"string","enum":["requested","acknowledged","failed","completed","cancelled"]},"revision":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","subjectId","externalId","subjectKind","assessmentId","policyKey","key","status","revision","createdAt","updatedAt"]},"RiskActionQueueDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RiskActionQueueItemDto"}},"nextOffset":{"type":"number","nullable":true}},"required":["items","nextOffset"]},"RiskRecordListDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RiskRecordDto"}},"nextOffset":{"type":"number","nullable":true}},"required":["items","nextOffset"]},"RiskAssessmentStateDto":{"type":"object","properties":{"assessment":{"$ref":"#/components/schemas/RiskAssessmentDataDto"},"current":{"type":"boolean"},"activeOverride":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskOverrideDataDto"}]},"effectiveDecision":{"type":"string","enum":["none","review","restrict","reject","awaiting_evidence","reassessment_required"]}},"required":["assessment","current","activeOverride","effectiveDecision"]},"RiskJourneyDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RiskEventDataDto"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]},"RecordRiskActivityDto":{"type":"object","properties":{"activityType":{"type":"string"},"category":{"type":"string","enum":["customer","system","reviewer"],"description":"Caller-reported category, not authenticated actor identity."},"title":{"type":"string"},"summary":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"reference":{"type":"string"}},"required":["activityType","category","title","summary","occurredAt"]},"CreateRiskSubjectDto":{"type":"object","properties":{"kind":{"type":"string","example":"person"},"externalId":{"type":"string"}},"required":["kind","externalId"]},"CreateRiskContextDto":{"type":"object","properties":{"kind":{"type":"string","example":"account_access"},"externalId":{"type":"string"}},"required":["kind","externalId"]},"AddRiskContextSubjectDto":{"type":"object","properties":{"subjectId":{"type":"string","format":"uuid"}},"required":["subjectId"]},"RiskContextSubjectDto":{"type":"object","properties":{"contextId":{"type":"string","format":"uuid"},"subjectId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["contextId","subjectId","organizationId","sandbox","createdBy","createdAt"]},"RiskContextSubjectListDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RiskContextSubjectDto"}},"nextOffset":{"type":"number","nullable":true}},"required":["items","nextOffset"]},"RiskContextPoliciesDto":{"type":"object","properties":{"contextId":{"type":"string","format":"uuid"},"revision":{"type":"number"},"policyVersionIds":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["contextId","revision","policyVersionIds"]},"ConfigureRiskContextPoliciesDto":{"type":"object","properties":{"expectedRevision":{"type":"number","minimum":0,"maximum":2147483646},"policyVersionIds":{"maxItems":20,"description":"Replace all pins with these published policy versions. An empty list clears the configuration.","type":"array","items":{"type":"string"}},"reason":{"type":"string"}},"required":["expectedRevision","policyVersionIds","reason"]},"CreateRiskPolicyDto":{"type":"object","properties":{"key":{"type":"string","example":"customer-onboarding"},"definition":{"allOf":[{"type":"object","properties":{"schemaVersion":{"description":"Policy format version. Omission denotes legacy version 1; unrelated to the published policy revision.","type":"string","const":"1"},"inputs":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"verification":{"type":"object","properties":{"stepType":{"type":"string","pattern":"^[a-z_]{2,30}$"},"transform":{"type":"string","enum":["identity","age_years"]},"workflowDefinitionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"workflowUpdatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"stepIndex":{"type":"integer","minimum":0,"maximum":99},"field":{"type":"string","pattern":"^(?:[a-zA-Z][a-zA-Z0-9_]{0,79}|output\\.[a-zA-Z][a-zA-Z0-9_]{0,39}(?:\\.[a-zA-Z][a-zA-Z0-9_]{0,39}){0,4})$"}},"required":["workflowDefinitionId","workflowUpdatedAt","stepIndex","field"],"additionalProperties":false},"label":{"type":"string","minLength":1,"maxLength":100},"kind":{"type":"string","enum":["text","number","boolean","list","country","choice","money","date","datetime"]},"allowedValues":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"decimalPlaces":{"type":"integer","minimum":0,"maximum":4},"unit":{"type":"string","minLength":1,"maxLength":40},"itemType":{"type":"string","enum":["string","number","boolean"]},"type":{"type":"string","enum":["string","number","boolean","list"]},"evidenceKind":{"type":"string","enum":["observed","model_signal"]},"requirement":{"type":"string","enum":["required","supporting"]},"acceptedSources":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":150}},"maxAgeSeconds":{"type":"integer","minimum":1,"maximum":31536000}},"required":["key","type","acceptedSources","maxAgeSeconds"],"additionalProperties":false}},"applicability":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}}},"required":["id","all"],"additionalProperties":false}},"factors":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"label":{"type":"string","minLength":1,"maxLength":1000},"match":{"default":"first","type":"string","enum":["first","highest"]},"weight":{"default":1,"type":"number","minimum":0,"maximum":100},"defaultPoints":{"type":"number","minimum":0,"maximum":100000},"cases":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"when":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false},"points":{"type":"number","minimum":0,"maximum":100000}},"required":["when","points"],"additionalProperties":false}}},"required":["id","label","cases"],"additionalProperties":false}},"aggregation":{"default":"sum","type":"string","enum":["sum","max"]},"floor":{"default":0,"type":"number","minimum":0,"maximum":10000000},"ceiling":{"default":10000000,"type":"number","minimum":0,"maximum":10000000},"bands":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"min":{"type":"number","minimum":0,"maximum":10000000},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","min","effect"],"additionalProperties":false}},"rules":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"reason":{"type":"string","minLength":1,"maxLength":1000},"all":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"fact":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"operator":{"type":"string","enum":["eq","in","contains","gte","gt","lte","lt","eq_fact","neq_fact"]},"value":{"anyOf":[{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},{"maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]}}]}},"required":["fact","operator","value"],"additionalProperties":false}},"forceBand":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"},"effect":{"type":"object","properties":{"decision":{"default":"none","type":"string","enum":["none","review","restrict","reject"]},"actions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_.-]{0,79}$"}}},"additionalProperties":false}},"required":["id","reason","all","effect"],"additionalProperties":false}},"missingEvidence":{"default":"awaiting_evidence","type":"string","enum":["awaiting_evidence","review"]},"reviewAfterSeconds":{"type":"integer","minimum":60,"maximum":31536000}},"required":["inputs","factors","bands","rules"],"additionalProperties":false}]}},"required":["key","definition"]},"CreateRiskSourceDto":{"type":"object","properties":{"key":{"type":"string"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/RiskSourceFactDto"}},"apiKeyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"scopes":{"description":"Defaults to subject permission only when omitted.","allOf":[{"$ref":"#/components/schemas/RiskSourceScopesDto"}]}},"required":["key","facts","apiKeyIds"]},"UpdateRiskSourceBindingsDto":{"type":"object","properties":{"expectedRevision":{"type":"number"},"apiKeyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"enabled":{"type":"boolean"},"scopes":{"description":"Replace scope permissions. Omission preserves current permissions.","allOf":[{"$ref":"#/components/schemas/RiskSourceScopesDto"}]}},"required":["expectedRevision","apiKeyIds","enabled"]},"AddRiskEvidenceDto":{"type":"object","properties":{"fact":{"type":"string"},"status":{"type":"string","enum":["available","unavailable","revoked"]},"value":{"description":"Typed scalar or scalar list; null only for unavailable/revoked evidence. Validated by the shared risk schema.","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}]},"observedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"providerRef":{"type":"string"},"modelProvenance":{"$ref":"#/components/schemas/RiskModelProvenanceDto"},"sourceRegistrationId":{"type":"string","format":"uuid","description":"Registered evidence source authorized for the submitting API key."}},"required":["fact","status","value","observedAt","sourceRegistrationId"]},"RiskEvidenceItemDto":{"type":"object","properties":{"fact":{"type":"string"},"status":{"type":"string","enum":["available","unavailable","revoked"]},"value":{"description":"Typed scalar or scalar list; null only for unavailable/revoked evidence. Validated by the shared risk schema.","nullable":true,"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}]},"observedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"providerRef":{"type":"string"},"modelProvenance":{"$ref":"#/components/schemas/RiskModelProvenanceDto"}},"required":["fact","status","value","observedAt"]},"AddRiskEvidenceBatchDto":{"type":"object","properties":{"sourceRegistrationId":{"type":"string","format":"uuid","description":"Registered source for every item in this batch."},"items":{"minItems":1,"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/RiskEvidenceItemDto"}}},"required":["sourceRegistrationId","items"]},"RiskEvidenceBatchDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable batch receipt ID, retained on idempotent retries."},"subjectId":{"type":"string","format":"uuid"},"items":{"description":"Immutable evidence receipts in request order.","type":"array","items":{"$ref":"#/components/schemas/RiskRecordDto"}}},"required":["id","subjectId","items"]},"SelectRiskPoliciesDto":{"type":"object","properties":{"policyVersionIds":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string"}},"strategy":{"type":"string","enum":["all","single"]},"trigger":{"type":"string"}},"required":["policyVersionIds","strategy","trigger"]},"RiskMonitoringDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subjectId":{"type":"string","format":"uuid"},"policyVersionId":{"type":"string","format":"uuid"},"policyKey":{"type":"string"},"enabled":{"type":"boolean"},"revision":{"type":"number"},"lastEvaluatedAt":{"type":"string","format":"date-time","nullable":true},"nextCheckAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["id","subjectId","policyVersionId","policyKey","enabled","revision","lastEvaluatedAt","nextCheckAt","lastError"]},"ConfigureRiskMonitoringDto":{"type":"object","properties":{"policyVersionId":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"}},"required":["policyVersionId","enabled"]},"RecordRiskVerificationDecisionDto":{"type":"object","properties":{"sessionWorkflowId":{"type":"string","format":"uuid"},"workflowRunId":{"type":"string","format":"uuid"},"decision":{"type":"string","enum":["approved","rejected","revoked"]},"reason":{"type":"string"}},"required":["sessionWorkflowId","workflowRunId","decision","reason"]},"AssessRiskDto":{"type":"object","properties":{"eventIds":{"maxItems":50,"description":"Existing events for this subject that triggered or contextualize this assessment.","type":"array","items":{"type":"string"}},"policyVersionId":{"type":"string","format":"uuid"},"trigger":{"type":"string"}},"required":["policyVersionId","trigger"]},"ImportRiskCheckDto":{"type":"object","properties":{"checkId":{"type":"string","format":"uuid"}},"required":["checkId"]},"OverrideRiskDto":{"type":"object","properties":{"decision":{"type":"string","enum":["none","review","restrict","reject"]},"reason":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["decision","reason","expiresAt"]},"RiskReasonDto":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"]},"TransitionRiskActionDto":{"type":"object","properties":{"reason":{"type":"string"},"status":{"type":"string","enum":["requested","acknowledged","completed","failed","cancelled"]},"expectedRevision":{"type":"number"}},"required":["reason","status","expectedRevision"]},"ScreeningIdentifierDto":{"type":"object","properties":{"kind":{"type":"string","enum":["passport","national_id","registration_number","wallet"]},"value":{"type":"string","maxLength":128,"description":"As written on the document."},"country":{"type":"string","description":"Issuing country, ISO 3166-1 alpha-2 or alpha-3."}},"required":["kind","value"]},"ScreeningSubjectDto":{"type":"object","properties":{"name":{"type":"string","maxLength":300,"description":"Full name as on the identity document, in any script; at most 12 words."},"aliases":{"maxItems":5,"description":"Other names of the same subject: the name in its own script, a former name.","type":"array","items":{"type":"string"}},"entityType":{"type":"string","enum":["person","entity"],"description":"Unset, a person and a company can both match."},"country":{"type":"string","description":"Country of the document the name comes from (ISO alpha-2 or alpha-3); it decides how a name in another script is read."},"datesOfBirth":{"maxItems":3,"description":"YYYY-MM-DD, YYYY-MM or YYYY.","type":"array","items":{"type":"string"}},"nationalities":{"maxItems":5,"description":"ISO alpha-2 or alpha-3; for a company, its country of registration.","type":"array","items":{"type":"string"}},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningIdentifierDto"}}},"required":["name"]},"CreateScreeningRunDto":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/ScreeningSubjectDto"},"sources":{"type":"array","description":"The lists to screen against, sanctions lists, the PEP list (korala_pep) or both. There is no default: name the lists your obligations require. Each kind is recorded as its own evidence: screening.sanctions and screening.pep.","items":{"type":"string","enum":["eu_fsf","ofac_sdn","ofac_consolidated","uk_sanctions","idb_sanctions","korala_pep"]}},"reviewScore":{"type":"number","minimum":1,"maximum":100,"default":70,"description":"At or above it a candidate is a possible match. Must be below matchScore (the two must differ, so it cannot be 100)."},"matchScore":{"type":"number","minimum":1,"maximum":100,"default":90,"description":"At or above it a candidate is a match. Must be above reviewScore (the two must differ, so it cannot be 1)."},"pepLookbackMonths":{"type":"number","minimum":12,"maximum":240,"default":12,"description":"With the PEP list: how many months after leaving office a person still counts as a PEP. At least 12, the AMLR minimum, which is the default. Refused without a PEP list."},"riskSubjectId":{"type":"string","format":"uuid","description":"A risk subject in this organisation and mode to record the outcome on: screening.sanctions evidence for sanctions lists, screening.pep for the PEP list."}},"required":["subject","sources"]},"ScreeningRunStatus":{"type":"string","enum":["clear","possible_match","match","incomplete","error"]},"ScreeningRunTrigger":{"type":"string","enum":["check_step","api"]},"ScreeningRunSourceDto":{"type":"object","properties":{"key":{"type":"string"},"sourceId":{"type":"string","nullable":true,"format":"uuid"},"versionId":{"type":"string","nullable":true,"format":"uuid","description":"The list version searched; null when there was none."},"publishedAt":{"type":"string","nullable":true,"format":"date-time"},"missing":{"type":"boolean","description":"Not searched: unknown, off, or never loaded."},"droppedEntries":{"type":"number","description":"Entries the list version dropped because its parser could not read them. Any makes the run incomplete."},"droppedTerms":{"type":"number","description":"Terms over 300 characters the searched version did not index, counted over the entries that version indexed itself: those it added or changed, or every listed entry when it rebuilt the list's terms for a new term builder. Terms left out of an entry an earlier version indexed, and this one kept unchanged, are not counted. Recorded only: no name a subject can be screened under is that long."},"termBuilderVersion":{"type":"number","nullable":true,"description":"The term builder that indexed the list version searched: from 3 the index finds names within one letter. Null when the list was not searched; absent on runs recorded before the field was added."},"reindexPending":{"type":"boolean","description":"The version searched was indexed by an older term builder and its index has not been rebuilt yet: names one letter off were not searched on it, and the run is incomplete (source_reindex_pending). Absent on runs recorded before the field was added."},"stale":{"type":"boolean"},"staleReasons":{"type":"array","items":{"type":"string"}},"attention":{"type":"string","nullable":true}},"required":["key","sourceId","versionId","publishedAt","missing","droppedEntries","droppedTerms","stale","staleReasons","attention"]},"ScreeningRunPolicyDto":{"type":"object","properties":{"reviewScore":{"type":"number"},"matchScore":{"type":"number"},"scorerVersion":{"type":"string"},"pepLookbackMonths":{"type":"number","description":"Runs that screened the PEP list: the months after leaving office a person still counted as a PEP."}},"required":["reviewScore","matchScore","scorerVersion"]},"ScreeningRiskSourceDto":{"type":"object","properties":{"fact":{"type":"string","enum":["screening.sanctions","screening.pep"]},"riskSource":{"type":"string","description":"Accept it in a policy input for this fact."}},"required":["fact","riskSource"]},"ScreeningPepPositionDto":{"type":"object","properties":{"category":{"type":"string","description":"legislature, ministers, head_of_state, head_of_government, central_bank, top_court_judges, ambassadors, io (international organisation), local_regional_heads, soe_heads, military_chiefs, party_leaders, ..."},"title":{"type":"string","nullable":true,"description":"The position as the source names it, when it does."},"positionId":{"type":"string","nullable":true,"description":"The Wikidata item of the position, when there is one."},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2; null for an international organisation."},"start":{"type":"string","nullable":true,"description":"YYYY, YYYY-MM or YYYY-MM-DD, as the source states it."},"end":{"type":"string","nullable":true},"current":{"type":"boolean","description":"The source says it is held now."},"source":{"type":"string","nullable":true,"description":"The roster that states it; null for Wikidata."}},"required":["category","title","positionId","country","start","end","current","source"]},"ScreeningRelatedPepDto":{"type":"object","properties":{"sourceEntryId":{"type":"string","description":"The PEP's entry id on the same list."},"name":{"type":"string"},"relation":{"type":"string","description":"What the family member is to the PEP: spouse, child, father, mother or sibling."},"positions":{"description":"The related PEP's positions that make the relative a family member (a sibling: head of state or government, minister or deputy minister only), from which its standing on the day of the run is judged.","type":"array","items":{"$ref":"#/components/schemas/ScreeningPepPositionDto"}}},"required":["sourceEntryId","name","relation"]},"ScreeningMatchPepDto":{"type":"object","properties":{"standing":{"type":"string","enum":["pep","former_pep","family_member","none"],"description":"Where the entry stood on the day of the run: a PEP (in office, or out of office for less than the look-back), a former PEP, a family member of a PEP, or none: a relative whose related PEPs are no longer PEPs (the match and its relation are shown; screening.pep records no family member)."},"flags":{"description":"position_dates_unknown: no position states when it was held, so the person is treated as a PEP.","type":"array","items":{"type":"string"}},"lookbackMonths":{"type":"number"},"lastHeldUntil":{"type":"string","nullable":true,"description":"A former PEP: the latest end date of any position."},"role":{"type":"string","enum":["pep","family_member"]},"categories":{"type":"array","items":{"type":"string"}},"positions":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningPepPositionDto"}},"relatedPeps":{"description":"A family member: the PEPs it is related to.","type":"array","items":{"$ref":"#/components/schemas/ScreeningRelatedPepDto"}},"sources":{"description":"wikidata and the official rosters the entry comes from.","type":"array","items":{"type":"string"}},"wikidataId":{"type":"string","nullable":true}},"required":["standing","flags","lookbackMonths","lastHeldUntil","role","categories","positions","relatedPeps","sources","wikidataId"]},"ScreeningFactorDto":{"type":"object","properties":{"code":{"type":"string"},"points":{"type":"number"},"cap":{"type":"number"},"detail":{"type":"string","description":"About the listed entry."}},"required":["code","points"]},"ScreeningMatchDecision":{"type":"string","enum":["pending","confirmed","false_positive"]},"ScreeningMatchDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"entryId":{"type":"string","format":"uuid"},"source":{"type":"string","description":"The list key."},"listVersionId":{"type":"string","format":"uuid"},"sourceEntryId":{"type":"string","description":"The publisher's own id for the entry."},"entityType":{"type":"string"},"listedName":{"type":"string","description":"The entry’s primary name as listed."},"matchedName":{"type":"string","nullable":true,"description":"The listed name (primary or alias) that matched."},"listedOn":{"type":"string","nullable":true},"programmes":{"description":"Sanctions lists: the programmes. The PEP list: the categories of the positions, or family_member.","type":"array","items":{"type":"string"}},"listKind":{"type":"string","enum":["sanctions","pep"],"description":"The kind of list."},"pep":{"nullable":true,"description":"PEP list matches only.","allOf":[{"$ref":"#/components/schemas/ScreeningMatchPepDto"}]},"score":{"type":"number","minimum":0,"maximum":100},"factors":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningFactorDto"}},"decision":{"allOf":[{"$ref":"#/components/schemas/ScreeningMatchDecision"}]},"decidedBy":{"type":"string","nullable":true},"decidedAt":{"type":"string","nullable":true,"format":"date-time"},"decisionReason":{"type":"string","nullable":true}},"required":["id","entryId","source","listVersionId","sourceEntryId","entityType","listedName","matchedName","listedOn","programmes","listKind","pep","score","factors","decision","decidedBy","decidedAt","decisionReason"]},"ScreeningRunDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunStatus"}]},"incomplete":{"type":"boolean","description":"The screening was not complete (see incompleteReasons). Nothing found in an incomplete run is status incomplete, never clear."},"incompleteReasons":{"type":"array","description":"source_missing, source_stale, source_attention, source_dropped_entries, source_reindex_pending, candidates_capped (the sanctions pool), pep_candidates_capped (the PEP pool), name_terms_capped, name_without_tokens.","items":{"type":"string","enum":["source_missing","source_stale","source_attention","source_dropped_entries","source_reindex_pending","candidates_capped","pep_candidates_capped","name_terms_capped","name_without_tokens"]}},"errorCode":{"type":"string","nullable":true},"trigger":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunTrigger"}]},"sandbox":{"type":"boolean"},"sessionId":{"type":"string","nullable":true,"format":"uuid"},"participantId":{"type":"string","nullable":true,"format":"uuid"},"riskSubjectId":{"type":"string","nullable":true,"format":"uuid"},"workflowRunId":{"type":"string","nullable":true,"format":"uuid"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningRunSourceDto"}},"policy":{"$ref":"#/components/schemas/ScreeningRunPolicyDto"},"listKinds":{"type":"array","description":"The kinds of list screened: sanctions, pep, or both.","items":{"type":"string","enum":["sanctions","pep"]}},"riskSource":{"type":"string","description":"The risk source of the first kind screened (sanctions when screened, otherwise pep); riskSources has each."},"riskSources":{"description":"Each kind of list as the evidence it records: screening.sanctions and screening.pep, each under its own source.","type":"array","items":{"$ref":"#/components/schemas/ScreeningRiskSourceDto"}},"candidateCount":{"type":"number","description":"Listed entries scored, at most 200. Entries whose kind, dates of birth or nationalities keep them below reviewScore are set aside unscored and not counted."},"topScore":{"type":"number","nullable":true,"description":"The highest score of the scored entries, or null when none was scored. Entries set aside as unable to reach review are not in it."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningMatchDto"}}},"required":["id","status","incomplete","incompleteReasons","errorCode","trigger","sandbox","sessionId","participantId","riskSubjectId","workflowRunId","sources","policy","listKinds","riskSource","riskSources","candidateCount","topScore","createdAt","updatedAt","matches"]},"ScreeningRunSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunStatus"}]},"incomplete":{"type":"boolean","description":"The screening was not complete (see incompleteReasons). Nothing found in an incomplete run is status incomplete, never clear."},"incompleteReasons":{"type":"array","description":"source_missing, source_stale, source_attention, source_dropped_entries, source_reindex_pending, candidates_capped (the sanctions pool), pep_candidates_capped (the PEP pool), name_terms_capped, name_without_tokens.","items":{"type":"string","enum":["source_missing","source_stale","source_attention","source_dropped_entries","source_reindex_pending","candidates_capped","pep_candidates_capped","name_terms_capped","name_without_tokens"]}},"errorCode":{"type":"string","nullable":true},"trigger":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunTrigger"}]},"sandbox":{"type":"boolean"},"sessionId":{"type":"string","nullable":true,"format":"uuid"},"participantId":{"type":"string","nullable":true,"format":"uuid"},"riskSubjectId":{"type":"string","nullable":true,"format":"uuid"},"workflowRunId":{"type":"string","nullable":true,"format":"uuid"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningRunSourceDto"}},"policy":{"$ref":"#/components/schemas/ScreeningRunPolicyDto"},"listKinds":{"type":"array","description":"The kinds of list screened: sanctions, pep, or both.","items":{"type":"string","enum":["sanctions","pep"]}},"riskSource":{"type":"string","description":"The risk source of the first kind screened (sanctions when screened, otherwise pep); riskSources has each."},"riskSources":{"description":"Each kind of list as the evidence it records: screening.sanctions and screening.pep, each under its own source.","type":"array","items":{"$ref":"#/components/schemas/ScreeningRiskSourceDto"}},"candidateCount":{"type":"number","description":"Listed entries scored, at most 200. Entries whose kind, dates of birth or nationalities keep them below reviewScore are set aside unscored and not counted."},"topScore":{"type":"number","nullable":true,"description":"The highest score of the scored entries, or null when none was scored. Entries set aside as unable to reach review are not in it."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","incomplete","incompleteReasons","errorCode","trigger","sandbox","sessionId","participantId","riskSubjectId","workflowRunId","sources","policy","listKinds","riskSource","riskSources","candidateCount","topScore","createdAt","updatedAt"]},"PaginatedScreeningRunsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningRunSummaryDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"DecideScreeningMatchDto":{"type":"object","properties":{"decision":{"type":"string","enum":["confirmed","false_positive"]},"reason":{"type":"string","maxLength":2000,"description":"Why, in words. Trimmed; blank or whitespace only is refused."}},"required":["decision","reason"]},"ScreeningListVersionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"publishedAt":{"type":"string","nullable":true,"format":"date-time"},"fetchedAt":{"type":"string","format":"date-time"},"entryCount":{"type":"number"}},"required":["id","publishedAt","fetchedAt","entryCount"]},"ScreeningSourceDto":{"type":"object","properties":{"key":{"type":"string"},"listKind":{"type":"string","enum":["sanctions","pep"]},"name":{"type":"string"},"publisher":{"type":"string"},"licence":{"type":"string"},"attribution":{"type":"string","description":"What a result that used the list credits."},"sourceUrl":{"type":"string"},"active":{"type":"boolean"},"cadenceHours":{"type":"number"},"lastConfirmedAt":{"type":"string","nullable":true,"format":"date-time"},"activeVersion":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ScreeningListVersionDto"}]},"stale":{"type":"boolean"},"staleReasons":{"type":"array","items":{"type":"string"}},"attention":{"type":"string","nullable":true}},"required":["key","listKind","name","publisher","licence","attribution","sourceUrl","active","cadenceHours","lastConfirmedAt","activeVersion","stale","staleReasons","attention"]},"AdverseMediaSubjectDto":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"description":"Full name of the person or company, in any script. It is searched as given and never stored."},"aliases":{"maxItems":1,"description":"One other name of the same subject, typically the name in its own script (Hangul, kana, Han).","type":"array","items":{"type":"string"}},"entityType":{"type":"string","enum":["person","entity"],"default":"person"},"country":{"type":"string","description":"ISO alpha-2 or alpha-3: the subject's country. It chooses the language of the adverse terms and tells the judge which namesakes to rule out."},"birthYear":{"type":"number","minimum":1900,"maximum":2100,"description":"Year of birth (a person) or of founding (a company). Only the judge sees it."},"languages":{"type":"array","maxItems":2,"description":"Languages to search the adverse terms in, instead of the one read from the name's script and the country.","items":{"type":"string","enum":["en","de","fr","es","cs","ja","ko"]}}},"required":["name"]},"CreateAdverseMediaRunDto":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/AdverseMediaSubjectDto"},"riskSubjectId":{"type":"string","format":"uuid","description":"A risk subject in this organisation and mode to record the outcome on, as screening.adverse_media evidence."}},"required":["subject"]},"AdverseMediaRunStatus":{"type":"string","enum":["clear","possible_finding","finding","incomplete","error"],"description":"finding: an open finding about the subject, or a confirmed one. possible_finding: open findings whose subject is unclear. clear: nothing found by a complete run. incomplete: nothing found, but something was not searched or judged. error: nothing could be searched or judged."},"AdverseMediaRunQueryDto":{"type":"object","properties":{"kind":{"type":"string","enum":["name","adverse"],"description":"The name alone, or the name with adverse terms."},"nameIndex":{"type":"number","description":"0 the name, 1 the alias."},"language":{"type":"string","description":"Language of the adverse terms (ISO 639-1)."},"results":{"type":"number"},"failure":{"type":"string","nullable":true,"description":"Why the query failed ('timeout', 'http_429', ...)."}},"required":["kind","nameIndex","language","results","failure"]},"AdverseMediaRunRetrievalDto":{"type":"object","properties":{"provider":{"type":"string","description":"aws_agentcore_web_search, gdelt, or fake (every sandbox run)."},"queries":{"description":"Each query sent; never its text.","type":"array","items":{"$ref":"#/components/schemas/AdverseMediaRunQueryDto"}},"articlesRetrieved":{"type":"number"},"articlesDropped":{"type":"number","description":"Results without a usable http(s) URL."},"articlesUnique":{"type":"number","description":"Distinct articles after de-duplication."}},"required":["provider","queries","articlesRetrieved","articlesDropped","articlesUnique"]},"AdverseMediaRunJudgeDto":{"type":"object","properties":{"provider":{"type":"string","description":"vertex, or fake (every sandbox run)."},"model":{"type":"string","nullable":true,"description":"The model as served; null when no article needed judging or no call answered."},"promptVersion":{"type":"string"},"rulesVersion":{"type":"string"},"articlesJudged":{"type":"number"},"articlesUnjudged":{"type":"number"}},"required":["provider","model","promptVersion","rulesVersion","articlesJudged","articlesUnjudged"]},"AdverseMediaCategory":{"type":"string","enum":["fraud","bribery_corruption","money_laundering","market_abuse","tax_fraud","sanctions_evasion","terrorism_financing","other_crime"]},"AdverseMediaStage":{"type":"string","enum":["allegation","investigation","charge","conviction","sanction"],"description":"How far the matter had gone; null when the article does not say."},"AdverseMediaFindingDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"title":{"type":"string","nullable":true},"publishedAt":{"type":"string","nullable":true,"description":"As the provider gave it: a date or a timestamp."},"snippet":{"type":"string","nullable":true,"description":"At most 280 characters of the provider's text."},"aboutSubject":{"type":"string","enum":["yes","unclear"],"description":"Whether the judge read the article as about this subject. Articles it read as about someone else are not kept."},"category":{"allOf":[{"$ref":"#/components/schemas/AdverseMediaCategory"}]},"stage":{"nullable":true,"description":"How far the matter had gone; null when the article does not say.","allOf":[{"$ref":"#/components/schemas/AdverseMediaStage"}]},"reason":{"type":"string","nullable":true,"description":"The judge's reason, at most 300 characters."},"foundBy":{"description":"The queries that found it: 'name:0', 'adverse:1:ko'.","type":"array","items":{"type":"string"}},"retrievalProvider":{"type":"string"},"judgeModel":{"type":"string"},"promptVersion":{"type":"string"},"decision":{"allOf":[{"$ref":"#/components/schemas/ScreeningMatchDecision"}]},"decidedBy":{"type":"string","nullable":true},"decidedAt":{"type":"string","nullable":true,"format":"date-time"},"decisionReason":{"type":"string","nullable":true}},"required":["id","url","title","publishedAt","snippet","aboutSubject","category","stage","reason","foundBy","retrievalProvider","judgeModel","promptVersion","decision","decidedBy","decidedAt","decisionReason"]},"AdverseMediaRunDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"description":"finding: an open finding about the subject, or a confirmed one. possible_finding: open findings whose subject is unclear. clear: nothing found by a complete run. incomplete: nothing found, but something was not searched or judged. error: nothing could be searched or judged.","allOf":[{"$ref":"#/components/schemas/AdverseMediaRunStatus"}]},"incomplete":{"type":"boolean","description":"Something was not searched or judged. Never a clear result, whatever the status."},"incompleteReasons":{"type":"array","items":{"type":"string","enum":["query_failed","names_capped","queries_capped","articles_capped","judge_failed","judge_output_invalid","deadline_exceeded"]}},"errorCode":{"type":"string","nullable":true,"enum":["missing_name","name_too_long","not_configured","retrieval_failed","judge_failed","concurrency_limited","invalid_config","no_session"]},"trigger":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunTrigger"}]},"sandbox":{"type":"boolean"},"simulated":{"type":"boolean","description":"The fake provider and judge answered: nothing was sent to a search API or a model. Every test-mode run is simulated."},"sessionId":{"type":"string","nullable":true,"format":"uuid"},"participantId":{"type":"string","nullable":true,"format":"uuid"},"riskSubjectId":{"type":"string","nullable":true,"format":"uuid"},"workflowRunId":{"type":"string","nullable":true,"format":"uuid"},"retrieval":{"$ref":"#/components/schemas/AdverseMediaRunRetrievalDto"},"judge":{"$ref":"#/components/schemas/AdverseMediaRunJudgeDto"},"riskFact":{"type":"string","description":"screening.adverse_media"},"riskSource":{"type":"string","description":"The risk source its evidence is recorded under: korala:screening:adverse_media:v1."},"findingCount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/AdverseMediaFindingDto"}}},"required":["id","status","incomplete","incompleteReasons","errorCode","trigger","sandbox","simulated","sessionId","participantId","riskSubjectId","workflowRunId","retrieval","judge","riskFact","riskSource","findingCount","createdAt","updatedAt","findings"]},"AdverseMediaRunSummaryDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"description":"finding: an open finding about the subject, or a confirmed one. possible_finding: open findings whose subject is unclear. clear: nothing found by a complete run. incomplete: nothing found, but something was not searched or judged. error: nothing could be searched or judged.","allOf":[{"$ref":"#/components/schemas/AdverseMediaRunStatus"}]},"incomplete":{"type":"boolean","description":"Something was not searched or judged. Never a clear result, whatever the status."},"incompleteReasons":{"type":"array","items":{"type":"string","enum":["query_failed","names_capped","queries_capped","articles_capped","judge_failed","judge_output_invalid","deadline_exceeded"]}},"errorCode":{"type":"string","nullable":true,"enum":["missing_name","name_too_long","not_configured","retrieval_failed","judge_failed","concurrency_limited","invalid_config","no_session"]},"trigger":{"allOf":[{"$ref":"#/components/schemas/ScreeningRunTrigger"}]},"sandbox":{"type":"boolean"},"simulated":{"type":"boolean","description":"The fake provider and judge answered: nothing was sent to a search API or a model. Every test-mode run is simulated."},"sessionId":{"type":"string","nullable":true,"format":"uuid"},"participantId":{"type":"string","nullable":true,"format":"uuid"},"riskSubjectId":{"type":"string","nullable":true,"format":"uuid"},"workflowRunId":{"type":"string","nullable":true,"format":"uuid"},"retrieval":{"$ref":"#/components/schemas/AdverseMediaRunRetrievalDto"},"judge":{"$ref":"#/components/schemas/AdverseMediaRunJudgeDto"},"riskFact":{"type":"string","description":"screening.adverse_media"},"riskSource":{"type":"string","description":"The risk source its evidence is recorded under: korala:screening:adverse_media:v1."},"findingCount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","incomplete","incompleteReasons","errorCode","trigger","sandbox","simulated","sessionId","participantId","riskSubjectId","workflowRunId","retrieval","judge","riskFact","riskSource","findingCount","createdAt","updatedAt"]},"PaginatedAdverseMediaRunsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdverseMediaRunSummaryDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"DecideAdverseMediaFindingDto":{"type":"object","properties":{"decision":{"type":"string","enum":["confirmed","false_positive"],"description":"confirmed: the article is about this subject and adverse. false_positive: it is not (another person, or nothing adverse)."},"reason":{"type":"string","maxLength":2000,"description":"Why, in words. Trimmed; blank or whitespace only is refused."}},"required":["decision","reason"]},"CatalogFormSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string","example":"irs-w9"},"title":{"type":"string"},"jurisdiction":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"publishedRevision":{"type":"string","description":"The published version currently available for cloning"},"publishedVersionId":{"type":"string","description":"ID of the published version to clone from"},"fieldCount":{"type":"number","description":"Fields mapped on the published version."},"signerRoleCount":{"type":"number","description":"Signer roles the published version defines."},"sourceUrl":{"type":"string","nullable":true,"example":"https://www.irs.gov/pub/irs-pdf/fw9.pdf","description":"The publisher's own URL this version's PDF was taken from. Every version published from now on records one, so this is null only for a form published before provenance became a publish requirement."},"sourceSha256":{"type":"string","nullable":true,"description":"SHA-256 of the exact PDF bytes Korala ships for this version. Download the form from sourceUrl, hash it, and compare to verify the catalog against its government source."}},"required":["id","slug","title","publishedRevision","publishedVersionId","fieldCount","signerRoleCount"]},"FieldType":{"type":"string","enum":["signature","initials","date","text","checkbox","dropdown","radio"]},"CatalogFormFieldDto":{"type":"object","properties":{"canonicalName":{"type":"string","example":"us_taxpayer_id","description":"Merge-field name on the cloned template. This is the name you set values against."},"label":{"type":"string","example":"U.S. taxpayer identification number (required)"},"signerRole":{"type":"string","example":"Beneficial Owner","description":"Which signer role fills this field"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number","description":"1-based page of the form"},"required":{"type":"boolean"},"options":{"description":"Dropdown fields only: the accepted values","type":"array","items":{"type":"string"}},"groupKey":{"type":"string","description":"Checkboxes that answer one question together, e.g. the thirteen entity-type boxes on a W-8. Set at most one per group."},"groupRequired":{"type":"boolean","description":"True when the group needs exactly one box set"},"maxLength":{"type":"number","description":"Character limit the field enforces, usually a comb field with one printed box per character"},"inputMask":{"type":"string","example":"###-##-####","description":"Input mask where # represents one digit"},"validationPattern":{"type":"string","example":"^\\d{2}-?\\d{7}$|^\\d{3}-?\\d{2}-?\\d{4}$","description":"Regex the value must match. Validate against it before you send, rather than finding out when a signer is stuck on the form."},"validationMessage":{"type":"string","example":"Enter a 9-digit SSN, ITIN, or EIN","description":"What the signer is told when validationPattern rejects"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: the format the form prints beside its date boxes, and the format the field auto-fills in"}},"required":["canonicalName","label","signerRole","fieldType","pageNumber","required"]},"CatalogFormFieldsDto":{"type":"object","properties":{"versionId":{"type":"string","description":"ID of the version these fields belong to"},"revision":{"type":"string","example":"Rev. October 2021"},"signerRoles":{"example":["Beneficial Owner"],"description":"Signer roles the clone will create, in order","type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFormFieldDto"}}},"required":["versionId","revision","signerRoles","fields"]},"CreateTemplateFromCatalogDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"name":{"type":"string","example":"W-9 for Acme investors","description":"Name for the created template (defaults to the form title)"}}},"MarkdownTemplateSourceDto":{"type":"object","properties":{"source":{"type":"string"},"sampleData":{"type":"object","additionalProperties":true},"revision":{"type":"number"},"formatVersion":{"type":"number","enum":[1]},"pageSize":{"type":"string","enum":["A4","Letter"]},"pageCount":{"type":"number","description":"Pages the source renders to with its sample data, as of the last save. Absent on templates saved before this was recorded."}},"required":["source","sampleData","revision","formatVersion","pageSize"]},"GoogleProvenanceDto":{"type":"object","properties":{"fileId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"mimeType":{"type":"string"},"driveVersion":{"type":"string"},"docsRevision":{"type":"string"},"tabCount":{"type":"number"},"skipEmptyPages":{"type":"boolean","description":"Whether conversion suppresses automatic blank parity pages. Absent on older imports, which retain their original pagination."},"fetchedAt":{"type":"string"},"locallyReplacedAt":{"type":"string","description":"First local file replacement. When present, this provenance describes the original import, not the current template file. Google variable validation no longer applies; the saved pagination policy is retained."},"sourceSha256":{"type":"string","description":"SHA-256 of the stored source, after DOCX ZIP normalization."},"providerSourceSha256":{"type":"string","description":"SHA-256 of the original bytes downloaded from Google."},"pdfSha256":{"type":"string"},"dialect":{"type":"string","enum":["korala-simple-v1"]}},"required":["fileId","name","url","mimeType","driveVersion","fetchedAt","sourceSha256","pdfSha256","dialect"]},"TemplateType":{"type":"string","enum":["pdf","docx","markdown"]},"DetectedMergeFieldDto":{"type":"object","properties":{"name":{"type":"string","example":"client_name"},"occurrences":{"type":"number","example":3}},"required":["name","occurrences"]},"TemplateDto":{"type":"object","properties":{"collectionIds":{"description":"Collection memberships; omitted on lists unless includeCollections=true.","type":"array","items":{"type":"string","format":"uuid"}},"markdown":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarkdownTemplateSourceDto"}]},"googleSource":{"description":"Original Google import provenance, available on detail responses.","allOf":[{"$ref":"#/components/schemas/GoogleProvenanceDto"}]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"templateType":{"default":"pdf","allOf":[{"$ref":"#/components/schemas/TemplateType"}]},"baseFileUrl":{"type":"string"},"isActive":{"type":"boolean"},"sandbox":{"type":"boolean","description":"Created with a test-mode API key (sandbox template)"},"formFieldsDetected":{"type":"number","nullable":true,"example":23,"description":"How many interactive form fields the base PDF ships with, counted when the upload was confirmed. 0 for a flat PDF, null when the file was never scanned."},"autoImportFormFields":{"type":"boolean","description":"Whether those embedded fields were placed as template fields automatically when the upload was confirmed."},"detectedMergeFields":{"nullable":true,"description":"Auto-detected input fields from DOCX or Markdown (null for PDF templates)","type":"array","items":{"$ref":"#/components/schemas/DetectedMergeFieldDto"}},"catalogFormSlug":{"type":"string","nullable":true,"description":"Standard Forms catalog slug this was cloned from, e.g. \"irs-w9\" (null for uploaded templates)"},"catalogFormTitle":{"type":"string","nullable":true,"description":"Catalog form title at clone time, e.g. \"IRS Form W-9 …\""},"catalogRevision":{"type":"string","nullable":true,"description":"Catalog form revision at clone time, e.g. \"Rev. March 2024\""},"catalogVersionId":{"type":"string","nullable":true,"description":"ID of the catalog form version this was cloned from"},"fieldCount":{"type":"number","description":"Fields the template places. On template lists only."},"signerRoleCount":{"type":"number","description":"Signer roles the template defines. On template lists only."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","templateType","baseFileUrl","isActive","sandbox","autoImportFormFields","createdAt","updatedAt"]},"MarkdownSourceDto":{"type":"object","properties":{"source":{"type":"string","description":"Markdown with the supported Liquid variable, if/unless and for syntax."},"sampleData":{"type":"object","additionalProperties":true,"description":"Example JSON for previews. Never implicitly fills a generated agreement."},"pageSize":{"type":"string","enum":["A4","Letter"],"default":"A4"}},"required":["source"]},"MarkdownSignatureDto":{"type":"object","properties":{"role":{"type":"string"},"label":{"type":"string"},"fieldType":{"description":"What the signer fills in: signature from ::signature, everything else from ::field. A ::field radio arrives as one radio per choice sharing a groupKey.","allOf":[{"$ref":"#/components/schemas/FieldType"}]},"required":{"type":"boolean"},"options":{"description":"A dropdown's choices, in order.","type":"array","items":{"type":"string"}},"groupKey":{"type":"string","description":"Shared by a radio's choices: one of them is picked."},"groupRequired":{"type":"boolean","description":"Whether the signer must pick one in that group."},"signingDate":{"type":"boolean","description":"A date filled with the date of signing: signingDate=\"true\", or a date inside a :::signatures block that does not say otherwise."},"pageNumber":{"type":"number"},"xPosition":{"type":"number"},"yPosition":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"required":["role","label","fieldType","required","pageNumber","xPosition","yPosition","width","height"]},"MarkdownPreviewDto":{"type":"object","properties":{"pdfBase64":{"type":"string","description":"Base64 encoded PDF. Preview does not save a template or send a document."},"pageCount":{"type":"number"},"mergeFields":{"type":"array","items":{"$ref":"#/components/schemas/DetectedMergeFieldDto"}},"signatures":{"description":"Every field a signer fills in, in source order: each ::signature, and each ::field (dates, text, initials, checkboxes, dropdowns, radios).","type":"array","items":{"$ref":"#/components/schemas/MarkdownSignatureDto"}}},"required":["pdfBase64","pageCount","mergeFields","signatures"]},"CreateMarkdownTemplateDto":{"type":"object","properties":{"source":{"type":"string","description":"Markdown with the supported Liquid variable, if/unless and for syntax."},"sampleData":{"type":"object","additionalProperties":true,"description":"Example JSON for previews. Never implicitly fills a generated agreement."},"pageSize":{"type":"string","enum":["A4","Letter"],"default":"A4"},"name":{"type":"string","example":"Consulting agreement"},"description":{"type":"string"}},"required":["source","name"]},"UpdateMarkdownTemplateDto":{"type":"object","properties":{"source":{"type":"string","description":"Markdown with the supported Liquid variable, if/unless and for syntax."},"sampleData":{"type":"object","additionalProperties":true,"description":"Example JSON for previews. Never implicitly fills a generated agreement."},"pageSize":{"type":"string","enum":["A4","Letter"],"default":"A4"},"name":{"type":"string","example":"Consulting agreement"},"description":{"type":"string"},"revision":{"type":"number","description":"Current source revision. A stale revision returns 409 instead of overwriting newer changes."}},"required":["source","name","revision"]},"CreateTemplateUploadUrlDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"filename":{"type":"string","example":"contract-template.pdf"},"contentType":{"type":"string","example":"application/pdf","description":"MIME type of the file. Supported: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document"}},"required":["filename","contentType"]},"TemplateUploadUrlResponseDto":{"type":"object","properties":{"templateId":{"type":"string"},"uploadUrl":{"type":"string"},"key":{"type":"string"},"maxUploadBytes":{"type":"number","example":26214400,"description":"Largest file this organization's plan accepts, in bytes. Uploading a bigger file is rejected when the upload is confirmed, so check it before transferring."}},"required":["templateId","uploadUrl","key","maxUploadBytes"]},"CreateTemplateDto":{"type":"object","properties":{"name":{"type":"string","example":"NDA Template"},"description":{"type":"string","example":"Standard non-disclosure agreement"},"autoImportFormFields":{"type":"boolean","description":"When the base PDF is a fillable form, its embedded fields are placed as template fields automatically — same positions, types, character limits and font sizes the form declares — and assigned to the template's first signer role (one named \"Signer\" is created when the template has none). Defaults to false for templates created with an API key (integrations provision their own roles and fields) and true for templates created from the dashboard; pass a value to override either way."}},"required":["name"]},"ReplaceTemplateFileDto":{"type":"object","properties":{"filename":{"type":"string","example":"updated-contract.pdf"},"contentType":{"type":"string","example":"application/pdf","description":"MIME type of the file. Supported: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document"}},"required":["filename","contentType"]},"ReplaceTemplateFileResponseDto":{"type":"object","properties":{"uploadUrl":{"type":"string"},"key":{"type":"string"}},"required":["uploadUrl","key"]},"ConfirmReplaceTemplateFileDto":{"type":"object","properties":{"key":{"type":"string","description":"Storage key returned from replace-file endpoint"}},"required":["key"]},"DuplicateTemplateDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Mode for the copy. Defaults to the mode of the calling key, so duplicating a sandbox template from the dashboard produces a live one. A test-mode API key cannot set this to false."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"name":{"type":"string","example":"IRS Form W-8BEN-E (production)","description":"Name for the copy. Defaults to the source name plus ' (copy)'."}}},"TemplateSortBy":{"type":"string","enum":["createdAt","name","status"]},"SortOrder":{"type":"string","enum":["asc","desc"]},"PaginatedTemplatesDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateDto"}},"total":{"type":"number","description":"Total number of templates"},"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["data","total","page","limit","totalPages"]},"TemplateSignerRoleDto":{"type":"object","properties":{"id":{"type":"string"},"templateId":{"type":"string"},"name":{"type":"string"},"signingOrder":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","templateId","name","signingOrder","createdAt","updatedAt"]},"FieldPlacement":{"type":"string","enum":["coordinate","anchor","bookmark"]},"TextAlign":{"type":"string","enum":["left","center","right"],"description":"Horizontal alignment of the value inside the field box"},"AnchorPosition":{"type":"string","enum":["replace","left","right","above","below"]},"TemplateFieldDto":{"type":"object","properties":{"id":{"type":"string"},"templateId":{"type":"string"},"signerRoleId":{"type":"string","nullable":true},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"placement":{"allOf":[{"$ref":"#/components/schemas/FieldPlacement"}]},"pageNumber":{"type":"number","description":"1-based page number, or -1 for last page."},"xPosition":{"type":"number","nullable":true},"yPosition":{"type":"number","nullable":true},"width":{"type":"number"},"height":{"type":"number"},"required":{"type":"boolean"},"mergeFieldName":{"type":"string","nullable":true},"defaultValue":{"type":"string","nullable":true},"editable":{"type":"boolean","description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","description":"One signer role owns the generated field, but until that signer signs any signer able to act may fill or correct it. Never true on signature or initials fields."},"signingDate":{"type":"boolean","nullable":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Null on a date made before the flag existed: a date on the signer’s own signature line is then the date of signing."},"label":{"type":"string","nullable":true,"description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","nullable":true,"description":"Embedded AcroForm field this field is linked to; generated document fields inherit the link."},"acroOptionValue":{"type":"string","nullable":true,"description":"For radio-group AcroForm fields: the option this field selects."},"options":{"nullable":true,"description":"Allowed values for dropdown fields","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","nullable":true,"description":"Maximum characters accepted at fill time"},"inputMask":{"type":"string","example":"###-##-####","nullable":true,"description":"Input mask where # represents one digit"},"validationPattern":{"type":"string","nullable":true,"description":"Regex the filled value must match"},"validationMessage":{"type":"string","nullable":true,"description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","nullable":true,"description":"Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'"},"fontSize":{"type":"number","nullable":true,"example":9,"description":"Point size the value is drawn at, copied onto generated document fields. Null fits the size to the box."},"textColor":{"type":"string","nullable":true,"example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"nullable":true,"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","nullable":true,"example":"Helvetica-Bold","description":"Base font the value is drawn in, copied onto generated document fields"},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks (a multiline form field)"},"groupKey":{"type":"string","nullable":true},"groupRequired":{"type":"boolean","description":"Whether at least one member of this group must be selected"},"requiredWhenFieldId":{"type":"string","nullable":true,"format":"uuid","description":"Id of the template field whose checked/filled state makes this field required on generated documents; null when unconditional"},"requiredWhenValue":{"type":"string","nullable":true,"description":"Exact controller value the condition triggers on; null means any checked/filled state"},"anchorText":{"type":"string","nullable":true},"anchorPosition":{"allOf":[{"$ref":"#/components/schemas/AnchorPosition"}]},"anchorOffsetX":{"type":"number"},"anchorOffsetY":{"type":"number"},"hideAnchor":{"type":"boolean"},"anchorMatchWholeWord":{"type":"boolean"},"bookmarkName":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","templateId","fieldType","placement","pageNumber","width","height","required","editable","sharedFill","multiline","groupRequired","anchorPosition","anchorOffsetX","anchorOffsetY","hideAnchor","anchorMatchWholeWord","createdAt","updatedAt"]},"TemplateWithDetailsDto":{"type":"object","properties":{"collectionIds":{"description":"Collection memberships; omitted on lists unless includeCollections=true.","type":"array","items":{"type":"string","format":"uuid"}},"markdown":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarkdownTemplateSourceDto"}]},"googleSource":{"description":"Original Google import provenance, available on detail responses.","allOf":[{"$ref":"#/components/schemas/GoogleProvenanceDto"}]},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"templateType":{"default":"pdf","allOf":[{"$ref":"#/components/schemas/TemplateType"}]},"baseFileUrl":{"type":"string"},"isActive":{"type":"boolean"},"sandbox":{"type":"boolean","description":"Created with a test-mode API key (sandbox template)"},"formFieldsDetected":{"type":"number","nullable":true,"example":23,"description":"How many interactive form fields the base PDF ships with, counted when the upload was confirmed. 0 for a flat PDF, null when the file was never scanned."},"autoImportFormFields":{"type":"boolean","description":"Whether those embedded fields were placed as template fields automatically when the upload was confirmed."},"detectedMergeFields":{"nullable":true,"description":"Auto-detected input fields from DOCX or Markdown (null for PDF templates)","type":"array","items":{"$ref":"#/components/schemas/DetectedMergeFieldDto"}},"catalogFormSlug":{"type":"string","nullable":true,"description":"Standard Forms catalog slug this was cloned from, e.g. \"irs-w9\" (null for uploaded templates)"},"catalogFormTitle":{"type":"string","nullable":true,"description":"Catalog form title at clone time, e.g. \"IRS Form W-9 …\""},"catalogRevision":{"type":"string","nullable":true,"description":"Catalog form revision at clone time, e.g. \"Rev. March 2024\""},"catalogVersionId":{"type":"string","nullable":true,"description":"ID of the catalog form version this was cloned from"},"fieldCount":{"type":"number","description":"Fields the template places. On template lists only."},"signerRoleCount":{"type":"number","description":"Signer roles the template defines. On template lists only."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"signerRoles":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSignerRoleDto"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFieldDto"}}},"required":["id","name","templateType","baseFileUrl","isActive","sandbox","autoImportFormFields","createdAt","updatedAt","signerRoles","fields"]},"UpdateTemplateDto":{"type":"object","properties":{"name":{"type":"string","example":"NDA Template v2"},"description":{"type":"string","example":"Updated non-disclosure agreement"},"isActive":{"type":"boolean","example":true},"sandbox":{"type":"boolean","example":false,"description":"Relabel the template as sandbox (test) or live. Useful for templates created before the flag existed. A test-mode API key can only set this to true."}}},"CreateSignerRoleDto":{"type":"object","properties":{"name":{"type":"string","example":"Client"},"signingOrder":{"type":"number","example":1}},"required":["name"]},"UpdateSignerRoleDto":{"type":"object","properties":{"name":{"type":"string","example":"Approver"},"signingOrder":{"type":"number","example":2}}},"CreateTemplateFieldDto":{"type":"object","properties":{"signerRoleId":{"type":"string","description":"Signer role ID (optional for non-signing fields)"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"placement":{"default":"coordinate","description":"How the field is positioned. \"coordinate\" uses absolute x/y/page (correct for fixed-layout PDFs). \"anchor\" locates anchorText in the rendered document and positions the field per generation (reflow-proof, recommended for DOCX).","allOf":[{"$ref":"#/components/schemas/FieldPlacement"}]},"pageNumber":{"type":"number","example":1,"description":"1-based page number (coordinate mode). Use -1 for the last page. Ignored for anchor placement."},"xPosition":{"type":"number","example":100,"description":"Required for coordinate placement; ignored for anchor."},"yPosition":{"type":"number","example":200,"description":"Required for coordinate placement; ignored for anchor."},"width":{"type":"number","example":200,"description":"Field box width in points. Korala fits a signature image inside the box, preserving its aspect ratio, then centres it, so a wide box scales the signature by width and leaves vertical padding. The box bounds the ink; it does not size it."},"height":{"type":"number","example":50,"description":"Field box height in points. Text, date and dropdown values render left-aligned with 4pt padding, centred against the box height, at min(12, height * 0.6) points."},"required":{"type":"boolean","example":true},"mergeFieldName":{"type":"string","example":"client_name"},"defaultValue":{"type":"string","example":"Default value"},"editable":{"type":"boolean","example":false,"description":"Treat a value resolved from variables or defaultValue as a suggestion: the generated field stays unfilled and the signer can change the value before signing. Applies to text, date, and checkbox fields."},"sharedFill":{"type":"boolean","example":false,"description":"One signer role owns the generated field, but until that signer signs any signer able to act may fill or correct it. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Copied onto every document made from the template."},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified name of an embedded AcroForm field in the base PDF (see GET /templates/{id}/form-fields). When set, generated document fields inherit the link and values are written through the PDF form field at completion — comb boxes, checkboxes, and length limits render natively — instead of being overlay-stamped."},"acroOptionValue":{"type":"string","example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Copied onto generated document fields."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at, copied onto generated document fields. Imported automatically from the base PDF's form fields; omit to fit the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in, copied onto generated document fields. Imported from the base PDF's form fields; honored when the platform can render that face, otherwise the default font is used."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields and copied onto generated document fields."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","format":"uuid","description":"Make this field conditionally required: on generated documents it must be filled before signing only while the referenced template field (same template, same signer role) is checked/filled — e.g. a W-9 LLC tax-classification code required only when the LLC box is checked. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","example":"Other","description":"Narrow the condition to an exact value of the referenced field. Omit to trigger on any checked/filled state."},"anchorText":{"type":"string","example":"Fund Lead Signature:","description":"Literal string to locate in the rendered document for anchor placement. A field is placed at EVERY occurrence. Required when placement is \"anchor\". Must not contain {{ }} (reserved for merge fields). Hiding a marker (white text, or hideAnchor) leaves it in the PDF text layer, where it survives into the signed document. Anchor on text that already belongs in the document when the output must carry no implementation markers."},"anchorPosition":{"default":"replace","description":"Where the field sits relative to each anchor match. The reference is the match's glyph bounding box (font ascent to descent), not its baseline: \"above\" places the field bottom against the box top, \"below\" the field top against the box bottom, \"left\"/\"right\" against its side edges. Anchoring above a ruled underscore line therefore starts about one ascender above the visible rule — correct with anchorOffsetY.","allOf":[{"$ref":"#/components/schemas/AnchorPosition"}]},"anchorOffsetX":{"type":"number","example":0,"description":"Horizontal offset in points applied after anchor resolution. Positive moves the field right, negative left."},"anchorOffsetY":{"type":"number","example":0,"description":"Vertical offset in points applied after anchor resolution. Coordinates are top-left origin, so positive moves the field DOWN the page and negative moves it UP."},"hideAnchor":{"type":"boolean","example":false,"description":"Draw a white rectangle over each visible anchor marker after resolving it (use when the anchor text is not already invisible). This hides the marker without removing it: the anchor string stays in the PDF text layer, where pdftotext, copy-paste, search and indexing still surface it in the signed document."},"anchorMatchWholeWord":{"type":"boolean","example":false,"description":"Match anchorText only at word boundaries. Off by default, because matching has always been a plain substring search and tightening it would silently drop fields that resolve today. Turn it on for short anchors: \"By:\" otherwise also matches inside \"Standby:\"."},"bookmarkName":{"type":"string","example":"SigSeller","description":"Word bookmark whose position locates this field. Required when placement is \"bookmark\", and DOCX templates only. A bookmark carries a position without carrying text, so unlike an anchor it leaves nothing in the PDF text layer, and Word keeps names unique so it always resolves to exactly one position. Use letters, digits and hyphens: the converter rewrites every other character to a hex code, so \"Sig_Seller\" is stored as \"Sig5FSeller\" and could collide with a bookmark of that literal name."}},"required":["fieldType","width","height"]},"TemplateBookmarkDto":{"type":"object","properties":{"name":{"type":"string","example":"SigSeller","description":"Bookmark name as it appears in the rendered PDF. A name containing anything other than letters, digits or hyphens is shown in the converter's rewritten form, e.g. Sig_Seller appears as Sig5FSeller."},"pageNumber":{"type":"number","example":1,"description":"1-based page number."},"x":{"type":"number","description":"Distance from the page left edge, in points."},"y":{"type":"number","description":"Distance from the page top edge, in points."}},"required":["name","pageNumber","x","y"]},"AmbiguousBookmarkDto":{"type":"object","properties":{"key":{"type":"string","example":"Sig5FSeller","description":"The single destination key these names collapse onto."},"names":{"example":["Sig_Seller","Sig5FSeller"],"description":"Bookmark names in the document that share that key.","type":"array","items":{"type":"string"}}},"required":["key","names"]},"TemplateBookmarksDto":{"type":"object","properties":{"bookmarks":{"description":"Named destinations in the template rendered as authored, with merge tokens left unsubstituted. Use it to confirm a bookmark name exists and to see the form the converter rewrote it to. The coordinates are from that unmerged layout, so a generated document places the field wherever the bookmark lands once real values have reflowed the page.","type":"array","items":{"$ref":"#/components/schemas/TemplateBookmarkDto"}},"ambiguous":{"description":"Bookmark names that collapse onto one destination once the converter rewrites them. Only one of each group survives, so a field bound to any of them resolves to whichever position won. Rename them to use only letters, digits and hyphens.","type":"array","items":{"$ref":"#/components/schemas/AmbiguousBookmarkDto"}},"missing":{"example":["_Ref418700706"],"description":"Bookmark names declared in the DOCX that reached no destination in the rendered document. A field bound to one of these places nothing, and the bookmark list alone would look healthy, so treat a name of your own appearing here as a template setup failure. The most common cause is a bookmark placed after a Word field code (a REF cross-reference, a PAGE number) in the same paragraph: the converter drops it. Move the bookmark before the field. Empty for PDF templates, which have no DOCX to compare against.","type":"array","items":{"type":"string"}}},"required":["bookmarks","ambiguous","missing"]},"AcroFormFieldDto":{"type":"object","properties":{"name":{"type":"string","example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified AcroForm field name (unique per field)"},"kind":{"type":"string","enum":["text","checkbox","radio","dropdown","signature"],"description":"Kind of embedded form field"},"pageNumber":{"type":"number","example":1,"description":"1-based page number"},"xPosition":{"type":"number","example":59,"description":"PDF points from the left edge (top-left origin)"},"yPosition":{"type":"number","example":118,"description":"PDF points from the top edge (top-left origin)"},"width":{"type":"number","example":517},"height":{"type":"number","example":14},"maxLength":{"type":"number","example":9,"description":"Maximum characters the form field accepts (comb/character boxes)"},"multiline":{"type":"boolean","description":"Whether the text field is multiline"},"comb":{"type":"boolean","description":"Comb field: characters sit in `maxLength` equally spaced cells"},"label":{"type":"string","example":"Employee's social security number","description":"The form author's tooltip (/TU) for this field — its human-readable label"},"required":{"type":"boolean","description":"Whether the form itself marks this field as required"},"readOnly":{"type":"boolean","description":"Read-only fields are computed or locked by the form and are never imported as signer-fillable fields"},"fontSize":{"type":"number","example":9,"description":"Point size from the field default appearance (/DA); absent when the form auto-sizes the text"},"fontFamily":{"type":"string","example":"Helvetica","description":"Base font the form draws this field with"},"textColor":{"type":"string","example":"#000080","description":"Text color from the field default appearance, as #rrggbb"},"alignment":{"description":"Horizontal alignment from the field's quadding (/Q)","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"optionValue":{"type":"string","example":"married","description":"For radio groups (one entry per option): the option export value"},"options":{"example":["CA","NY"],"description":"For dropdowns/list boxes: the allowed values","type":"array","items":{"type":"string"}},"currentValue":{"type":"string","description":"Value already present in the PDF ('checked' for checked boxes)"}},"required":["name","kind","pageNumber","xPosition","yPosition","width","height"]},"TemplateFormFieldPartyDto":{"type":"object","properties":{"key":{"type":"string","example":"landlord"},"name":{"type":"string","example":"Landlord"},"evidence":{"type":"string","example":"9 fields on page 2 name the landlord"},"pages":{"example":[2],"type":"array","items":{"type":"number"}},"fieldCount":{"type":"number","example":9},"source":{"type":"string","enum":["named","layout"],"description":"How the split was arrived at. \"named\" means the form names this party itself — an employer, a tenant — and the fields are its section. \"layout\" means it does not, or not in a language we read, so the form was cut along its widest visible breaks into as many parts as there are signers: unlabelled, and offered for the sender to assign rather than proposed as fact."},"signerRoleIds":{"type":"array","items":{"type":"string"}},"fieldIds":{"description":"Ids of this party's fields, for highlighting them while the sender decides which role fills the section.","type":"array","items":{"type":"string"}}},"required":["key","name","evidence","pages","fieldCount","source","signerRoleIds","fieldIds"]},"AssignTemplateFormFieldPartyDto":{"type":"object","properties":{"party":{"type":"string","example":"landlord"},"signerRoleId":{"type":"string","description":"Role that fills this party's fields"}},"required":["party","signerRoleId"]},"AssignTemplateFormFieldPartiesDto":{"type":"object","properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/AssignTemplateFormFieldPartyDto"}}},"required":["assignments"]},"ImportTemplateFormFieldsDto":{"type":"object","properties":{"signerRoleId":{"type":"string","description":"Signer role the imported fields are assigned to. Defaults to the template's first role, creating a default \"Signer\" role when it has none — an unassigned template field places nothing at generation."},"replaceExisting":{"type":"boolean","default":false,"description":"Delete the template's existing fields before importing, so the import is the whole field set. Without it, existing fields are kept and only form fields that are not placed yet are added, so repeating the call places nothing new."}}},"UpdateTemplateFieldDto":{"type":"object","properties":{"signerRoleId":{"type":"string","description":"Signer role ID (set to null to unassign, omit to keep unchanged)","nullable":true},"placement":{"allOf":[{"$ref":"#/components/schemas/FieldPlacement"}]},"pageNumber":{"type":"number","example":1,"description":"1-based page number, or -1 for the last page."},"xPosition":{"type":"number","example":100},"yPosition":{"type":"number","example":200},"width":{"type":"number","example":200},"height":{"type":"number","example":50},"required":{"type":"boolean","example":true},"mergeFieldName":{"type":"string","example":"client_name"},"defaultValue":{"type":"string","example":"Default value"},"editable":{"type":"boolean","example":false,"description":"Treat a value resolved from variables or defaultValue as a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","example":false,"description":"One signer role owns the generated field, but until that signer signs any signer able to act may fill or correct it. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Copied onto every document made from the template."},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","nullable":true,"example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Embedded AcroForm field to link this field to (see GET /templates/{id}/form-fields). Set to null to unlink: generated documents then draw the value at the field's coordinates instead of writing it through the PDF's form field. Omit to keep unchanged."},"acroOptionValue":{"type":"string","nullable":true,"example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked. Set to null to clear it, omit to keep it unchanged."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Copied onto generated document fields."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at, copied onto generated document fields. Imported automatically from the base PDF's form fields; omit to fit the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in, copied onto generated document fields. Imported from the base PDF's form fields; honored when the platform can render that face, otherwise the default font is used."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields and copied onto generated document fields."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","nullable":true,"format":"uuid","description":"Make this field conditionally required by the referenced template field (same template, same signer role). Set to null to clear the condition; omit to keep unchanged. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","nullable":true,"example":"Other","description":"Exact controller value the condition triggers on. Set to null to trigger on any checked/filled state; omit to keep unchanged."},"anchorText":{"type":"string","example":"Fund Lead Signature:","description":"Anchor string for anchor placement (must not contain {{ }}). Hidden markers remain in the PDF text layer — see CreateTemplateFieldDto."},"anchorPosition":{"allOf":[{"$ref":"#/components/schemas/AnchorPosition"}]},"anchorOffsetX":{"type":"number","example":0},"anchorOffsetY":{"type":"number","example":0},"hideAnchor":{"type":"boolean","example":false},"anchorMatchWholeWord":{"type":"boolean","example":false},"bookmarkName":{"type":"string","example":"SigSeller","description":"Word bookmark name for bookmark placement — see CreateTemplateFieldDto for the naming constraint."}}},"CreateDocumentFromTemplateDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"templateData":{"type":"object","additionalProperties":true,"description":"JSON input for Markdown/Liquid templates. Explicit input is required for generation; preview sample data is never used implicitly."},"name":{"type":"string","example":"NDA - Acme Corp"},"signers":{"type":"object","additionalProperties":true,"description":"Map of signer role ID to signer details (required if template has signer roles)","example":{"role-id-1":{"email":"client@acme.com","name":"John Doe"}}},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables to substitute in text fields (PDF) or DOCX body placeholders (DOCX)","example":{"client_name":"Acme Corporation","contract_date":"2026-01-15"}},"suppressNotifications":{"type":"boolean","description":"Suppress all email notifications for this document","default":false}},"required":["name"]},"DocumentStatus":{"type":"string","enum":["draft","pending","completing","completed","failed","voided","expired"]},"DocumentDto":{"type":"object","properties":{"collectionIds":{"description":"Collection memberships; omitted on lists unless includeCollections=true.","type":"array","items":{"type":"string","format":"uuid"}},"googleSource":{"description":"Original Google import provenance, available on detail responses.","allOf":[{"$ref":"#/components/schemas/GoogleProvenanceDto"}]},"id":{"type":"string"},"name":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/DocumentStatus"}]},"originalFileUrl":{"type":"string"},"signedFileUrl":{"type":"string","nullable":true},"certificateFileUrl":{"type":"string","nullable":true},"expiresAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"sandbox":{"type":"boolean","description":"Whether this is a sandbox (test) document"},"suppressNotifications":{"type":"boolean","description":"Whether email notifications are suppressed"},"formFieldsDetected":{"type":"number","nullable":true,"example":23,"description":"How many interactive form fields the uploaded PDF ships with, counted when the upload was confirmed. 0 for a flat PDF, null when the file was never scanned (e.g. generated from a template)."},"autoImportFormFields":{"type":"boolean","description":"Whether those embedded fields are placed automatically for the first signer added to this document."},"catalogFormSlug":{"type":"string","nullable":true,"description":"Standard Forms catalog slug this document was generated from, e.g. \"irs-w9\" (null for non-catalog documents)"},"catalogFormTitle":{"type":"string","nullable":true,"description":"Catalog form title, e.g. \"IRS Form W-9 …\""},"catalogRevision":{"type":"string","nullable":true,"description":"Catalog form revision, e.g. \"Rev. March 2024\""},"catalogVersionId":{"type":"string","nullable":true,"description":"ID of the catalog form version this document is based on"},"templateId":{"type":"string","nullable":true,"format":"uuid","description":"The workspace template this document was created from"},"templateName":{"type":"string","nullable":true,"description":"That template's current name, on the document detail only (null if the template was deleted)"},"signerNames":{"description":"Names of the people signing, in signing order. On document lists only.","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","status","originalFileUrl","sandbox","suppressNotifications","autoImportFormFields","createdAt","updatedAt"]},"GenerateDocumentDto":{"type":"object","properties":{"templateData":{"type":"object","additionalProperties":true,"description":"JSON input for Markdown/Liquid templates."},"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables to fill in template fields (by merge field name). For DOCX templates, these substitute {{placeholder}} tags in the document body. Falls back to default values if not provided.","example":{"client_name":"Acme Corporation","contract_date":"2026-01-15"}}}},"GeneratedDocumentDto":{"type":"object","properties":{"url":{"type":"string","description":"URL to download the generated PDF"},"expiresAt":{"format":"date-time","type":"string","description":"Expiration time for the download URL"}},"required":["url","expiresAt"]},"CreateCollectionDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"externalId":{"type":"string","minLength":1,"maxLength":255,"description":"Immutable, case-sensitive external reference, unique per organization and mode even when archived."},"metadata":{"type":"object","description":"JSON object, at most 16 KiB of UTF-8 JSON."}},"required":["name"]},"CollectionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"metadata":{"type":"object"},"archivedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"documentCount":{"type":"number"},"templateCount":{"type":"number"},"signingRequestCount":{"type":"number","description":"Signing requests started from this collection."}},"required":["id","organizationId","sandbox","name","description","externalId","metadata","archivedAt","createdAt","updatedAt","documentCount","templateCount","signingRequestCount"]},"CollectionSortBy":{"type":"string","enum":["createdAt","name"]},"PaginatedCollectionsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"UpdateCollectionDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","nullable":true,"maxLength":2000},"metadata":{"type":"object","description":"Replaces metadata. JSON object, at most 16 KiB of UTF-8 JSON."}}},"DocumentSortBy":{"type":"string","enum":["createdAt","name","status"]},"PaginatedDocumentsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentDto"}},"total":{"type":"number","description":"Total number of documents"},"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["data","total","page","limit","totalPages"]},"CollectionDocumentsMutationDto":{"type":"object","properties":{"documentIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["documentIds"]},"CollectionTemplatesMutationDto":{"type":"object","properties":{"templateIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["templateIds"]},"CreateUploadUrlDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"filename":{"type":"string","example":"contract.pdf"},"contentType":{"type":"string","example":"application/pdf"},"name":{"type":"string","example":"Lease: Flat 4 (renewal)","description":"What to call the document. The filename is restricted to ASCII because it names the stored file; a name is not. Defaults to the filename. Confirm can still rename it."}},"required":["filename","contentType"]},"UploadUrlResponseDto":{"type":"object","properties":{"documentId":{"type":"string"},"uploadUrl":{"type":"string"},"key":{"type":"string"},"maxUploadBytes":{"type":"number","example":26214400,"description":"Largest file this organization's plan accepts, in bytes. Uploading a bigger file is rejected when the upload is confirmed, so check it before transferring."}},"required":["documentId","uploadUrl","key","maxUploadBytes"]},"ConfirmUploadDto":{"type":"object","properties":{"name":{"type":"string","example":"Sales Contract Q1 2026"},"autoImportFormFields":{"type":"boolean","description":"When the uploaded PDF is a fillable form, its embedded fields are placed automatically for the first signer added — same positions, types, character limits and font sizes the form declares. Defaults to false for documents created with an API key (integrations place their own fields) and true for documents created from the dashboard; pass a value to override either way."}}},"UpdateDocumentDto":{"type":"object","properties":{"name":{"type":"string","example":"Sales Contract Q1 2026"}}},"AddSignerDto":{"type":"object","properties":{"email":{"type":"string","example":"john@example.com","description":"Signer email. Required for email notifications."},"name":{"type":"string","example":"John Doe"},"signingOrder":{"type":"number","example":1},"externalId":{"type":"string","example":"user_123","description":"External identifier for tracking signers in your system"},"redirectUrl":{"type":"string","example":"https://example.com/done","description":"URL to redirect signer after signing. Must be HTTPS (or localhost for development)."}},"required":["name"]},"SignerRole":{"type":"string","enum":["signer","approver","cc"]},"SignerStatus":{"type":"string","enum":["pending","viewed","signed","declined"]},"AuthMethod":{"type":"string","enum":["email_link","access_link","wallet_signature"]},"SignerDto":{"type":"object","properties":{"id":{"type":"string"},"documentId":{"type":"string"},"email":{"type":"string","nullable":true},"name":{"type":"string"},"externalId":{"type":"string","nullable":true},"role":{"allOf":[{"$ref":"#/components/schemas/SignerRole"}]},"signingOrder":{"type":"number"},"status":{"allOf":[{"$ref":"#/components/schemas/SignerStatus"}]},"authMethod":{"allOf":[{"$ref":"#/components/schemas/AuthMethod"}]},"signedAt":{"format":"date-time","type":"string","nullable":true},"accessToken":{"type":"string"},"redirectUrl":{"type":"string","nullable":true,"description":"URL to redirect signer after signing"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","documentId","name","role","signingOrder","status","authMethod","accessToken","createdAt","updatedAt"]},"AddFieldDto":{"type":"object","properties":{"required":{"type":"boolean","example":true,"description":"Whether the signer must fill this field (default true)"},"editable":{"type":"boolean","example":false,"description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","example":false,"description":"One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type."},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified name of an embedded AcroForm field in the PDF (see GET /documents/{id}/form-fields). When set, the value is written through the PDF form field at completion — comb boxes, checkboxes, and length limits render natively — instead of being overlay-stamped at the coordinates."},"acroOptionValue":{"type":"string","example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Without it, a format hint in the label (e.g. \"Date (MM-DD-YYYY)\") applies, then the signer locale."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","format":"uuid","description":"Make this field conditionally required: it must be filled before signing only while the referenced field (same document, same signer) is checked/filled — e.g. a W-9 LLC tax-classification code required only when the LLC box is checked. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","example":"Other","description":"Narrow the condition to an exact value of the referenced field (e.g. a dropdown's \"Other\" choice). Omit to trigger on any checked/filled state."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at. Imported automatically from the PDF form field's default appearance; omit to fit the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in. Imported from the PDF form field; honored when the platform can render that face, otherwise the default font is used. Values written through the form field render in the form's own font regardless."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields: the signer gets a multi-line editor and the value is laid out from the top of the box, wrapping to its width."},"signerId":{"type":"string"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number","example":1},"xPosition":{"type":"number","example":100},"yPosition":{"type":"number","example":200},"width":{"type":"number","example":200},"height":{"type":"number","example":50}},"required":["signerId","fieldType","pageNumber","xPosition","yPosition","width","height"]},"FieldFilledBy":{"type":"string","enum":["sender","signer"],"description":"Who wrote the current value: the sender (a non-editable template prefill or a signing-packet lock) or the signer (any fill, including bulk signing on their behalf). Null while unfilled."},"FieldDto":{"type":"object","properties":{"id":{"type":"string"},"documentId":{"type":"string"},"signerId":{"type":"string"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number"},"xPosition":{"type":"number"},"yPosition":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"label":{"type":"string","nullable":true,"description":"Human-readable label shown to the signer for this field"},"required":{"type":"string"},"value":{"type":"string","nullable":true},"editable":{"type":"boolean","description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","description":"One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Never true on signature or initials fields."},"signingDate":{"type":"boolean","nullable":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Null on a date made before the flag existed: a date on the signer’s own signature line is then the date of signing."},"signatureImageUrl":{"type":"string","nullable":true},"filledAt":{"format":"date-time","type":"string","nullable":true},"filledBy":{"nullable":true,"description":"Who wrote the current value: the sender (a non-editable template prefill or a signing-packet lock) or the signer (any fill, including bulk signing on their behalf). Null while unfilled.","allOf":[{"$ref":"#/components/schemas/FieldFilledBy"}]},"signingDateChangedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the signer changed the date beside their signature from the automatic date of signing to one of their own. Null otherwise."},"acroFieldName":{"type":"string","nullable":true,"description":"Embedded AcroForm field this field is linked to; values fill the PDF form field at completion instead of being overlay-stamped."},"acroOptionValue":{"type":"string","nullable":true,"description":"For radio-group AcroForm fields: the option this field selects."},"options":{"nullable":true,"description":"Allowed values for dropdown fields","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","nullable":true,"description":"Maximum characters accepted at fill time"},"inputMask":{"type":"string","example":"###-##-####","nullable":true,"description":"Input mask where # represents one digit"},"validationPattern":{"type":"string","nullable":true,"description":"Regex the filled value must match"},"validationMessage":{"type":"string","nullable":true,"description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","nullable":true,"description":"Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'"},"groupKey":{"type":"string","nullable":true},"groupRequired":{"type":"boolean","description":"Whether at least one member of this group must be selected"},"requiredWhenFieldId":{"type":"string","nullable":true,"format":"uuid","description":"Id of the field whose checked/filled state makes this field required (conditional requirement); null when unconditional"},"requiredWhenValue":{"type":"string","nullable":true,"description":"Exact controller value the condition triggers on; null means any checked/filled state"},"fontSize":{"type":"number","nullable":true,"example":9,"description":"Point size the value is drawn at, imported from the PDF form field. Null means the size is fitted to the box."},"textColor":{"type":"string","nullable":true,"example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"nullable":true,"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","nullable":true,"example":"Helvetica-Bold","description":"Base font the value is drawn in, imported from the PDF form field"},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks (a multiline form field)"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","documentId","signerId","fieldType","pageNumber","xPosition","yPosition","width","height","required","editable","sharedFill","groupRequired","multiline","createdAt","updatedAt"]},"BatchFieldDto":{"type":"object","properties":{"required":{"type":"boolean","example":true,"description":"Whether the signer must fill this field (default true)"},"editable":{"type":"boolean","example":false,"description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","example":false,"description":"One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type."},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified name of an embedded AcroForm field in the PDF (see GET /documents/{id}/form-fields). When set, the value is written through the PDF form field at completion — comb boxes, checkboxes, and length limits render natively — instead of being overlay-stamped at the coordinates."},"acroOptionValue":{"type":"string","example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Without it, a format hint in the label (e.g. \"Date (MM-DD-YYYY)\") applies, then the signer locale."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","format":"uuid","description":"Make this field conditionally required: it must be filled before signing only while the referenced field (same document, same signer) is checked/filled — e.g. a W-9 LLC tax-classification code required only when the LLC box is checked. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","example":"Other","description":"Narrow the condition to an exact value of the referenced field (e.g. a dropdown's \"Other\" choice). Omit to trigger on any checked/filled state."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at. Imported automatically from the PDF form field's default appearance; omit to fit the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in. Imported from the PDF form field; honored when the platform can render that face, otherwise the default font is used. Values written through the form field render in the form's own font regardless."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields: the signer gets a multi-line editor and the value is laid out from the top of the box, wrapping to its width."},"signerId":{"type":"string"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number","description":"Place it at these coordinates. Give either these or anchorText, never both."},"xPosition":{"type":"number"},"yPosition":{"type":"number"},"anchorText":{"type":"string","description":"Place it against this text instead, as the anchored route does.","example":"Tenant signature"},"occurrence":{"type":"number","description":"Which match, when the text appears more than once."},"position":{"type":"string","enum":["replace","left","right","above","below"]},"offsetX":{"type":"number"},"offsetY":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"required":["signerId","fieldType"]},"AddFieldsDto":{"type":"object","properties":{"fields":{"description":"The fields to place, in one request. Each is placed on its own terms; one that cannot be placed does not stop the others.","type":"array","items":{"$ref":"#/components/schemas/BatchFieldDto"}}},"required":["fields"]},"FieldResultDto":{"type":"object","properties":{"index":{"type":"number","example":0,"description":"Which entry of the request this answers."},"success":{"type":"boolean","example":true},"field":{"description":"The field, when it was placed.","allOf":[{"$ref":"#/components/schemas/FieldDto"}]},"error":{"type":"string","example":"There is no room above \"Signature\" for a 180 × 40 field.","description":"Why it was not placed."}},"required":["index","success"]},"AddFieldsResultDto":{"type":"object","properties":{"placed":{"type":"number","example":5},"failed":{"type":"number","example":1},"results":{"type":"array","items":{"$ref":"#/components/schemas/FieldResultDto"}}},"required":["placed","failed","results"]},"FillFieldValueDto":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid","description":"The field to fill"},"value":{"type":"string","example":"Korala LLC","description":"What the field should hold. A checkbox takes \"true\" or \"false\"; a dropdown or a radio option takes one of its allowed values; a date takes the field's dateFormat. An empty string clears the field."}},"required":["fieldId","value"]},"FillFieldsDto":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/FillFieldValueDto"}}},"required":["values"]},"FillFieldResultDto":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid"},"success":{"type":"boolean","example":true},"error":{"type":"string","example":"The signer has already filled this field","description":"Why the value was not written."}},"required":["fieldId","success"]},"RemainingFieldDto":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid"},"label":{"type":"string","example":"Line 7b: SSN, ITIN, or EIN"},"fieldType":{"type":"string","example":"text"}},"required":["fieldId","fieldType"]},"FillFieldsResultDto":{"type":"object","properties":{"filled":{"type":"number","example":12},"failed":{"type":"number","example":1},"results":{"type":"array","items":{"$ref":"#/components/schemas/FillFieldResultDto"}},"stillToFill":{"description":"Fields still holding no value that the sender can fill, signatures excluded. Empty does not by itself mean the document can be signed: read blockingIssue.","type":"array","items":{"$ref":"#/components/schemas/RemainingFieldDto"}},"blockingIssue":{"type":"string","example":"Choose one of \"Line 9a: Entity type\"","description":"What would still stop the signer completing, judged by the same check the signing step runs, with the signatures taken as drawn. Absent when nothing but the signatures is left."}},"required":["filled","failed","results","stillToFill"]},"AddAnchoredFieldDto":{"type":"object","properties":{"required":{"type":"boolean","example":true,"description":"Whether the signer must fill this field (default true)"},"editable":{"type":"boolean","example":false,"description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","example":false,"description":"One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type."},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified name of an embedded AcroForm field in the PDF (see GET /documents/{id}/form-fields). When set, the value is written through the PDF form field at completion — comb boxes, checkboxes, and length limits render natively — instead of being overlay-stamped at the coordinates."},"acroOptionValue":{"type":"string","example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Without it, a format hint in the label (e.g. \"Date (MM-DD-YYYY)\") applies, then the signer locale."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","format":"uuid","description":"Make this field conditionally required: it must be filled before signing only while the referenced field (same document, same signer) is checked/filled — e.g. a W-9 LLC tax-classification code required only when the LLC box is checked. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","example":"Other","description":"Narrow the condition to an exact value of the referenced field (e.g. a dropdown's \"Other\" choice). Omit to trigger on any checked/filled state."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at. Imported automatically from the PDF form field's default appearance; omit to fit the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in. Imported from the PDF form field; honored when the platform can render that face, otherwise the default font is used. Values written through the form field render in the form's own font regardless."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields: the signer gets a multi-line editor and the value is laid out from the top of the box, wrapping to its width."},"signerId":{"type":"string"},"fieldType":{"type":"string","enum":["signature","initials","date","text","checkbox","dropdown","radio"]},"anchorText":{"type":"string","description":"Text in the PDF to place the field against","example":"Tenant signature"},"occurrence":{"type":"number","description":"Which match to use when the text appears more than once, counting from 1 in reading order. Required in that case.","minimum":1},"position":{"type":"string","enum":["replace","left","right","above","below"],"default":"right","description":"Where the field goes relative to the text. \"right\" and \"left\" sit on the same line, the field resting on the bottom of the text; \"above\" and \"below\" share its left edge. A field given no height is no taller than the blank it stands in. \"replace\" covers the text and takes its size."},"offsetX":{"type":"number","description":"Shift right, in points","default":0},"offsetY":{"type":"number","description":"Shift down, in points","default":0},"width":{"type":"number","description":"In points, rounded. Defaults to a size fit for the type."},"height":{"type":"number","description":"In points, rounded. Defaults to a size fit for the type, and above or below a label to no more than the blank there."}},"required":["signerId","fieldType","anchorText"]},"BlankDto":{"type":"object","properties":{"pageNumber":{"type":"number","example":1},"label":{"type":"string","example":"Tenant signature","description":"The words printed against the blank: before a rule on the same line, or under it. Empty when the rule carries no nearby label."},"line":{"type":"string","example":"Tenant signature ______________  Date ____________","description":"The whole printed line, so two blanks sharing a label can be told apart."},"xPosition":{"type":"number","example":120},"yPosition":{"type":"number","example":640},"width":{"type":"number","example":240},"height":{"type":"number","example":28},"found":{"type":"string","enum":["rule","gap"],"description":"\"rule\" is a run of underscores or dashes. \"gap\" is a short label ending in a colon with room after it."}},"required":["pageNumber","label","line","xPosition","yPosition","width","height","found"]},"PageSizeDto":{"type":"object","properties":{"pageNumber":{"type":"number","example":1},"width":{"type":"number","description":"Page width in PDF points","example":612},"height":{"type":"number","description":"Page height in PDF points","example":792},"rotated":{"type":"boolean","description":"True for a page stored rotated. Text positions on it cannot be trusted, so fields there need coordinates."}},"required":["pageNumber","width","height"]},"DocumentBlanksDto":{"type":"object","properties":{"blanks":{"type":"array","items":{"$ref":"#/components/schemas/BlankDto"}},"pages":{"type":"array","items":{"$ref":"#/components/schemas/PageSizeDto"}},"pageCount":{"type":"number","example":3},"hasFormFields":{"type":"boolean","nullable":true,"example":false,"description":"Whether the document is a fillable form. When it is, its own fields say where everything goes and import_form_fields places them; the blanks here are only what the printed text shows. Null when the file was never scanned for them, which is not the same as having none."}},"required":["blanks","pages","pageCount","hasFormFields"]},"TextMatchDto":{"type":"object","properties":{"text":{"type":"string","description":"The phrase this match is for, as it was asked","example":"Signature"},"occurrence":{"type":"number","description":"Which match of that phrase this is, counting from 1 in reading order","example":1},"pageNumber":{"type":"number","example":1},"xPosition":{"type":"number","description":"Left edge of the matched text, in points from the page left"},"yPosition":{"type":"number","description":"Top edge of the matched text, in points from the page top"},"width":{"type":"number"},"height":{"type":"number"},"line":{"type":"string","description":"The whole line the match sits on, to tell matches apart","example":"Tenant signature: ______________  Date: ________"}},"required":["text","occurrence","pageNumber","xPosition","yPosition","width","height","line"]},"TextMatchCountDto":{"type":"object","properties":{"text":{"type":"string","example":"Signature"},"total":{"type":"number","example":2}},"required":["text","total"]},"DocumentTextDto":{"type":"object","properties":{"pages":{"description":"The pages that were searched: at most the first 150","type":"array","items":{"$ref":"#/components/schemas/PageSizeDto"}},"pageCount":{"type":"number","description":"Pages in the document, searched or not"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/TextMatchDto"}},"totalMatches":{"type":"number","description":"Matches found for all the phrases together, which may exceed those listed; `counts` has the total for each phrase"},"counts":{"description":"How often each phrase was found. A phrase with no matches is listed with 0, so nothing asked for goes unanswered","type":"array","items":{"$ref":"#/components/schemas/TextMatchCountDto"}},"hasText":{"type":"boolean","description":"False when the PDF has no text layer (a scan): nothing can be found in it, so fields need coordinates"}},"required":["pages","pageCount","matches","totalMatches","counts","hasText"]},"PageTextDto":{"type":"object","properties":{"pageNumber":{"type":"number","example":1},"text":{"type":"string","description":"The page as someone reading it would see it: columns kept apart, lines in order. Empty for a page with no text layer."},"truncated":{"type":"boolean","description":"True when this page ran past 60,000 characters, more than any printed page holds, and was cut there"}},"required":["pageNumber","text"]},"DocumentPagesTextDto":{"type":"object","properties":{"pageCount":{"type":"number","description":"Pages in the document"},"pages":{"type":"array","items":{"$ref":"#/components/schemas/PageTextDto"}},"nextPage":{"type":"number","nullable":true,"description":"The page to continue from, or null when the last page was returned"},"hasText":{"type":"boolean","description":"False when none of the returned pages has any text. They are scanned, and have to be looked at instead of read; other pages of the same document may still have text"}},"required":["pageCount","pages","nextPage","hasText"]},"PageImageFieldDto":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"The number captioned on the image"},"fieldId":{"type":"string"},"fieldType":{"type":"string","enum":["signature","initials","date","text","checkbox","dropdown","radio"]},"signerName":{"type":"string","nullable":true},"xPosition":{"type":"number"},"yPosition":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}},"required":["number","fieldId","fieldType","signerName","xPosition","yPosition","width","height"]},"PageImageDto":{"type":"object","properties":{"pageNumber":{"type":"number","example":1},"pageCount":{"type":"number","description":"Pages in the document"},"widthPoints":{"type":"number","description":"Page width in PDF points","example":612},"heightPoints":{"type":"number","description":"Page height in PDF points","example":792},"pixelsPerPoint":{"type":"number","description":"Image pixels per PDF point. Divide a pixel position by this to get the point position a field takes.","example":2},"fieldsShown":{"type":"number","description":"Fields outlined on the image"},"fields":{"description":"The outlined fields. Each is captioned on the image with its number and type; whose it is, is here","type":"array","items":{"$ref":"#/components/schemas/PageImageFieldDto"}},"pngBase64":{"type":"string","description":"The page as a PNG, base64-encoded"}},"required":["pageNumber","pageCount","widthPoints","heightPoints","pixelsPerPoint","fieldsShown","fields","pngBase64"]},"FormFieldPartyDto":{"type":"object","properties":{"key":{"type":"string","example":"employer","description":"Stable key for this party, used when assigning it"},"name":{"type":"string","example":"Employer"},"evidence":{"type":"string","example":"12 fields on page 2 name the employer","description":"Why the form was read this way, in words the sender can check against the document in front of them"},"pages":{"example":[2],"type":"array","items":{"type":"number"}},"fieldCount":{"type":"number","example":12},"source":{"type":"string","enum":["named","layout"],"description":"How the split was arrived at. \"named\" means the form names this party itself — an employer, a tenant — and the fields are its section. \"layout\" means it does not, or not in a language we read, so the form was cut along its widest visible breaks into as many parts as there are signers: unlabelled, and offered for the sender to assign rather than proposed as fact."},"signerIds":{"description":"Signers these fields are currently assigned to","type":"array","items":{"type":"string"}},"fieldIds":{"description":"Ids of this party's fields, for highlighting them while the sender decides who fills the section.","type":"array","items":{"type":"string"}}},"required":["key","name","evidence","pages","fieldCount","source","signerIds","fieldIds"]},"AssignFormFieldPartyDto":{"type":"object","properties":{"party":{"type":"string","example":"employer","description":"Party key to move"},"signerId":{"type":"string","description":"Signer who fills this party's fields"}},"required":["party","signerId"]},"AssignFormFieldPartiesDto":{"type":"object","properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/AssignFormFieldPartyDto"}}},"required":["assignments"]},"ImportFormFieldsDto":{"type":"object","properties":{"signerId":{"type":"string","description":"Signer the imported fields are assigned to"},"replaceExisting":{"type":"boolean","default":false,"description":"Delete the document's existing fields before importing, so the import is the whole field set. Without it, existing fields are kept and only form fields that are not placed yet are added, so repeating the call places nothing new."}},"required":["signerId"]},"UpdateFieldDto":{"type":"object","properties":{"signerId":{"type":"string","description":"Reassign this one field to another signer on the same document — finer-grained than the parties assignment, which moves whole sections."},"required":{"type":"boolean","example":false,"description":"Whether the signer must fill this field"},"editable":{"type":"boolean","example":false,"description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","example":false,"description":"One signer owns the field, but until they sign any signer able to act may fill or correct it. Refused on signature and initials fields."},"signingDate":{"type":"boolean","example":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type."},"xPosition":{"type":"number","example":100},"yPosition":{"type":"number","example":200},"width":{"type":"number","example":200},"height":{"type":"number","example":50},"label":{"type":"string","example":"Your full name","description":"Human-readable label shown to the signer for this field"},"acroFieldName":{"type":"string","nullable":true,"example":"topmostSubform[0].Page1[0].f1_01[0]","description":"Fully-qualified name of an embedded AcroForm field to link this field to (see GET /documents/{id}/form-fields). Set to null to unlink: the value is then drawn at the field's coordinates instead of written through the PDF's form field. Omit to keep unchanged."},"acroOptionValue":{"type":"string","nullable":true,"example":"married","description":"For radio-group AcroForm fields: the option (export value) this field selects when checked. Set to null to clear it, omit to keep it unchanged."},"options":{"example":["CA","NY"],"description":"Allowed values for dropdown fields. The signer picks one; fills with a value outside this list are rejected.","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","example":11,"description":"Maximum characters accepted at fill time. Imported automatically from AcroForm comb fields by detection."},"inputMask":{"type":"string","nullable":true,"example":"###-##-####","description":"Single-line signer input mask. Each # accepts one digit; Korala inserts every other character as a literal."},"validationPattern":{"type":"string","example":"^\\d{3}-\\d{2}-\\d{4}$","description":"Regular expression the filled value must match (text and date fields). Rejected fills return validationMessage."},"validationMessage":{"type":"string","example":"Enter your SSN as XXX-XX-XXXX","description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","example":"MM-DD-YYYY","description":"Date fields only: format the auto-filled date is rendered in. Combines D/DD, M/MM, and YY/YYYY tokens with a consistent \"-\", \"/\", or \".\" separator. Without it, a format hint in the label (e.g. \"Date (MM-DD-YYYY)\") applies, then the signer locale."},"groupKey":{"type":"string","example":"fed_tax_class","description":"Semantic group key. Checkbox members sharing a groupKey are mutually exclusive (checking one clears the others) even with distinct PDF fill targets — e.g. a W-9 federal tax classification."},"groupRequired":{"type":"boolean","example":true,"description":"Require at least one member of this field's group to be selected before signing can complete."},"requiredWhenFieldId":{"type":"string","nullable":true,"format":"uuid","description":"Make this field conditionally required: it must be filled before signing only while the referenced field (same document, same signer) is checked/filled. Set to null to clear the condition; omit to keep unchanged. Refused on choose-one group members."},"requiredWhenValue":{"type":"string","nullable":true,"example":"Other","description":"Narrow the condition to an exact value of the referenced field. Set to null to trigger on any checked/filled state; omit to keep unchanged."},"fontSize":{"type":"number","example":9,"description":"Point size the value is drawn at; null-equivalent when omitted, which fits the size to the box."},"textColor":{"type":"string","example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the value is drawn in. Imported from the PDF form field; honored when the platform can render that face, otherwise the default font is used. Values written through the form field render in the form's own font regardless."},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks. Imported from multiline PDF form fields: the signer gets a multi-line editor and the value is laid out from the top of the box, wrapping to its width."}}},"UpdateSignerDto":{"type":"object","properties":{"name":{"type":"string","example":"John Doe"},"signingOrder":{"type":"number","example":2,"description":"Signers with the same order sign at the same time; a higher order waits for every lower one."}}},"ElectronicDisclosureProfileDto":{"type":"object","properties":{"id":{"type":"string","example":"acme-electronic-signing-terms"},"version":{"type":"string","example":"2026-09-01"},"title":{"type":"string","example":"Electronic signature disclosure"},"contentHtml":{"type":"string","description":"Restricted HTML. Scripts, images, styles, embedded content, and unsafe links are removed."}},"required":["id","version","title","contentHtml"]},"SendDocumentDto":{"type":"object","properties":{"electronicDisclosure":{"$ref":"#/components/schemas/ElectronicDisclosureProfileDto"},"suppressNotifications":{"type":"boolean","description":"Suppress all email notifications for this document (signing invitations and completion emails)","default":false},"expiresInDays":{"type":"number","description":"Expire this document if unsigned after N days from send. Overrides the organization's default. Omit to use the org default (or never expire).","minimum":1,"maximum":365,"example":14}}},"AuditEventDto":{"type":"object","properties":{"id":{"type":"string"},"documentId":{"type":"string"},"signerId":{"type":"string","nullable":true},"eventType":{"type":"string"},"ipAddress":{"type":"string","nullable":true},"claimedIpAddress":{"type":"string","nullable":true,"description":"Partner-asserted end-user IP address (from X-Client-IP header)"},"userAgent":{"type":"string","nullable":true},"geoLocation":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"documentHash":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["id","documentId","eventType","createdAt"]},"BulkSignFieldValueDto":{"type":"object","properties":{"fieldId":{"type":"string","description":"Field ID to override"},"value":{"type":"string","description":"Value to set on the field"},"signatureImageUrl":{"type":"string","description":"Signature image as a base64 PNG data URL (for Signature/Initials fields)","example":"data:image/png;base64,..."}},"required":["fieldId","value"]},"BulkSignDocumentOverrideDto":{"type":"object","properties":{"documentId":{"type":"string","description":"Document ID to apply overrides to"},"fields":{"description":"Field value overrides for this document","type":"array","items":{"$ref":"#/components/schemas/BulkSignFieldValueDto"}}},"required":["documentId","fields"]},"BulkSignRequestDto":{"type":"object","properties":{"documentIds":{"description":"Document IDs to sign (max 500)","type":"array","items":{"type":"string"}},"signerEmail":{"type":"string","example":"ceo@company.com","description":"Signer email. Exactly one of signerEmail or signerExternalId is required. When one person holds several roles on the same document and so appears as several signers with this email, the call takes the lowest signing order that has not signed or declined, so repeated calls walk the roles in order. Use signerExternalId to name one specific signer instead."},"signerExternalId":{"type":"string","example":"user_123","description":"Signer external ID. Exactly one of signerEmail or signerExternalId is required."},"autoFillDateValue":{"type":"string","example":"2026-02-18","description":"Value to auto-fill Date fields, as ISO YYYY-MM-DD. Defaults to today. Each field renders it through its own dateFormat, so one batch can span fields with different formats. A non-ISO value is stamped verbatim."},"documents":{"description":"Per-document field overrides","type":"array","items":{"$ref":"#/components/schemas/BulkSignDocumentOverrideDto"}}},"required":["documentIds"]},"BulkSignDocumentResultDto":{"type":"object","properties":{"documentId":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"string","nullable":true},"allSigned":{"type":"boolean","nullable":true,"description":"Whether all signers have signed (triggers completion)"}},"required":["documentId","success"]},"BulkSignResponseDto":{"type":"object","properties":{"signed":{"type":"number","description":"Number of documents successfully signed"},"failed":{"type":"number","description":"Number of documents that failed"},"results":{"description":"Per-document results","type":"array","items":{"$ref":"#/components/schemas/BulkSignDocumentResultDto"}}},"required":["signed","failed","results"]},"WebhookEventType":{"type":"string","enum":["risk.context.created","risk.context.subject_added","risk.context.policies_configured","risk.investigation.requested","risk.investigation.completed","risk.investigation.failed","risk.investigation.reviewed","risk.subject.created","risk.policy.created","risk.policy.published","risk.activity.reported","risk.evidence.recorded","risk.evidence.batch_recorded","risk.assessment.created","risk.action.requested","risk.action.transitioned","risk.override.created","risk.override.revoked","screening.run.completed","screening.match.found","screening.adverse_media.run.completed","screening.adverse_media.finding.found","document_created","document_sent","document_viewed","document_signed","document_completed","document_failed","document_voided","document_declined","document_expired","signing_packet.sent","signing_packet.viewed","signing_packet.item_signed","signing_packet.recipient_completed","signing_packet.partially_completed","signing_packet.voided","signing_packet.expired","session_completed","session_expired","session_failed","session_resolved","session_review_required","session_resubmission_requested","session_workflow_completed","session_workflow_failed","workflow_run_completed","workflow_run_failed","test"]},"WebhookMode":{"type":"string","enum":["live","test"],"description":"Which traffic this endpoint receives: live or test documents, sessions and workflows. API credentials pin the mode. Existing subscriptions cannot change mode."},"CreateWebhookDto":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/webhooks"},"events":{"type":"array","example":["document_signed","document_completed"],"items":{"$ref":"#/components/schemas/WebhookEventType"}},"description":{"type":"string","example":"Notifications for signed documents"},"mode":{"default":"live","description":"Which traffic this endpoint receives: live or test documents, sessions and workflows. API credentials pin the mode. Existing subscriptions cannot change mode.","allOf":[{"$ref":"#/components/schemas/WebhookMode"}]}},"required":["url","events"]},"WebhookWithSecretDto":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"mode":{"description":"Which traffic this endpoint receives: live or test documents, sessions and workflows. API credentials pin the mode. Existing subscriptions cannot change mode.","allOf":[{"$ref":"#/components/schemas/WebhookMode"}]},"isActive":{"type":"boolean"},"description":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"secret":{"type":"string","description":"Secret for HMAC signature verification (only shown once)"}},"required":["id","url","events","mode","isActive","createdAt","updatedAt","secret"]},"WebhookDto":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"mode":{"description":"Which traffic this endpoint receives: live or test documents, sessions and workflows. API credentials pin the mode. Existing subscriptions cannot change mode.","allOf":[{"$ref":"#/components/schemas/WebhookMode"}]},"isActive":{"type":"boolean"},"description":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","events","mode","isActive","createdAt","updatedAt"]},"UpdateWebhookDto":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/webhooks"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"description":{"type":"string"},"isActive":{"type":"boolean"},"mode":{"description":"Which traffic this endpoint receives: live or test documents, sessions and workflows. API credentials pin the mode. Existing subscriptions cannot change mode.","allOf":[{"$ref":"#/components/schemas/WebhookMode"}]}}},"DocumentCreatedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"sandbox":{"type":"boolean"}},"required":["documentId","name","status","sandbox"]},"DocumentSentEventData":{"type":"object","properties":{"documentId":{"type":"string"},"name":{"type":"string"},"signerCount":{"type":"number"},"sandbox":{"type":"boolean"}},"required":["documentId","name","signerCount","sandbox"]},"DocumentViewedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"signerId":{"type":"string"},"signerEmail":{"type":"string","nullable":true},"signerExternalId":{"type":"string","nullable":true},"packetId":{"type":"string","description":"Present when the signer opened the document in a signing packet: the packet"},"packetItemId":{"type":"string","description":"Present when the signer opened the document in a signing packet: the packet item for this document"},"sandbox":{"type":"boolean"}},"required":["documentId","signerId","sandbox"]},"DocumentSignedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"signerId":{"type":"string"},"signerEmail":{"type":"string","nullable":true},"signerExternalId":{"type":"string","nullable":true},"allSigned":{"type":"boolean","description":"Whether all signers have now signed"},"packetId":{"type":"string","description":"Present when the signer signed through a signing packet: the packet"},"packetItemId":{"type":"string","description":"Present when the signer signed through a signing packet: the packet item for this document"},"bulkSign":{"type":"boolean","description":"True when the signature was applied by bulk signing"},"sandbox":{"type":"boolean"}},"required":["documentId","signerId","allSigned","sandbox"]},"DocumentCompletedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"name":{"type":"string"},"completedAt":{"type":"string","description":"ISO 8601 timestamp"},"signerCount":{"type":"number"},"sandbox":{"type":"boolean"}},"required":["documentId","name","completedAt","signerCount","sandbox"]},"DocumentFailedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"error":{"type":"string"},"sandbox":{"type":"boolean"}},"required":["documentId","error","sandbox"]},"DocumentVoidedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"name":{"type":"string"},"sandbox":{"type":"boolean"}},"required":["documentId","name","sandbox"]},"DocumentDeclinedEventData":{"type":"object","properties":{"documentId":{"type":"string"},"signerId":{"type":"string"},"signerEmail":{"type":"string","nullable":true},"signerExternalId":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"sandbox":{"type":"boolean"}},"required":["documentId","signerId","sandbox"]},"TestEventData":{"type":"object","properties":{"sandbox":{"type":"boolean"},"message":{"type":"string"}},"required":["sandbox","message"]},"WebhookPayloadDto":{"type":"object","properties":{"eventId":{"type":"string","description":"Unique delivery ID"},"event":{"description":"Event type","allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"timestamp":{"type":"string","description":"ISO 8601 timestamp"},"data":{"description":"Event-specific data","oneOf":[{"$ref":"#/components/schemas/DocumentCreatedEventData"},{"$ref":"#/components/schemas/DocumentSentEventData"},{"$ref":"#/components/schemas/DocumentViewedEventData"},{"$ref":"#/components/schemas/DocumentSignedEventData"},{"$ref":"#/components/schemas/DocumentCompletedEventData"},{"$ref":"#/components/schemas/DocumentFailedEventData"},{"$ref":"#/components/schemas/DocumentVoidedEventData"},{"$ref":"#/components/schemas/DocumentDeclinedEventData"},{"$ref":"#/components/schemas/TestEventData"}]}},"required":["eventId","event","timestamp","data"]},"WebhookDeliveryStatus":{"type":"string","enum":["pending","success","failed","retrying"]},"WebhookDeliveryDto":{"type":"object","properties":{"id":{"type":"string"},"webhookId":{"type":"string"},"eventType":{"allOf":[{"$ref":"#/components/schemas/WebhookEventType"}]},"payload":{"$ref":"#/components/schemas/WebhookPayloadDto"},"status":{"allOf":[{"$ref":"#/components/schemas/WebhookDeliveryStatus"}]},"httpStatusCode":{"type":"number"},"requestHeaders":{"type":"object","description":"Request headers sent with the webhook","additionalProperties":{"type":"string"}},"responseHeaders":{"type":"object","description":"Response headers received from the endpoint","additionalProperties":{"type":"string"}},"responseBody":{"type":"string"},"attempts":{"type":"number"},"nextRetryAt":{"format":"date-time","type":"string"},"deliveredAt":{"format":"date-time","type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","webhookId","eventType","payload","status","attempts","createdAt"]},"WebhookDeliveryListDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryDto"}},"nextCursor":{"type":"string","description":"Cursor for the next page of results"},"hasMore":{"type":"boolean","description":"Whether more results are available"}},"required":["data","hasMore"]},"PlanType":{"type":"string","enum":["api_sandbox","api_payg","api_startup","api_scale","web_free","web_pro","web_business","web_enterprise"],"description":"Current plan type"},"UsageDto":{"type":"object","properties":{"signingCount":{"type":"number","description":"Document signings used this period"},"signingLimit":{"type":"number","nullable":true,"description":"Signing limit (null = unlimited)"},"signingRemaining":{"type":"number","nullable":true,"description":"Signings remaining (null = unlimited)"},"fillCount":{"type":"number","description":"Template fills used this period"},"fillLimit":{"type":"number","nullable":true,"description":"Fill limit (null = unlimited)"},"fillRemaining":{"type":"number","nullable":true,"description":"Fills remaining (null = unlimited)"},"periodStart":{"format":"date-time","type":"string","description":"Current billing period start"},"periodEnd":{"format":"date-time","type":"string","description":"Current billing period end"},"planType":{"description":"Current plan type","allOf":[{"$ref":"#/components/schemas/PlanType"}]},"planName":{"type":"string","description":"Current plan display name"},"signingOverageCents":{"type":"number","description":"Signing overage charges this period (cents)"},"fillOverageCents":{"type":"number","description":"Fill overage charges this period (cents)"}},"required":["signingCount","fillCount","periodStart","periodEnd","planType","planName","signingOverageCents","fillOverageCents"]},"SandboxUsageDto":{"type":"object","properties":{"signingCount":{"type":"number","description":"Sandbox document signings used this period"},"signingLimit":{"type":"number","nullable":true,"description":"Sandbox signing limit (null = unlimited)"},"signingRemaining":{"type":"number","nullable":true,"description":"Sandbox signings remaining (null = unlimited)"},"fillCount":{"type":"number","description":"Sandbox template fills used this period"},"fillLimit":{"type":"number","nullable":true,"description":"Sandbox fill limit (null = unlimited)"},"fillRemaining":{"type":"number","nullable":true,"description":"Sandbox fills remaining (null = unlimited)"},"periodStart":{"format":"date-time","type":"string","description":"Current billing period start"},"periodEnd":{"format":"date-time","type":"string","description":"Current billing period end"}},"required":["signingCount","fillCount","periodStart","periodEnd"]},"PlanDto":{"type":"object","properties":{"planType":{"description":"Current plan type","allOf":[{"$ref":"#/components/schemas/PlanType"}]},"name":{"type":"string","description":"Plan display name"},"basePriceCents":{"type":"number","description":"Base monthly price in cents"},"perUser":{"type":"boolean","description":"Whether base price is per-user"},"includedSignings":{"type":"number","description":"Included signings per month (-1 = unlimited, 0 = none)"},"signingOverageCents":{"type":"number","description":"Overage price per signing in cents"},"fillPriceCents":{"type":"number","description":"Price per template fill in cents"},"includedFills":{"type":"number","description":"Included template fills per month (-1 = unlimited, 0 = none)"},"hardLimit":{"type":"boolean","description":"Whether the plan has a hard limit (blocks when exceeded)"},"customSigningLimit":{"type":"number","nullable":true,"description":"Custom signing limit override"},"customFillLimit":{"type":"number","nullable":true,"description":"Custom fill limit override"}},"required":["planType","name","basePriceCents","perUser","includedSignings","signingOverageCents","fillPriceCents","includedFills","hardLimit"]},"TriggerFieldDetectionDto":{"type":"object","properties":{"minConfidence":{"type":"number","description":"Minimum confidence threshold (0-100)"}}},"FieldDetectionStatus":{"type":"string","enum":["queued","ocr_processing","ai_processing","completed","failed"],"description":"Current status of the field detection job"},"FieldDetectionJobDto":{"type":"object","properties":{"id":{"type":"string","description":"Job ID"},"documentId":{"type":"string","description":"Document ID (if detecting for a document)"},"templateId":{"type":"string","description":"Template ID (if detecting for a template)"},"status":{"description":"Current status of the field detection job","allOf":[{"$ref":"#/components/schemas/FieldDetectionStatus"}]},"ocrProcessingMs":{"type":"number","description":"OCR processing time in milliseconds"},"aiProcessingMs":{"type":"number","description":"AI processing time in milliseconds"},"proposedFieldCount":{"type":"number","description":"Number of proposed fields detected"},"errorMessage":{"type":"string","description":"Error message if job failed"},"createdAt":{"format":"date-time","type":"string","description":"Job creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Job last update timestamp"}},"required":["id","status","createdAt","updatedAt"]},"ProposedFieldStatus":{"type":"string","enum":["pending","accepted","rejected","modified"],"description":"Review status of the proposed field"},"ProposedFieldDto":{"type":"object","properties":{"id":{"type":"string","description":"Proposed field ID"},"documentId":{"type":"string","description":"Document ID (if detecting for a document)"},"templateId":{"type":"string","description":"Template ID (if detecting for a template)"},"jobId":{"type":"string","description":"Parent job ID"},"fieldType":{"description":"Type of field detected","allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number","description":"Page number where field was detected"},"xPosition":{"type":"number","description":"X position in PDF coordinates"},"yPosition":{"type":"number","description":"Y position in PDF coordinates"},"width":{"type":"number","description":"Field width in PDF coordinates"},"height":{"type":"number","description":"Field height in PDF coordinates"},"confidence":{"type":"number","description":"Confidence score 0-100"},"detectionReason":{"type":"string","description":"Reason for detection"},"contextText":{"type":"string","description":"Surrounding text context"},"acroFieldName":{"type":"string","description":"Embedded AcroForm field this proposal came from (fillable PDFs). Accepted fields keep the link, so values fill the PDF form field at completion."},"acroOptionValue":{"type":"string","description":"For radio-group AcroForm fields: the option this proposal selects."},"options":{"description":"Allowed values for dropdown fields","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","description":"Character limit read from the embedded form field (comb boxes)"},"groupKey":{"type":"string","description":"Semantic group key (radio options share the AcroForm field name); members are mutually exclusive when accepted"},"fontSize":{"type":"number","example":9,"description":"Point size the embedded form field draws its value at; absent when the form auto-sizes the text"},"textColor":{"type":"string","example":"#000080","description":"Text color of the embedded form field, as #rrggbb"},"textAlign":{"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","example":"Helvetica-Bold","description":"Base font the embedded form field draws its value in"},"multiline":{"type":"boolean","description":"Whether the embedded form field is multiline"},"status":{"description":"Review status of the proposed field","allOf":[{"$ref":"#/components/schemas/ProposedFieldStatus"}]},"acceptedFieldId":{"type":"string","description":"ID of the accepted field (if accepted)"},"reviewedAt":{"format":"date-time","type":"string","description":"When the field was reviewed"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","jobId","fieldType","pageNumber","xPosition","yPosition","width","height","confidence","status","createdAt","updatedAt"]},"AcceptProposedFieldDto":{"type":"object","properties":{"signerId":{"type":"string","description":"Signer ID to assign the field to"},"required":{"type":"boolean","description":"Whether the signer must fill the accepted field(s). Defaults to true; radio-group options are always optional."},"groupRequired":{"type":"boolean","description":"Mark the accepted option(s) as a choose-one group requiring at least one selection before signing."}},"required":["signerId"]},"AcceptAllProposedFieldsDto":{"type":"object","properties":{"signerId":{"type":"string","description":"Signer ID to assign all fields to"},"minConfidence":{"type":"number","description":"Minimum confidence to accept (defaults to 70)"},"required":{"type":"boolean","description":"Whether the signer must fill the accepted field(s). Defaults to true; radio-group options are always optional."},"groupRequired":{"type":"boolean","description":"Mark the accepted option(s) as a choose-one group requiring at least one selection before signing."}},"required":["signerId"]},"AcceptAllResultDto":{"type":"object","properties":{"accepted":{"type":"number","description":"Number of fields accepted"},"rejected":{"type":"number","description":"Number of fields rejected"}},"required":["accepted","rejected"]},"AcceptTemplateProposedFieldDto":{"type":"object","properties":{"signerRoleId":{"type":"string","description":"Signer role ID to assign the field to"},"required":{"type":"boolean","description":"Whether the signer must fill the accepted field(s). Defaults to true; radio-group options are always optional."},"groupRequired":{"type":"boolean","description":"Mark the accepted option(s) as a choose-one group requiring at least one selection before signing."}}},"AcceptAllTemplateProposedFieldsDto":{"type":"object","properties":{"signerRoleId":{"type":"string","description":"Signer role ID to assign all fields to"},"minConfidence":{"type":"number","description":"Minimum confidence to accept (defaults to 70)"},"required":{"type":"boolean","description":"Whether the signer must fill the accepted field(s). Defaults to true; radio-group options are always optional."},"groupRequired":{"type":"boolean","description":"Mark the accepted option(s) as a choose-one group requiring at least one selection before signing."}}},"CreateSavedSignatureDto":{"type":"object","properties":{"email":{"type":"string","example":"ceo@company.com"},"name":{"type":"string","example":"Jane Smith"},"signatureImageUrl":{"type":"string","example":"data:image/png;base64,...","description":"Signature image as a base64 PNG data URL"},"kind":{"type":"string","description":"Whether this image is a full signature or a set of initials. They are adopted separately and stored as separate rows, so saving initials never replaces the signer's signature.","enum":["signature","initials"],"default":"signature"},"isDefault":{"type":"boolean","default":true}},"required":["email","name","signatureImageUrl"]},"SavedSignatureDto":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"signatureImageUrl":{"type":"string"},"kind":{"type":"string","enum":["signature","initials"]},"isDefault":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","email","name","signatureImageUrl","kind","isDefault","createdAt","updatedAt"]},"SigningPacketRecipientInputDto":{"type":"object","properties":{"name":{"type":"string","example":"Alex Manager","minLength":1},"email":{"type":"string","example":"alex@example.com"},"externalId":{"type":"string"}},"required":["name","email"]},"SigningPacketFieldValueInputDto":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid","description":"A field assigned to the item signer on the item document"},"value":{"type":"string","example":"250000.00","minLength":1,"description":"The value the recipient reviews but cannot change. Trimmed, must not be blank, and validated against the field like a signer-entered value (options, maxLength, inputMask, validationPattern). A checkbox can only be locked checked."}},"required":["fieldId","value"]},"SigningPacketItemInputDto":{"type":"object","properties":{"documentId":{"type":"string","format":"uuid"},"signerId":{"type":"string","format":"uuid"},"order":{"type":"number","minimum":1},"representedEntity":{"type":"string"},"signingCapacity":{"type":"string"},"fieldValues":{"maxItems":200,"description":"Values your backend fixes for the item signer before the packet is sent. Each field must belong to the item signer and be unfilled; signature, initials, shared-fill, choose-one group, and already filled fields are refused. Sending the packet writes the values and locks the fields, so the recipient sees them in the hosted ceremony but cannot change them. Other signers and their existing signatures are untouched.","type":"array","items":{"$ref":"#/components/schemas/SigningPacketFieldValueInputDto"}}},"required":["documentId","signerId"]},"CreateSigningPacketDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"sourceCollectionId":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Series A closing documents","minLength":1},"externalId":{"type":"string"},"recipient":{"$ref":"#/components/schemas/SigningPacketRecipientInputDto"},"accessMode":{"type":"string","enum":["email_verification","link"],"default":"email_verification"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SigningPacketItemInputDto"}},"redirectUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["name","recipient","items"]},"HostedSigningBrandDto":{"type":"object","properties":{"name":{"type":"string","description":"Partner identity shown in hosted signing"},"logoUrl":{"type":"string","format":"uri","nullable":true},"primaryColor":{"type":"string","nullable":true,"example":"#2563EB","description":"Accent color used for signing actions"}},"required":["name","logoUrl","primaryColor"]},"ElectronicDisclosureDto":{"type":"object","properties":{"provider":{"type":"string","enum":["korala","partner"]},"profileId":{"type":"string"},"version":{"type":"string"},"title":{"type":"string"},"contentHtml":{"type":"string","description":"Restricted, server-sanitized HTML"},"contentSha256":{"type":"string","description":"SHA-256 of the immutable disclosure snapshot"},"affirmationText":{"type":"string"}},"required":["provider","profileId","version","title","contentHtml","contentSha256","affirmationText"]},"SigningPacketRecipientDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["pending","viewed","completed"]},"consentedAt":{"type":"string","nullable":true}},"required":["id","name","email","status"]},"SigningPacketFieldValueDto":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid"},"value":{"type":"string"}},"required":["fieldId","value"]},"SigningPacketFieldDto":{"type":"object","properties":{"id":{"type":"string"},"documentId":{"type":"string"},"signerId":{"type":"string"},"fieldType":{"allOf":[{"$ref":"#/components/schemas/FieldType"}]},"pageNumber":{"type":"number"},"xPosition":{"type":"number"},"yPosition":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"label":{"type":"string","nullable":true,"description":"Human-readable label shown to the signer for this field"},"required":{"type":"string"},"value":{"type":"string","nullable":true},"editable":{"type":"boolean","description":"When true, a prefilled value is a suggestion the signer can change before signing."},"sharedFill":{"type":"boolean","description":"One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Never true on signature or initials fields."},"signingDate":{"type":"boolean","nullable":true,"description":"Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Null on a date made before the flag existed: a date on the signer’s own signature line is then the date of signing."},"signatureImageUrl":{"type":"string","nullable":true},"filledAt":{"format":"date-time","type":"string","nullable":true},"filledBy":{"nullable":true,"description":"Who wrote the current value: the sender (a non-editable template prefill or a signing-packet lock) or the signer (any fill, including bulk signing on their behalf). Null while unfilled.","allOf":[{"$ref":"#/components/schemas/FieldFilledBy"}]},"signingDateChangedAt":{"format":"date-time","type":"string","nullable":true,"description":"When the signer changed the date beside their signature from the automatic date of signing to one of their own. Null otherwise."},"acroFieldName":{"type":"string","nullable":true,"description":"Embedded AcroForm field this field is linked to; values fill the PDF form field at completion instead of being overlay-stamped."},"acroOptionValue":{"type":"string","nullable":true,"description":"For radio-group AcroForm fields: the option this field selects."},"options":{"nullable":true,"description":"Allowed values for dropdown fields","type":"array","items":{"type":"string"}},"maxLength":{"type":"number","nullable":true,"description":"Maximum characters accepted at fill time"},"inputMask":{"type":"string","example":"###-##-####","nullable":true,"description":"Input mask where # represents one digit"},"validationPattern":{"type":"string","nullable":true,"description":"Regex the filled value must match"},"validationMessage":{"type":"string","nullable":true,"description":"Signer-facing error when validationPattern does not match"},"dateFormat":{"type":"string","nullable":true,"description":"Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'"},"groupKey":{"type":"string","nullable":true},"groupRequired":{"type":"boolean","description":"Whether at least one member of this group must be selected"},"requiredWhenFieldId":{"type":"string","nullable":true,"format":"uuid","description":"Id of the field whose checked/filled state makes this field required (conditional requirement); null when unconditional"},"requiredWhenValue":{"type":"string","nullable":true,"description":"Exact controller value the condition triggers on; null means any checked/filled state"},"fontSize":{"type":"number","nullable":true,"example":9,"description":"Point size the value is drawn at, imported from the PDF form field. Null means the size is fitted to the box."},"textColor":{"type":"string","nullable":true,"example":"#000080","description":"Color the value is drawn in, as #rrggbb"},"textAlign":{"nullable":true,"description":"Horizontal alignment of the value inside the field box","allOf":[{"$ref":"#/components/schemas/TextAlign"}]},"fontFamily":{"type":"string","nullable":true,"example":"Helvetica-Bold","description":"Base font the value is drawn in, imported from the PDF form field"},"multiline":{"type":"boolean","description":"Whether the value may contain line breaks (a multiline form field)"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","documentId","signerId","fieldType","pageNumber","xPosition","yPosition","width","height","required","editable","sharedFill","groupRequired","multiline","createdAt","updatedAt"]},"SigningPacketItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"documentId":{"type":"string","format":"uuid"},"documentSignerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","signed","invalidated"]},"order":{"type":"number"},"documentName":{"type":"string"},"documentStatus":{"type":"string","enum":["draft","pending","completing","completed","failed","voided","expired"]},"signerStatus":{"type":"string","enum":["pending","viewed","signed","declined"]},"documentUrl":{"type":"string"},"signedDocumentUrl":{"type":"string","nullable":true},"certificateUrl":{"type":"string","nullable":true},"representedEntity":{"type":"string","nullable":true},"signingCapacity":{"type":"string","nullable":true},"fieldValues":{"description":"Values the sender locked for the item signer; applied to the fields when the packet is sent.","type":"array","items":{"$ref":"#/components/schemas/SigningPacketFieldValueDto"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SigningPacketFieldDto"}}},"required":["id","documentId","documentSignerId","status","order","documentName","documentStatus","signerStatus"]},"SigningPacketSavedSignatureDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"signatureImageUrl":{"type":"string"},"kind":{"type":"string","enum":["signature","initials"]}},"required":["id","name","signatureImageUrl","kind"]},"SigningPacketDto":{"type":"object","properties":{"sourceCollectionId":{"type":"string","format":"uuid","nullable":true},"id":{"type":"string","format":"uuid"},"publicId":{"type":"string","format":"uuid"},"name":{"type":"string"},"externalId":{"type":"string","nullable":true},"sandbox":{"type":"boolean"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"senderName":{"type":"string"},"senderOrganizationName":{"type":"string","nullable":true},"brand":{"nullable":true,"description":"Server-resolved partner branding for hosted signing","allOf":[{"$ref":"#/components/schemas/HostedSigningBrandDto"}]},"electronicDisclosure":{"$ref":"#/components/schemas/ElectronicDisclosureDto"},"status":{"type":"string","enum":["draft","sent","viewed","processing","partially_completed","recipient_completed","voided","expired"]},"accessMode":{"type":"string","enum":["email_verification","link"]},"recipient":{"$ref":"#/components/schemas/SigningPacketRecipientDto"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SigningPacketItemDto"}},"signingUrl":{"type":"string"},"certificateUrl":{"type":"string","nullable":true},"auditReportUrl":{"type":"string","nullable":true,"deprecated":true,"description":"Deprecated alias for certificateUrl"},"redirectUrl":{"type":"string","nullable":true},"savedSignature":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SigningPacketSavedSignatureDto"}]},"savedInitials":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SigningPacketSavedSignatureDto"}]},"deliveryStatus":{"type":"string","enum":["not_requested","sent","failed"]}},"required":["id","publicId","name","sandbox","senderName","electronicDisclosure","status","accessMode","recipient","items"]},"SigningPacketSummaryRecipientDto":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"}},"required":["name","email","status"]},"SigningPacketSummaryDto":{"type":"object","properties":{"sourceCollectionId":{"type":"string","format":"uuid","nullable":true},"id":{"type":"string","format":"uuid"},"publicId":{"type":"string","format":"uuid"},"name":{"type":"string"},"sandbox":{"type":"boolean"},"status":{"type":"string","enum":["draft","sent","viewed","processing","partially_completed","recipient_completed","voided","expired"]},"accessMode":{"type":"string","enum":["email_verification","link"]},"recipient":{"$ref":"#/components/schemas/SigningPacketSummaryRecipientDto"},"itemCount":{"type":"number"},"signedItemCount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"sentAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","publicId","name","sandbox","status","accessMode","recipient","itemCount","signedItemCount","createdAt","updatedAt"]},"PaginatedSigningPacketsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SigningPacketSummaryDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"EligiblePacketSignerDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["pending","viewed"]},"signingOrder":{"type":"number"}},"required":["id","name","email","status","signingOrder"]},"EligiblePacketDocumentDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sandbox":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"signers":{"type":"array","items":{"$ref":"#/components/schemas/EligiblePacketSignerDto"}}},"required":["id","name","sandbox","createdAt","signers"]},"PaginatedEligiblePacketDocumentsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EligiblePacketDocumentDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"UpdateSigningPacketDto":{"type":"object","properties":{"name":{"type":"string","minLength":1},"redirectUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"SendSigningPacketDto":{"type":"object","properties":{"electronicDisclosure":{"$ref":"#/components/schemas/ElectronicDisclosureProfileDto"},"delivery":{"type":"string","enum":["email","none"],"default":"email"}}},"SigningPacketAuditEventDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string","enum":["created","updated","sent","reminder_sent","viewed","consent_accepted","completion_accepted","completion_finished","voided","expired"]},"actorType":{"type":"string"},"actorId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","eventType","actorType","createdAt"]},"SigningPacketAuditDto":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/SigningPacketAuditEventDto"}},"certificateUrl":{"type":"string","nullable":true},"reportUrl":{"type":"string","nullable":true,"deprecated":true,"description":"Deprecated alias for certificateUrl"}},"required":["events"]},"CreateWorkflowDefinitionDto":{"type":"object","properties":{"name":{"type":"string","example":"Proof of Address Extraction"},"slug":{"type":"string","example":"proof-of-address"},"description":{"type":"string","example":"Extract and validate proof of address documents"},"steps":{"description":"Array of step configurations","example":[{"type":"capture","config":{"acceptedTypes":["application/pdf"],"maxSizeMb":10}},{"type":"ocr","config":{"provider":"auto"}}],"type":"array","items":{"type":"string"}},"inputSchema":{"type":"object","additionalProperties":true,"description":"Expected input schema (JSON Schema format)"},"outputSchema":{"type":"object","additionalProperties":true,"description":"Expected output schema (JSON Schema format)"},"isPublic":{"type":"boolean","description":"Whether this workflow is publicly accessible for demos","default":false}},"required":["name","slug","steps"]},"WorkflowStepType":{"type":"string","enum":["capture","ocr","extract","validate","enrich","check","risk","output","review","webhook"]},"WorkflowStepDto":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/WorkflowStepType"}]},"config":{"type":"object","additionalProperties":true}},"required":["type","config"]},"WorkflowDefinitionDto":{"type":"object","properties":{"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"organizationId":{"type":"string","nullable":true},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStepDto"}},"inputSchema":{"type":"object","additionalProperties":true,"nullable":true},"outputSchema":{"type":"object","additionalProperties":true,"nullable":true},"isPublic":{"type":"boolean"},"isActive":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string","description":"When what a run executes last changed: the steps, the input or output schema, or the slug. A rename, a new description or switching the workflow on or off leaves it alone."}},"required":["sandbox","id","name","slug","steps","isPublic","isActive","createdAt","updatedAt"]},"PaginatedWorkflowDefinitionsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDefinitionDto"}},"total":{"type":"number","description":"Total number of workflows"},"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["data","total","page","limit","totalPages"]},"UpdateWorkflowDefinitionDto":{"type":"object","properties":{"name":{"type":"string","example":"Updated Workflow Name"},"slug":{"type":"string","example":"updated-slug"},"description":{"type":"string","example":"Updated description"},"steps":{"description":"Array of step configurations","type":"array","items":{"type":"string"}},"inputSchema":{"type":"object","additionalProperties":true,"description":"Expected input schema (JSON Schema format)"},"outputSchema":{"allOf":[{"type":"object","additionalProperties":true}],"nullable":true,"description":"Expected output schema (JSON Schema format). null removes the stored schema; leaving it out keeps it."},"isPublic":{"type":"boolean","description":"Whether this workflow is publicly accessible"},"isActive":{"type":"boolean","description":"Whether this workflow is active"}}},"StartWorkflowRunDto":{"type":"object","properties":{"inputData":{"type":"object","additionalProperties":true,"description":"Additional input data for the workflow","example":{"customField":"value"}}}},"CaptureChallengeDto":{"type":"object","properties":{"recordingSlotKey":{"type":"string","description":"Slot for the continuous selfie recording, when required"},"version":{"type":"number","enum":[1]},"id":{"type":"string","format":"uuid"},"workflowRunId":{"type":"string","format":"uuid"},"slotOrder":{"type":"array","items":{"type":"string"}},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}},"required":["version","id","workflowRunId","slotOrder","issuedAt","expiresAt"]},"ArtifactCameraConfigDto":{"type":"object","properties":{"preferredFacing":{"type":"string","enum":["environment","user"]},"outputFormat":{"type":"string","enum":["image/jpeg","image/png"]},"outputQuality":{"type":"number"},"maxResolution":{"type":"number"}}},"ArtifactUploadPlanDto":{"type":"object","properties":{"livenessRecording":{"type":"boolean","description":"Capture a continuous video alongside the posed selfies"},"captureChallenge":{"description":"Server-issued selfie submission challenge. Resume invalidates the previous challenge and requires recapture. This does not establish liveness.","allOf":[{"$ref":"#/components/schemas/CaptureChallengeDto"}]},"slotKey":{"type":"string"},"label":{"type":"string","nullable":true},"required":{"type":"boolean"},"acceptedTypes":{"type":"array","items":{"type":"string"}},"maxSizeMb":{"type":"number"},"inputModes":{"type":"array","items":{"type":"string"}},"uploadUrl":{"type":"string","description":"Pre-signed URL to upload the artifact"},"key":{"type":"string","description":"Storage key for the uploaded artifact"},"livenessPose":{"type":"string","enum":["straight","left","right"],"nullable":true,"description":"For a liveness challenge: the face pose this capture asks for"},"cameraConfig":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ArtifactCameraConfigDto"}]},"uploaded":{"type":"boolean","description":"A file is already in place for this slot (uploaded before the run was resumed, perhaps on another device); include the slot when confirming, but do not upload it again"},"livenessSession":{"type":"boolean","description":"Filled by a live camera check session instead of an upload: open one with the liveness start route, run the check, then call the liveness complete route. uploadUrl is empty for this slot."}},"required":["slotKey","required","acceptedTypes","maxSizeMb","inputModes","uploadUrl","key"]},"WorkflowRunStatus":{"type":"string","enum":["pending","running","paused","completed","failed"]},"StartWorkflowRunResponseDto":{"type":"object","properties":{"runId":{"type":"string","description":"The workflow run ID to poll for status"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactUploadPlanDto"}},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowRunStatus"}]}},"required":["runId","artifacts","status"]},"WorkflowRunDto":{"type":"object","properties":{"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"workflowDefinitionId":{"type":"string"},"organizationId":{"type":"string","nullable":true},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowRunStatus"}]},"inputData":{"type":"object","additionalProperties":true,"nullable":true},"outputData":{"type":"object","additionalProperties":true,"nullable":true},"currentStep":{"type":"number"},"errorMessage":{"type":"string","nullable":true},"inputFileUrl":{"type":"string","nullable":true},"inputFileMimeType":{"type":"string","nullable":true},"startedAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"}},"required":["sandbox","id","workflowDefinitionId","status","currentStep","createdAt"]},"PaginatedWorkflowRunsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunDto"}},"total":{"type":"number","description":"Total number of runs"},"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["data","total","page","limit","totalPages"]},"WorkflowStepRunStatus":{"type":"string","enum":["pending","running","paused","completed","failed","skipped"]},"WorkflowStepRunDto":{"type":"object","properties":{"id":{"type":"string"},"workflowRunId":{"type":"string"},"stepIndex":{"type":"number"},"stepType":{"allOf":[{"$ref":"#/components/schemas/WorkflowStepType"}]},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowStepRunStatus"}]},"inputData":{"type":"object","additionalProperties":true,"nullable":true},"outputData":{"type":"object","additionalProperties":true,"nullable":true},"errorMessage":{"type":"string","nullable":true},"processingTimeMs":{"type":"number","nullable":true},"createdAt":{"format":"date-time","type":"string"},"completedAt":{"format":"date-time","type":"string","nullable":true}},"required":["id","workflowRunId","stepIndex","stepType","status","createdAt"]},"WorkflowRunWithStepsDto":{"type":"object","properties":{"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"workflowDefinitionId":{"type":"string"},"organizationId":{"type":"string","nullable":true},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowRunStatus"}]},"inputData":{"type":"object","additionalProperties":true,"nullable":true},"outputData":{"type":"object","additionalProperties":true,"nullable":true},"currentStep":{"type":"number"},"errorMessage":{"type":"string","nullable":true},"inputFileUrl":{"type":"string","nullable":true},"inputFileMimeType":{"type":"string","nullable":true},"startedAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"stepRuns":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStepRunDto"}}},"required":["sandbox","id","workflowDefinitionId","status","currentStep","createdAt","stepRuns"]},"ConfirmArtifactUploadDto":{"type":"object","properties":{"captureChallengeId":{"type":"string","description":"Required for slots with a captureChallenge in their upload plan."},"slotKey":{"type":"string"},"contentType":{"type":"string","nullable":true},"captureMode":{"type":"string","nullable":true}},"required":["slotKey"]},"ConfirmWorkflowUploadDto":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":true,"description":"Additional metadata about the upload"},"artifacts":{"description":"Artifact batch metadata for multi-artifact workflows","type":"array","items":{"$ref":"#/components/schemas/ConfirmArtifactUploadDto"}}}},"WorkflowArtifactStatus":{"type":"string","enum":["planned","uploaded"]},"WorkflowRunArtifactDto":{"type":"object","properties":{"id":{"type":"string"},"workflowRunId":{"type":"string"},"slotKey":{"type":"string"},"label":{"type":"string","nullable":true},"mimeType":{"type":"string","nullable":true},"captureMode":{"type":"string","nullable":true},"sizeBytes":{"type":"number","nullable":true},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowArtifactStatus"}]},"url":{"type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"uploadedAt":{"format":"date-time","type":"string","nullable":true}},"required":["id","workflowRunId","slotKey","status","createdAt"]},"ReviewWorkflowStepDto":{"type":"object","properties":{"action":{"type":"string","enum":["approve","reject"],"description":"Whether to approve or reject the review"},"stepRunId":{"type":"string","format":"uuid","description":"Exact paused step being reviewed. Supply it for safe retries; required after any earlier review has been decided on this run."},"editedData":{"type":"object","additionalProperties":true,"description":"Edited field values (only for approve)"},"reason":{"type":"string","description":"Reason for rejection (only for reject)"}},"required":["action"]},"SessionParticipantRole":{"type":"string","enum":["subject","beneficial_owner","controller","director","representative"]},"CreateSessionParticipantDto":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/SessionParticipantRole"}]},"displayName":{"type":"string"},"externalParticipantId":{"type":"string"},"data":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true}},"required":["role"]},"CreateSessionDto":{"type":"object","properties":{"originContextId":{"type":"string","description":"Registered risk context that initiated this session. Requires subjectId and context membership. Origin does not restrict evidence reuse or enable context evaluation."},"subjectId":{"type":"string","description":"Korala risk subject ID. Must match externalUserId, customer type, organization and environment."},"externalUserId":{"type":"string","description":"Partner's user identifier","example":"usr_abc123"},"configurationSlug":{"type":"string","description":"Slug of the session configuration to use","example":"kyc-standard"},"context":{"type":"object","additionalProperties":true,"description":"Session-level context data available to all workflows (e.g., user profile data)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary metadata attached to the session"},"participants":{"description":"Participants attached to this session or compliance case","type":"array","items":{"$ref":"#/components/schemas/CreateSessionParticipantDto"}},"expiresInMinutes":{"type":"number","description":"Session expiration in minutes from creation (default: 1440 = 24h)","example":1440},"redirectUrl":{"type":"string","description":"URL to redirect the user after session completion","example":"https://partner.com/verification/complete"}},"required":["externalUserId","configurationSlug"]},"SubjectKind":{"type":"string","enum":["individual","business"]},"SessionStatus":{"type":"string","enum":["created","in_progress","pending_review","completed","expired","failed"]},"SessionResolution":{"type":"string","enum":["approved","rejected"]},"RiskLevel":{"type":"string","enum":["low","medium","high"]},"RiskKind":{"type":"string","enum":["sybil","velocity","duplicate_document","device_cluster","location_cluster","network_mismatch"]},"RiskFindingSeverity":{"type":"string","enum":["low","medium","high"]},"RiskFindingDto":{"type":"object","properties":{"code":{"type":"string"},"severity":{"allOf":[{"$ref":"#/components/schemas/RiskFindingSeverity"}]},"entityType":{"type":"string"},"observedAt":{"type":"string","description":"ISO 8601 timestamp"},"entityId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true}},"required":["code","severity","entityType","observedAt","metadata"]},"RiskAssessmentDto":{"type":"object","properties":{"kind":{"example":"sybil","allOf":[{"$ref":"#/components/schemas/RiskKind"}]},"score":{"type":"number","minimum":0,"maximum":100},"level":{"allOf":[{"$ref":"#/components/schemas/RiskLevel"}]},"reasons":{"type":"array","items":{"type":"string"}},"findingCount":{"type":"number"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/RiskFindingDto"}},"metrics":{"type":"object","additionalProperties":true},"manualReviewRecommended":{"type":"boolean"}},"required":["kind","score","level","reasons","findingCount","findings","metrics","manualReviewRecommended"]},"SessionDecisionFindingDto":{"type":"object","properties":{"code":{"type":"string","description":"Korala reason code, family.name (for example screening.sanctions_match)"},"effect":{"type":"string","enum":["decline","review","resubmit"]},"checkId":{"type":"string","nullable":true,"description":"The check that produced this finding; null for a session-level finding (missing evidence, duplicate identity, validation, a required manual decision)."}},"required":["code","effect","checkId"]},"SessionDecisionAttemptDto":{"type":"object","properties":{"sessionWorkflowId":{"type":"string"},"workflowRunId":{"type":"string"},"attempt":{"type":"number","nullable":true,"description":"The run's stored attempt number. Null only if the run was never numbered (a broken invariant). When Korala decides automatically it then records data.attempt_unnumbered: an approval or resubmission goes to review with the code in codes, a review gains it in codes, and beside a definite decline it sits in findings (not codes) while the decline stands. With no automatic decision there is no record. A reviewer's or partner's decision stands and simply cites null. A decision an older version of Korala made cites that version's attempt counter."}},"required":["sessionWorkflowId","workflowRunId","attempt"]},"SessionDecisionResubmissionWorkflowDto":{"type":"object","properties":{"sessionWorkflowId":{"type":"string","description":"A workflow the person is asked to redo"},"attemptsRemaining":{"type":"number","description":"Attempts the person has left on it"}},"required":["sessionWorkflowId","attemptsRemaining"]},"SessionDecisionResubmissionDto":{"type":"object","properties":{"sessionWorkflowId":{"type":"string","description":"The earliest workflow the person is asked to redo"},"attemptsRemaining":{"type":"number","description":"The fewest attempts the person has left on any workflow asked for again"},"workflows":{"description":"Every workflow asked for again, earliest first","type":"array","items":{"$ref":"#/components/schemas/SessionDecisionResubmissionWorkflowDto"}}},"required":["sessionWorkflowId","attemptsRemaining"]},"SessionDecisionIdentityAcrossAttemptsDto":{"type":"object","properties":{"status":{"type":"string","enum":["same","changed","unknown"],"description":"changed: a different person (code duplicate.identity_changed_between_attempts; the switch itself never declines, while a definite decline from a check set to block still declines, with the switch among decision.codes); unknown: a field either attempt left unread, so not compared; same: name and date of birth agree"},"signals":{"type":"array","description":"What showed a change: name_and_date_of_birth, both differ; document_number, another document (number and issuing country) whose name differs while the date of birth is not shown to agree (unread on either); document_and_date_of_birth, another document with another date of birth, whatever the name (two people of one name)","items":{"type":"string","enum":["name_and_date_of_birth","document_number","document_and_date_of_birth"]}}},"required":["status","signals"]},"SessionDecisionDto":{"type":"object","properties":{"outcome":{"type":"string","enum":["approved","rejected","review","resubmit"]},"decidedBy":{"type":"string","enum":["auto","reviewer","partner"],"description":"auto: Korala decided; reviewer: someone in the dashboard; partner: your integration through the API"},"decidedAt":{"type":"string"},"rulesVersion":{"type":"string","example":"korala-decisions-v2","description":"The rules that made the decision. v2 adds the identity switch between attempts and the unnumbered-attempt rule; records made under v1 keep it."},"reasonCodesVersion":{"type":"string","example":"korala-reasons-v1"},"codes":{"description":"Why: the decline codes of a rejection, or the codes holding a session in review","type":"array","items":{"type":"string"}},"decidingCheckIds":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/SessionDecisionFindingDto"}},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/SessionDecisionAttemptDto"}},"resubmission":{"$ref":"#/components/schemas/SessionDecisionResubmissionDto"},"identityAcrossAttempts":{"description":"Whether the judged attempts' identity documents show the same person as the session's earlier attempts. Present only when an earlier attempt had an identity document.","allOf":[{"$ref":"#/components/schemas/SessionDecisionIdentityAcrossAttemptsDto"}]}},"required":["outcome","decidedBy","decidedAt","rulesVersion","reasonCodesVersion","codes","decidingCheckIds","findings","attempts"]},"SessionParticipantDto":{"type":"object","properties":{"id":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/SessionParticipantRole"}]},"displayName":{"type":"string","nullable":true},"externalParticipantId":{"type":"string","nullable":true},"data":{"type":"object","additionalProperties":true,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","role","createdAt","updatedAt"]},"SessionWorkflowStatus":{"type":"string","enum":["pending","in_progress","completed","failed","resubmit_required"]},"SessionDocumentChoiceDto":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"type":{"type":"string","enum":["passport","national_id","driving_license"]}},"required":["country","type"]},"SessionWorkflowAttemptDto":{"type":"object","properties":{"workflowRunId":{"type":"string"},"attemptNumber":{"type":"number","nullable":true,"description":"Which attempt this run is, from 1, in the order the runs were claimed, never rewritten. A run an older version of Korala started during an upgrade is numbered when the next run of this workflow starts or the session is next decided, so it can be numbered after a newer run and numbers need not follow startedAt. Until then it is null and listed after the numbered ones, by startedAt: never a number that changes later. If an older version of Korala made the last decision on the session, earlier runs can stay unnumbered (nothing later claims or decides on them), and that decision cites the attempt counter of that version. A decision this version makes cites the stored number, or null where an invariant broke (see decision.attempts[].attempt). A workflow redone because an earlier one changed keeps counting here, while its attemptCount (the cap) starts again."},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowRunStatus"}]},"startedAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"resubmissionReasons":{"nullable":true,"description":"The capture reason codes Korala asked for this attempt again with. Null for the current attempt, for one the partner asked for again, and for attempts from before this was recorded.","type":"array","items":{"type":"string"}},"documentChoice":{"nullable":true,"description":"The document the person chose for this attempt, if asked","allOf":[{"$ref":"#/components/schemas/SessionDocumentChoiceDto"}]},"checkIds":{"description":"Ids of this attempt's checks in the session's checks, current and superseded alike","type":"array","items":{"type":"string"}}},"required":["workflowRunId","attemptNumber","status","checkIds"]},"SessionWorkflowDto":{"type":"object","properties":{"id":{"type":"string"},"workflowDefinitionId":{"type":"string"},"workflowName":{"type":"string","nullable":true},"workflowSlug":{"type":"string","nullable":true},"workflowRunId":{"type":"string","nullable":true},"outputKey":{"type":"string"},"participantId":{"type":"string","nullable":true},"participantRole":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SessionParticipantRole"}]},"participantDisplayName":{"type":"string","nullable":true},"order":{"type":"number"},"status":{"allOf":[{"$ref":"#/components/schemas/SessionWorkflowStatus"}]},"context":{"type":"object","additionalProperties":true,"nullable":true},"attemptCount":{"type":"number"},"maxAttempts":{"type":"number"},"resubmissionReasons":{"nullable":true,"description":"Why Korala asked for this workflow again: capture reason codes the person can act on (capture.document_expired, capture.document_unsupported, capture.image_unreadable, capture.side_missing, capture.file_too_large). Kept while the redo runs and cleared when the workflow next completes. Null when nobody asked, or when the partner did.","type":"array","items":{"type":"string"}},"documentChoice":{"nullable":true,"description":"On the session link only: the document chosen for a run still waiting for its uploads, so another device continues with it","allOf":[{"$ref":"#/components/schemas/SessionDocumentChoiceDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"attempts":{"description":"Every attempt at this workflow, ordered by attemptNumber, then any not yet numbered by startedAt, the current one included. On the organisation's session responses (GET, create, resolve, resubmit), never on the person's session link. An earlier attempt is one a resubmission replaced: its checks are the session's checks with supersededAt set.","type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowAttemptDto"}}},"required":["id","workflowDefinitionId","outputKey","order","status","attemptCount","maxAttempts","createdAt","updatedAt"]},"CheckKind":{"type":"string","enum":["document_authenticity","face_match","passive_liveness","active_liveness","database_identity","aml_screening","business_registry","tax_id","individual_identity","pep_sanctions","adverse_media","ubo_lookup"]},"CheckStatus":{"type":"string","enum":["clear","match","review_required","error"]},"CheckBlockingMode":{"type":"string","enum":["none","manual_review","block"]},"SessionCheckMatchDto":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string"},"score":{"type":"number","nullable":true},"category":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true}},"required":["label"]},"SessionCheckDto":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sessionWorkflowId":{"type":"string","nullable":true},"participantId":{"type":"string","nullable":true},"checkKind":{"allOf":[{"$ref":"#/components/schemas/CheckKind"}]},"provider":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/CheckStatus"}]},"score":{"type":"number","nullable":true},"blockingMode":{"allOf":[{"$ref":"#/components/schemas/CheckBlockingMode"}]},"reviewThreshold":{"allOf":[{"$ref":"#/components/schemas/RiskLevel"}]},"reviewRecommended":{"type":"boolean"},"providerRef":{"type":"string","nullable":true},"matches":{"type":"array","items":{"$ref":"#/components/schemas/SessionCheckMatchDto"}},"reasons":{"type":"array","items":{"type":"string"}},"rawResultRedacted":{"type":"object","additionalProperties":true,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"supersededAt":{"format":"date-time","type":"string","nullable":true,"description":"When a resubmission replaced the attempt this check judged. A superseded check is an earlier attempt, kept as evidence: it no longer decides the session. Integrations must ignore checks with supersededAt set when judging the session."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","sessionId","checkKind","provider","status","blockingMode","reviewThreshold","reviewRecommended","matches","reasons","createdAt","updatedAt"]},"SessionDetailDto":{"type":"object","properties":{"originContextId":{"type":"string","nullable":true,"description":"Registered originating risk context; null when none was linked. This association does not determine evidence applicability."},"subjectId":{"type":"string","nullable":true,"description":"Explicitly linked Korala risk subject ID; null for unlinked sessions."},"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"organizationId":{"type":"string"},"externalUserId":{"type":"string"},"subjectKind":{"allOf":[{"$ref":"#/components/schemas/SubjectKind"}]},"finalManualReviewRequired":{"type":"boolean"},"accessToken":{"type":"string","description":"Access token for end-user access"},"status":{"allOf":[{"$ref":"#/components/schemas/SessionStatus"}]},"resolution":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SessionResolution"}]},"resolutionReason":{"type":"string","nullable":true},"resolvedAt":{"format":"date-time","type":"string","nullable":true},"resolvedBy":{"type":"string","nullable":true},"riskScore":{"type":"number","nullable":true},"riskLevel":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskLevel"}]},"riskSummary":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskAssessmentDto"}]},"eventVersion":{"type":"number","description":"Grows with each change announced by a session webhook; compare it with the webhook's `data.version`. The higher number is the newer state; numbers may skip."},"decision":{"nullable":true,"description":"The structured decision: outcome, reason codes, deciding checks, attempts, who decided and under which rules. Null until something is decided.","allOf":[{"$ref":"#/components/schemas/SessionDecisionDto"}]},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"context":{"type":"object","additionalProperties":true,"nullable":true},"accumulatedData":{"type":"object","additionalProperties":true,"nullable":true},"expiresAt":{"format":"date-time","type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"startedAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/SessionParticipantDto"}},"workflows":{"type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowDto"}},"checks":{"type":"array","items":{"$ref":"#/components/schemas/SessionCheckDto"}}},"required":["sandbox","id","organizationId","externalUserId","subjectKind","finalManualReviewRequired","accessToken","status","eventVersion","createdAt","updatedAt","participants","workflows","checks"]},"SessionDto":{"type":"object","properties":{"originContextId":{"type":"string","nullable":true,"description":"Registered originating risk context; null when none was linked. This association does not determine evidence applicability."},"subjectId":{"type":"string","nullable":true,"description":"Explicitly linked Korala risk subject ID; null for unlinked sessions."},"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"organizationId":{"type":"string"},"externalUserId":{"type":"string"},"subjectKind":{"allOf":[{"$ref":"#/components/schemas/SubjectKind"}]},"finalManualReviewRequired":{"type":"boolean"},"accessToken":{"type":"string","description":"Access token for end-user access"},"status":{"allOf":[{"$ref":"#/components/schemas/SessionStatus"}]},"resolution":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SessionResolution"}]},"resolutionReason":{"type":"string","nullable":true},"resolvedAt":{"format":"date-time","type":"string","nullable":true},"resolvedBy":{"type":"string","nullable":true},"riskScore":{"type":"number","nullable":true},"riskLevel":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskLevel"}]},"riskSummary":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RiskAssessmentDto"}]},"eventVersion":{"type":"number","description":"Grows with each change announced by a session webhook; compare it with the webhook's `data.version`. The higher number is the newer state; numbers may skip."},"decision":{"nullable":true,"description":"The structured decision: outcome, reason codes, deciding checks, attempts, who decided and under which rules. Null until something is decided.","allOf":[{"$ref":"#/components/schemas/SessionDecisionDto"}]},"metadata":{"type":"object","additionalProperties":true,"nullable":true},"context":{"type":"object","additionalProperties":true,"nullable":true},"accumulatedData":{"type":"object","additionalProperties":true,"nullable":true},"expiresAt":{"format":"date-time","type":"string","nullable":true},"redirectUrl":{"type":"string","nullable":true},"startedAt":{"format":"date-time","type":"string","nullable":true},"completedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["sandbox","id","organizationId","externalUserId","subjectKind","finalManualReviewRequired","accessToken","status","eventVersion","createdAt","updatedAt"]},"PaginatedSessionsDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionDto"}},"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","limit","totalPages"]},"ResolveSessionDto":{"type":"object","properties":{"resolution":{"description":"Resolution decision","allOf":[{"$ref":"#/components/schemas/SessionResolution"}]},"reason":{"type":"string","description":"Reason for the resolution","example":"Documents verified successfully"}},"required":["resolution"]},"ResubmitSessionWorkflowDto":{"type":"object","properties":{"reopen":{"type":"boolean","description":"Reopen a session a reviewer or your integration already decided. Without it, a resubmission on a manually decided session is refused (409).","default":false}}},"SessionWorkflowArtifactListDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunArtifactDto"}}},"required":["data"]},"SessionWorkflowBindingDto":{"type":"object","properties":{"workflowSlug":{"type":"string"},"participantRoles":{"type":"array","items":{"$ref":"#/components/schemas/SessionParticipantRole"}},"outputKey":{"type":"string"},"context":{"type":"object","additionalProperties":true},"maxAttempts":{"type":"number"}},"required":["workflowSlug"]},"CreateSessionConfigurationDto":{"type":"object","properties":{"name":{"type":"string","example":"KYC Standard"},"slug":{"type":"string","example":"kyc-standard"},"description":{"type":"string","example":"Identity document + proof of address"},"workflowSlugs":{"description":"Ordered array of workflow slugs","example":["id-document","proof-of-address"],"type":"array","items":{"type":"string"}},"workflowBindings":{"description":"Expanded workflow bindings. When omitted, workflowSlugs are used as one binding each.","type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowBindingDto"}},"subjectKind":{"default":"individual","allOf":[{"$ref":"#/components/schemas/SubjectKind"}]},"isVerification":{"type":"boolean","description":"Enable resolution (approved/rejected)","default":true},"autoResolve":{"type":"boolean","description":"Auto-resolve based on validation results","default":true},"finalManualReviewRequired":{"type":"boolean","description":"Require explicit partner approval or decline after workflow completion","default":false},"defaultExpiresInMinutes":{"type":"number","description":"Default session expiration in minutes","default":1440},"defaultRedirectUrl":{"type":"string","description":"Default redirect URL after session completion"}},"required":["name","slug"]},"SessionConfigurationDto":{"type":"object","properties":{"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"workflowSlugs":{"type":"array","items":{"type":"string"}},"workflowBindings":{"type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowBindingDto"}},"subjectKind":{"allOf":[{"$ref":"#/components/schemas/SubjectKind"}]},"isVerification":{"type":"boolean"},"autoResolve":{"type":"boolean"},"finalManualReviewRequired":{"type":"boolean"},"defaultExpiresInMinutes":{"type":"number","nullable":true},"defaultRedirectUrl":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["sandbox","id","organizationId","name","slug","workflowSlugs","workflowBindings","subjectKind","isVerification","autoResolve","finalManualReviewRequired","isActive","createdAt","updatedAt"]},"UpdateSessionConfigurationDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"workflowSlugs":{"type":"array","items":{"type":"string"}},"workflowBindings":{"type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowBindingDto"}},"subjectKind":{"allOf":[{"$ref":"#/components/schemas/SubjectKind"}]},"isVerification":{"type":"boolean"},"autoResolve":{"type":"boolean"},"finalManualReviewRequired":{"type":"boolean"},"defaultExpiresInMinutes":{"type":"number"},"defaultRedirectUrl":{"type":"string"},"isActive":{"type":"boolean"}}},"SessionAccessParticipantDto":{"type":"object","properties":{"id":{"type":"string"},"role":{"allOf":[{"$ref":"#/components/schemas/SessionParticipantRole"}]},"displayName":{"type":"string","nullable":true}},"required":["id","role"]},"SessionAccessWorkflowDto":{"type":"object","properties":{"id":{"type":"string"},"workflowDefinitionId":{"type":"string"},"workflowName":{"type":"string","nullable":true},"workflowSlug":{"type":"string","nullable":true},"workflowRunId":{"type":"string","nullable":true},"outputKey":{"type":"string"},"participantId":{"type":"string","nullable":true},"participantRole":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SessionParticipantRole"}]},"participantDisplayName":{"type":"string","nullable":true},"order":{"type":"number"},"status":{"allOf":[{"$ref":"#/components/schemas/SessionWorkflowStatus"}]},"context":{"type":"object","additionalProperties":true,"nullable":true},"attemptCount":{"type":"number"},"maxAttempts":{"type":"number"},"resubmissionReasons":{"nullable":true,"description":"Why Korala asked for this workflow again: capture reason codes the person can act on (capture.document_expired, capture.document_unsupported, capture.image_unreadable, capture.side_missing, capture.file_too_large). Kept while the redo runs and cleared when the workflow next completes. Null when nobody asked, or when the partner did.","type":"array","items":{"type":"string"}},"documentChoice":{"nullable":true,"description":"On the session link only: the document chosen for a run still waiting for its uploads, so another device continues with it","allOf":[{"$ref":"#/components/schemas/SessionDocumentChoiceDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","workflowDefinitionId","outputKey","order","status","attemptCount","maxAttempts","createdAt","updatedAt"]},"SessionAccessDto":{"type":"object","properties":{"sandbox":{"type":"boolean","description":"Persisted execution mode: true for test data","readOnly":true},"id":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/SessionStatus"}]},"resolution":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SessionResolution"}]},"redirectUrl":{"type":"string","nullable":true},"expiresAt":{"format":"date-time","type":"string","nullable":true},"participants":{"type":"array","items":{"$ref":"#/components/schemas/SessionAccessParticipantDto"}},"workflows":{"description":"Ordered list of workflows in this session","type":"array","items":{"$ref":"#/components/schemas/SessionAccessWorkflowDto"}},"currentWorkflow":{"nullable":true,"description":"The next workflow the user should work on","allOf":[{"$ref":"#/components/schemas/SessionAccessWorkflowDto"}]}},"required":["sandbox","id","status","participants","workflows"]},"SessionHandoffDto":{"type":"object","properties":{"url":{"type":"string","description":"Opens the session on another device; valid for ten minutes. Carries no access token."},"qrDataUrl":{"type":"string","description":"The same link as a PNG data URL QR code"},"expiresAt":{"format":"date-time","type":"string"}},"required":["url","qrDataUrl","expiresAt"]},"SessionHandoffRedeemedDto":{"type":"object","properties":{"accessToken":{"type":"string","description":"The access token of the session the link opens"}},"required":["accessToken"]},"StartSessionWorkflowDto":{"type":"object","properties":{"inputData":{"type":"object","additionalProperties":true,"description":"Additional input for this workflow run. It reaches the run as inputData.endUserInput, beside the data the session, earlier workflows and the binding provide, and never replaces any of it. Where the binding context has documentChoice: true, it must carry document: { country (ISO 3166-1 alpha-2), type (passport | national_id | driving_license) }, which decides the capture slots; elsewhere document is ignored."}}},"StartSessionWorkflowResponseDto":{"type":"object","properties":{"runId":{"type":"string","description":"The workflow run ID to poll for status"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactUploadPlanDto"}}},"required":["runId","artifacts"]},"ReportedDeviceSignalsDto":{"type":"object","properties":{"browserInstallationId":{"type":"string","description":"Random identifier kept by this browser installation. It may be cleared or forged; the server hashes it before storage."},"language":{"type":"string"},"timezone":{"type":"string"},"screenWidth":{"type":"number"},"screenHeight":{"type":"number"},"pixelRatio":{"type":"number"},"hardwareConcurrency":{"type":"number"},"maxTouchPoints":{"type":"number"},"webglRenderer":{"type":"string"},"webdriver":{"type":"boolean"}},"required":["language","timezone","screenWidth","screenHeight","pixelRatio","maxTouchPoints"]},"ConfirmSessionWorkflowUploadDto":{"type":"object","properties":{"contentType":{"type":"string","description":"Content type of the uploaded file","example":"application/pdf"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ConfirmArtifactUploadDto"}},"deviceSignals":{"description":"Browser-reported signals from the device confirming a verification capture. Used only as a review candidate; not a device identity assertion.","allOf":[{"$ref":"#/components/schemas/ReportedDeviceSignalsDto"}]}}},"StartLivenessSessionDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Client attempt UUID. Reuse only when retrying the same start request.","format":"uuid"},"slotKey":{"type":"string","description":"The capture slot flagged livenessSession"}},"required":["slotKey"]},"LivenessStreamingCredentialsDto":{"type":"object","properties":{"accessKeyId":{"type":"string"},"secretAccessKey":{"type":"string"},"sessionToken":{"type":"string"},"expiration":{"type":"string","format":"date-time"}},"required":["accessKeyId","secretAccessKey","sessionToken","expiration"]},"LivenessSessionDto":{"type":"object","properties":{"sessionId":{"type":"string","description":"The live camera check session the browser streams to"},"region":{"type":"string","description":"Processing region for the live camera check"},"credentials":{"description":"Temporary credentials that can only stream a Face Liveness session, valid 15 minutes","allOf":[{"$ref":"#/components/schemas/LivenessStreamingCredentialsDto"}]},"attempt":{"type":"number","description":"This attempt, starting at 1"},"attemptsRemaining":{"type":"number","description":"Attempts left after this one"}},"required":["sessionId","region","credentials","attempt","attemptsRemaining"]},"CompleteLivenessSessionDto":{"type":"object","properties":{"slotKey":{"type":"string","description":"The capture slot flagged livenessSession"},"sessionId":{"type":"string","description":"The session id the start route returned"}},"required":["slotKey","sessionId"]},"LivenessSessionOutcomeDto":{"type":"object","properties":{"status":{"type":"string","enum":["succeeded","failed","expired","incomplete"],"description":"succeeded: the reference frame is stored and the slot counts as captured. Anything else can be retried while attempts remain."},"attemptsRemaining":{"type":"number","description":"Attempts left"},"feedback":{"description":"Retry guidance for the camera check, such as low lighting","type":"array","items":{"type":"string"}}},"required":["status","attemptsRemaining","feedback"]},"SessionWorkflowStepStatusDto":{"type":"object","properties":{"id":{"type":"string"},"stepType":{"allOf":[{"$ref":"#/components/schemas/WorkflowStepType"}]},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowStepRunStatus"}]}},"required":["id","stepType","status"]},"SessionWorkflowRunStatusDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/WorkflowRunStatus"}]},"errorMessage":{"type":"string","nullable":true,"description":"Why the run failed, when it is something the person can fix (a capture problem such as a wrong file type); null otherwise"},"stepRuns":{"type":"array","items":{"$ref":"#/components/schemas/SessionWorkflowStepStatusDto"}}},"required":["id","status","stepRuns"]},"GoogleImportRequestDto":{"type":"object","properties":{"sandbox":{"type":"boolean","default":false,"description":"Dashboard mode. API keys always use their authenticated mode."},"collectionIds":{"maxItems":100,"description":"Explicit destination collections. Omission or [] leaves the resource unassigned.","type":"array","items":{"type":"string","format":"uuid"}},"connectionId":{"type":"string"},"fileId":{"type":"string"},"target":{"type":"string","enum":["document","template"]},"name":{"type":"string"},"idempotencyKey":{"type":"string","description":"Unique per connection owner. Reusing a key with different input returns 409."}},"required":["connectionId","fileId","target","name","idempotencyKey"]},"GoogleVariableDto":{"type":"object","properties":{"name":{"type":"string"},"occurrences":{"type":"number"}},"required":["name","occurrences"]},"GoogleImportDto":{"type":"object","properties":{"collectionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"id":{"type":"string"},"target":{"type":"string","enum":["document","template"]},"name":{"type":"string"},"sandbox":{"type":"boolean"},"status":{"type":"string","enum":["queued","processing","awaiting_values","ready","completed","failed"]},"variables":{"type":"array","items":{"$ref":"#/components/schemas/GoogleVariableDto"}},"provenance":{"$ref":"#/components/schemas/GoogleProvenanceDto"},"previewUrl":{"type":"string"},"reviewHash":{"type":"string"},"documentId":{"type":"string"},"templateId":{"type":"string"},"errorCode":{"type":"string"}},"required":["id","target","name","sandbox","status","variables"]},"GoogleValuesDto":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":"string"}}},"required":["values"]},"GooglePublishDto":{"type":"object","properties":{"reviewHash":{"type":"string","description":"Hash returned with the exact PDF reviewed by the caller."}},"required":["reviewHash"]}}}}