{"openapi":"3.0.0","paths":{"/sanctions/search":{"post":{"description":"Search global sanctions lists for individuals matching the provided name. Returns matches from OFAC, UN, FCDO, DFAT, CASL, and INTERPOL databases.\n\n**Costs 5 credits per request.**\n\nOptionally filter by specific sanctions sources or countries.","operationId":"SanctionsController_searchSanctionsEndpoint","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SanctionSearchInput"},"examples":{"basic":{"summary":"Basic sanctions search","value":{"fullName":"John Smith"}},"filtered":{"summary":"Search specific sources and countries","value":{"fullName":"John Smith","sources":["ofac","un"],"countries":["LK"]}}}}}},"responses":{"200":{"description":"Sanctions search results including total hits and matching sanction records.","content":{"application/json":{"example":{"totalHits":2,"searchingFor":["john smith"],"documents":[{"fullName":"John Arthur Smith","source":"ofac","type":"individual","programs":["SDGT"],"remarks":"Designated pursuant to Executive Order 13224","dateOfBirth":"1965-04-12","nationality":"Unknown","aliases":["J. Smith","Johnny Smith"],"addresses":["123 Unknown St, Somewhere"],"identificationDocuments":[{"type":"passport","number":"X1234567","country":"XX"}]},{"fullName":"John B. Smith","source":"un","type":"individual","programs":["Security Council Resolution 1267"],"remarks":"Listed on 2020-01-15","dateOfBirth":"1970-08-22","nationality":"Unknown","aliases":[],"addresses":[],"identificationDocuments":[]}]}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"API key does not have AML Screening product access or the Individual Screening feature enabled"}},"security":[{"bearer":[]}],"summary":"Search sanctions lists","tags":["AML Screening"]}},"/high-risk/search":{"post":{"description":"Search global PEP registries, sanctions lists, and adverse media databases for individuals matching the provided name. Returns detailed dossiers including risk scores, positions held, associates, and identification documents.\n\n**Costs 3 credits per request.**\n\nResults are cached by default. Set `noCache: true` to force a fresh search.\n\nThe response includes an AI-generated risk scorecard with:\n- **Overall risk score** (0.0–1.0)\n- **PEP likelihood score** with category and reasoning\n- **Risk category** classification","operationId":"DossiersController_searchDossiersPostRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DossierSearchInput"},"examples":{"basicSearch":{"summary":"Basic name search","description":"Search by full name — the simplest way to query.","value":{"fullName":"John Smith"}},"freshSearch":{"summary":"Force fresh search (no cache)","description":"Bypass cached results and run a fresh search against all data sources.","value":{"fullName":"John Smith","noCache":true}},"allProfiles":{"summary":"Include non-high-risk profiles","description":"Return all matching profiles, not just those flagged as high-risk.","value":{"fullName":"John Smith","onlyShowHighRiskProfiles":false}}}}}},"responses":{"200":{"description":"Array of individual dossiers matching the search query. Each dossier includes biographical data, positions held, associates, identification documents, and an AI-generated risk scorecard.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndividualDossier"}}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"API key does not have AML Screening product access or the Individual Screening feature enabled"}},"security":[{"bearer":[]}],"summary":"Search for Politically Exposed Persons and high-risk individuals","tags":["AML Screening"]}},"/screening/request":{"post":{"description":"Submit an individual for background screening against global sanctions lists (OFAC, UN, FCDO, DFAT, CASL, INTERPOL), PEP registries, and adverse media databases.\n\n**Costs 10 credits per request.**\n\nThe screening runs asynchronously. When matches are found, Screening Alerts are created and surfaced in your Dossiers Dashboard for review. You are also notified via webhooks (`amlScreening.screeningRequest.completed`, `amlScreening.screeningAlert.triggered`).\n\nProvide additional details like `dateOfBirth`, `country`, and `identificationDocument` to improve match accuracy and reduce false positives.","operationId":"ScreeningRequestController_createRequest","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScreeningRequestDto"},"examples":{"basic":{"summary":"Basic screening — name only","value":{"fullName":"John Smith"}},"withDetails":{"summary":"Screening with additional details","description":"Providing date of birth, country, and an external ID improves match quality and lets you correlate results with your systems.","value":{"fullName":"John Smith","dateOfBirth":"1985-03-15","country":"LK","externalId":"CUST-12345","identificationDocument":{"type":"passport","number":"N1234567","country":"LK"}}}}}}},"responses":{"201":{"description":"Screening request created successfully. The returned requestId can be used to track the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScreeningRequestResponseDto"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"API key does not have AML Screening product access or the Individual Screening feature enabled"}},"security":[{"bearer":[]}],"summary":"Create a screening request","tags":["AML Screening"]}},"/kyc-sessions":{"post":{"description":"Creates a new KYC verification session. Returns a signed session URL that can be shared with the customer. If customerEmail and customerName are provided, an invitation email with the session link and QR code is sent automatically.","operationId":"KycSessionApiController_createSession","parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKycSessionDTO"}}}},"responses":{"201":{"description":"Session created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKycSessionOutputDTO"}}}},"401":{"description":"Unauthorized — invalid or missing API key."},"403":{"description":"Forbidden — KYC Sessions product not enabled."}},"security":[{"bearer":[]}],"summary":"Create a KYC session","tags":["KYC Sessions"]},"get":{"description":"Retrieves a paginated list of KYC sessions for the authenticated organization. Supports filtering by state, completion status, date range, and free-text search across session ID, external ID, customer name, and email.","operationId":"KycSessionApiController_getAllSessions","parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycSessionFiltersDTO"}}}},"responses":{"200":{"description":"Paginated list of sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedKycSessionsDTO"}}}},"401":{"description":"Unauthorized — invalid or missing API key."},"403":{"description":"Forbidden — KYC Sessions product not enabled."}},"security":[{"bearer":[]}],"summary":"List KYC sessions","tags":["KYC Sessions"]}},"/kyc-sessions/{id}":{"get":{"description":"Retrieves a single KYC session by its ID, including document verification and face verification results if available. If document verification is still in progress, the latest status is refreshed before returning.","operationId":"KycSessionApiController_getSession","parameters":[{"name":"id","required":true,"in":"path","description":"The unique session ID.","schema":{"example":"665f1a2b3c4d5e6f7a8b9c0d","type":"string"}}],"responses":{"200":{"description":"Session details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KycSessionOutputDTO"}}}},"401":{"description":"Unauthorized — invalid or missing API key."},"404":{"description":"Session not found."}},"security":[{"bearer":[]}],"summary":"Get a KYC session","tags":["KYC Sessions"]},"delete":{"description":"Permanently deletes a KYC session and all associated data.","operationId":"KycSessionApiController_deleteSession","parameters":[{"name":"id","required":true,"in":"path","description":"The unique session ID.","schema":{"example":"665f1a2b3c4d5e6f7a8b9c0d","type":"string"}}],"responses":{"200":{"description":"Session deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSessionOutputDTO"}}}},"401":{"description":"Unauthorized — invalid or missing API key."},"404":{"description":"Session not found."}},"security":[{"bearer":[]}],"summary":"Delete a KYC session","tags":["KYC Sessions"]}},"/document-processing":{"post":{"description":"Submit documents for processing against one of the available processor templates.\n\n**Available processors:**\n| `processorId` | Accepted formats | Description |\n|---|---|---|\n| `INVOICE` | image/jpeg, image/png, application/pdf | Extracts and validates commercial invoices, tax invoices, proforma invoices, and credit notes |\n| `SRI_LANKA_ID` | image/jpeg, image/png, application/pdf | KYC validation and data extraction for Sri Lankan passports, driver's licenses, and NICs (old & new). Also enriches with voter registration data when NIC is present. |\n| `SRI_LANKA_FORM1_COMPANY_REGISTRATION` | application/pdf | Extracts company registration data from Sri Lankan Form 1 documents |\n| `SRI_LANKA_FORM15_ANNUAL_RETURN` | application/pdf | Extracts annual return data from Sri Lankan Form 15 documents |\n\n**The `inputData` field** provides verification context to the AI — values are matched against extracted document fields. For example, passing `name` and `dateOfBirth` for an ID document tells the processor to flag a mismatch if the document doesn't match.\n\nSynchronous steps (e.g., image cropping) run immediately. Validation and extraction are queued as background jobs by default. You will be notified via webhooks when processing completes.","operationId":"DocumentProcessingController_initiateProcessing","parameters":[],"requestBody":{"required":true,"description":"Document processing request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateDocumentProcessingInput"},"examples":{"invoice":{"summary":"Invoice — validate & extract","description":"Extracts invoice fields (supplier, customer, line items, amounts) and cross-checks the expected vendor and total. Accepts PDF or image files.","value":{"processorId":"INVOICE","files":[{"base64Data":"<base64-encoded-file-data>","mimeType":"application/pdf","filename":"invoice.pdf"}],"inputData":{"expectedVendor":"ACME Corp","expectedAmount":"1500.00"}}},"invoiceUrl":{"summary":"Invoice — via URL","description":"Same as the invoice example but the file is fetched from a URL instead of being uploaded as base64.","value":{"processorId":"INVOICE","files":[{"url":"https://example.com/documents/invoice.pdf","mimeType":"application/pdf","filename":"invoice.pdf"}],"inputData":{"expectedVendor":"ACME Corp","expectedAmount":"1500.00"}}},"sriLankaId":{"summary":"Sri Lanka ID — KYC verification","description":"Validates and extracts data from Sri Lankan identity documents (Passport, Driver's License, NIC old/new).\nSupply known customer details in `inputData` to trigger cross-checks:\n- `name` — full name to match against the document\n- `dateOfBirth` — expected date of birth (YYYY-MM-DD)\n- `idNumber` — NIC or passport number to verify\n- `address` — residential address to compare (warning-level check)\n\nFor NIC documents the processor also automatically:\n- Validates NIC format (9+V/X or 12 digits)\n- Derives and cross-checks date of birth and sex encoded in the NIC\n- Enriches the result with voter registration data from Sri Lanka Elections eServices","value":{"processorId":"SRI_LANKA_ID","files":[{"base64Data":"<base64-encoded-file-data>","mimeType":"image/jpeg","filename":"nic_front.jpg"}],"inputData":{"name":"Kamal Perera","dateOfBirth":"1985-03-15","idNumber":"851234567V","address":"123 Main Street, Colombo 03"}}},"sriLankaCompanyReg":{"summary":"Sri Lanka Company Registration — Form 1","description":"Extracts company registration details from a Sri Lankan Form 1 document (PDF only). Extracted fields include company name, registration number, company type, directors, shareholders, secretaries, registered address, and presenter information.","value":{"processorId":"SRI_LANKA_FORM1_COMPANY_REGISTRATION","files":[{"base64Data":"<base64-encoded-file-data>","mimeType":"application/pdf","filename":"form1_company_registration.pdf"}]}},"sriLankaAnnualReturn":{"summary":"Sri Lanka Annual Return — Form 15","description":"Extracts annual return data from a Sri Lankan Form 15 document (PDF only). Extracted fields include company details, share classes, shareholders, directors, secretaries, auditors, AGM information, and declaratory officers.","value":{"processorId":"SRI_LANKA_FORM15_ANNUAL_RETURN","files":[{"base64Data":"<base64-encoded-file-data>","mimeType":"application/pdf","filename":"form15_annual_return.pdf"}]}}}}}},"responses":{"201":{"description":"Processing initiated successfully","content":{"application/json":{"example":{"instanceId":"65f3c1a2b4e5f60012345678","processorId":"SRI_LANKA_ID","status":"scanning","statusLabel":"Scanning document","createdAt":"2026-03-05T11:35:06.000Z","updatedAt":"2026-03-05T11:35:06.000Z","result":null,"files":[{"filename":"nic_front.jpg","mimeType":"image/jpeg"}]}}}},"400":{"description":"Invalid processor ID or unsupported file type for the selected processor","content":{"application/json":{"example":{"statusCode":400,"message":"Invalid file types provided. Accepted types: image/jpeg, image/png","error":"Bad Request"}}}}},"security":[{"bearer":[]}],"summary":"Initiate document processing","tags":["Document Processing"]},"get":{"description":"Retrieve a list of document processing instances with optional filters. Use includeFileUrls=true to get signed URLs (expires in 5 minutes).","operationId":"DocumentProcessingController_listInstances","parameters":[{"name":"processorId","required":false,"in":"query","description":"Filter by processor ID","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by processing status","schema":{"enum":["pending","running","completed","failed","error"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of results (default: 50)","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results to skip (default: 0)","schema":{"type":"number"}},{"name":"includeFileUrls","required":false,"in":"query","description":"Include signed URLs for files (default: false). May impact performance for large lists.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of processing instances","content":{"application/json":{"example":{"instances":[{"instanceId":"65f3c1a2b4e5f60012345678","processorId":"SRI_LANKA_ID","status":"completed","statusLabel":"Completed","createdAt":"2026-03-05T11:35:06.000Z","updatedAt":"2026-03-05T11:35:42.000Z","completedAt":"2026-03-05T11:35:42.000Z"},{"instanceId":"65f3c1a2b4e5f60012345679","processorId":"INVOICE","status":"extracting","statusLabel":"Extracting data","createdAt":"2026-03-05T12:00:00.000Z","updatedAt":"2026-03-05T12:00:15.000Z","completedAt":null}],"count":2}}}}},"security":[{"bearer":[]}],"summary":"List processing instances","tags":["Document Processing"]}},"/document-processing/processors":{"get":{"description":"Returns all available document processor types with their schema fields, validation rules, extraction rules, recognised templates, and supported inputData keys.","operationId":"DocumentProcessingController_getProcessors","parameters":[],"responses":{"200":{"description":"List of available processors and their capabilities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentProcessorTypeDTO"}}}}}},"security":[{"bearer":[]}],"summary":"List available document processors","tags":["Document Processing"]}},"/document-processing/{id}/stages/{stageId}":{"get":{"description":"Retrieve the full output of a single pipeline stage (e.g. crop_and_detect_faces, pre_validate_and_extract, post_validation). Returns the complete stage data including validation rules, extraction results, and schema.","operationId":"DocumentProcessingController_getInstanceStage","parameters":[{"name":"id","required":true,"in":"path","description":"Processing instance ID","schema":{"type":"string"}},{"name":"stageId","required":true,"in":"path","description":"Stage ID (crop_and_detect_faces | pre_validate_and_extract | post_validation)","schema":{"type":"string"}}],"responses":{"200":{"description":"Stage result","content":{"application/json":{"example":{"stageId":"pre_validate_and_extract","status":"success","data":{"validation":{"status":"success","passed":true,"reasoning":"All validation rules passed","rulesPassed":[{"id":"is_valid_document","confidence":0.95},{"id":"name_matches","confidence":0.92}],"rulesFailed":[],"rulesIgnored":[],"userErrorMessages":[]},"extraction":{"status":"success","passed":true,"reasoning":"All fields extracted successfully","rulesPassed":[{"id":"full_name","confidence":0.98}],"rulesFailed":[],"rulesIgnored":[],"userErrorMessages":[]},"schema":{"fullName":{"value":"Kamal Perera","originalText":"KAMAL PERERA","originalTextConfidence":0.98,"isOriginalTextHandwritten":false},"dateOfBirth":{"value":"1985-03-15","originalText":"15.03.1985","originalTextConfidence":0.95,"isOriginalTextHandwritten":false}}}}}}},"404":{"description":"Instance or stage not found"}},"security":[{"bearer":[]}],"summary":"Get a specific pipeline stage result","tags":["Document Processing"]}},"/document-processing/{id}":{"get":{"description":"Retrieve the details and status of a document processing instance. File URLs are signed and expire in 5 minutes.","operationId":"DocumentProcessingController_getInstance","parameters":[{"name":"id","required":true,"in":"path","description":"Processing instance ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Processing instance retrieved successfully","content":{"application/json":{"example":{"instanceId":"65f3c1a2b4e5f60012345678","processorId":"SRI_LANKA_ID","status":"completed","statusLabel":"Completed","createdAt":"2026-03-05T11:35:06.000Z","updatedAt":"2026-03-05T11:35:42.000Z","completedAt":"2026-03-05T11:35:42.000Z","result":{"documentTypeID":"sri_lanka_nic_new","validation":{"status":"success","passed":true,"reasoning":"All validation rules passed","rulesPassed":[{"id":"is_valid_document","confidence":0.97},{"id":"name_matches","confidence":0.94},{"id":"dob_matches","confidence":0.99}],"rulesFailed":[],"rulesIgnored":[],"userErrorMessages":[]},"extraction":{"status":"success","passed":true,"reasoning":"All fields extracted successfully","rulesPassed":[{"id":"full_name","confidence":0.98},{"id":"nic_number","confidence":0.99}],"rulesFailed":[],"rulesIgnored":[],"userErrorMessages":[]},"schema":{"fullName":{"value":"Kamal Perera","originalText":"KAMAL PERERA","originalTextConfidence":0.98,"isOriginalTextHandwritten":false},"nicNumber":{"value":"199512345678","originalText":"199512345678","originalTextConfidence":0.99,"isOriginalTextHandwritten":false},"dateOfBirth":{"value":"1985-03-15","originalText":"15.03.1985","originalTextConfidence":0.95,"isOriginalTextHandwritten":false},"sex":{"value":"Male"},"address":{"value":"123 Main Street, Colombo 03","originalText":"123 Main Street, Colombo 03","originalTextConfidence":0.88,"isOriginalTextHandwritten":true}},"postProcessing":{"passed":true,"ruleResults":[{"id":"nic_dob_cross_check","passed":true,"confidence":1,"errorLevel":"error"},{"id":"voter_registration_lookup","passed":true,"confidence":0.95,"errorLevel":"warning","message":"Voter registration record found"}],"schemaModifications":[{"field":"voterRegistration","value":{"registered":true,"district":"Colombo"},"source":"derived","sourceDescription":"Derived from Sri Lanka Elections eServices lookup"}]},"stages":[{"stageId":"crop_and_detect_faces","status":"success"},{"stageId":"visual_integrity_check","status":"success"},{"stageId":"pre_validate_and_extract","status":"success"},{"stageId":"post_validation","status":"success"},{"stageId":"voter_registry","status":"success"}]},"files":[{"filename":"nic_front.jpg","mimeType":"image/jpeg","url":"https://storage.example.com/signed-url..."}]}}}},"404":{"description":"Processing instance not found"}},"security":[{"bearer":[]}],"summary":"Get processing instance","tags":["Document Processing"]},"delete":{"description":"Delete a document processing instance and its associated data","operationId":"DocumentProcessingController_deleteInstance","parameters":[{"name":"id","required":true,"in":"path","description":"Processing instance ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Processing instance deleted successfully","content":{"application/json":{"example":{"success":true,"message":"Processing instance 65f3c1a2b4e5f60012345678 deleted successfully"}}}},"404":{"description":"Processing instance not found"}},"security":[{"bearer":[]}],"summary":"Delete processing instance","tags":["Document Processing"]}},"/document-processing/{id}/events":{"get":{"description":"Subscribe to real-time Server-Sent Events for a processing instance. Events are emitted as each pipeline stage starts, succeeds, or fails. The connection stays open until the client disconnects.","operationId":"DocumentProcessingController_streamInstanceEvents","parameters":[{"name":"id","required":true,"in":"path","description":"Processing instance ID","schema":{"type":"string"}}],"responses":{"200":{"description":"SSE event stream"}},"security":[{"bearer":[]}],"summary":"Stream instance progress (SSE)","tags":["Document Processing"]}}},"info":{"title":"Dossiers API","description":"## Overview\n\nThe Dossiers REST API gives financial institutions and regulated businesses programmatic access to two core compliance products:\n\n**Document Verification** — Submit identity documents and invoices for AI-powered validation and structured data extraction. Supports Sri Lankan National Identity Cards, passports, driver's licenses, commercial invoices, and company registration forms. Processing runs asynchronously; results are delivered via webhooks.\n\n**AML Screening** — Screen individuals against global sanctions lists (OFAC, UN, FCDO, DFAT, CASL, INTERPOL), PEP registries, and adverse media databases. Matches surface as Screening Alerts in your Dossiers compliance dashboard for review by your team.\n\n---\n\n## Authentication\n\nAll endpoints require a Bearer JWT API key issued from the **Developer Console** in your Dossiers dashboard. Include it in the `Authorization` header of every request:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nAPI keys carry product-level permissions. Ensure the key has the relevant product enabled (**Document Verification** or **AML Screening**) before calling its endpoints.\n\n---\n\n## Credits\n\nAPI usage is metered in credits:\n\n| Product | Endpoint | Credits |\n|---|---|---|\n| Document Verification | `POST /document-processing` | 5 credits |\n| AML Screening | `POST /screening/request` | 10 credits |\n\n---\n\n## Document Verification\n\n### Submitting a Request\n\nSend a `POST /document-processing` request with the following body:\n\n```json\n{\n  \"processorId\": \"SRI_LANKA_ID\",\n  \"files\": [\n    {\n      \"base64Data\": \"<base64-encoded file contents>\",\n      \"mimeType\": \"image/jpeg\",\n      \"filename\": \"id_front.jpg\"\n    },\n    {\n      \"base64Data\": \"<base64-encoded file contents>\",\n      \"mimeType\": \"image/jpeg\",\n      \"filename\": \"id_back.jpg\"\n    }\n  ]\n}\n```\n\nAlternatively, supply a publicly accessible `url` instead of `base64Data` for each file:\n\n```json\n{\n  \"processorId\": \"INVOICE\",\n  \"files\": [\n    {\n      \"url\": \"https://example.com/documents/invoice.pdf\",\n      \"mimeType\": \"application/pdf\",\n      \"filename\": \"invoice.pdf\"\n    }\n  ],\n  \"inputData\": {\n    \"expectedVendor\": \"ACME Corp\",\n    \"expectedAmount\": 1500.00\n  }\n}\n```\n\n**Key fields:**\n\n| Field | Required | Description |\n|---|---|---|\n| `processorId` | Yes | Which document processor to run (see table below) |\n| `files` | Yes | One or more document files. Each file needs `mimeType` and `filename` plus either `base64Data` or `url` |\n| `inputData` | No | Optional key/value context passed to the processor (e.g. expected vendor, expected amounts, known name) |\n| `backgroundProcessing` | No | Default `true`. Set to `false` to wait synchronously for the full result before the response is returned |\n\n**Available processor IDs:**\n\n| processorId | Accepted file types | Description |\n|---|---|---|\n| `SRI_LANKA_ID` | `image/jpeg`, `image/png` | Sri Lankan NIC (old & new) and passport |\n| `INVOICE` | `image/jpeg`, `image/png`, `application/pdf` | Commercial invoices, multi-currency |\n| `SRI_LANKA_FORM1_COMPANY_REGISTRATION` | `image/jpeg`, `image/png`, `application/pdf` | Company registration Form 1 |\n| `SRI_LANKA_FORM15_ANNUAL_RETURN` | `image/jpeg`, `image/png`, `application/pdf` | Annual return Form 15 |\n\n### Response\n\nA successful submission returns HTTP `201` with an `instanceId`:\n\n```json\n{\n  \"instanceId\": \"65f3c1a2b4e5f60012345678\",\n  \"status\": \"pending\",\n  ...\n}\n```\n\nUse this `instanceId` to poll `GET /document-processing/{id}` for the current status, or wait for the webhook event described below.\n\n### Processing Statuses\n\n| Status | Meaning |\n|---|---|\n| `pending` | Job accepted, waiting to be picked up |\n| `processing_sync` | Synchronous steps (e.g. image crop) running |\n| `sync_completed` | Synchronous steps done, async steps queued |\n| `processing_async` | Validation and extraction running in the background |\n| `completed` | All processing finished successfully |\n| `failed` | Processing encountered an unrecoverable error |\n\n### Retrieving Results\n\n- **Single instance** — `GET /document-processing/{id}`\n  Returns the full instance including validation results, extracted schema fields, and signed file URLs (valid for 5 minutes).\n\n- **Stage-level detail** — `GET /document-processing/{id}/stages/{stageId}`\n  Returns the raw output of a single pipeline stage. Useful for debugging. Available stage IDs: `crop_and_detect_faces`, `pre_validate_and_extract`, `post_validation`.\n\n- **List instances** — `GET /document-processing`\n  Supports filtering by `processorId`, `status`, and pagination via `limit` / `offset`. Add `includeFileUrls=true` to include signed file URLs in the list response.\n\n---\n\n## Webhooks\n\n### Overview\n\nBoth Document Verification and AML Screening emit webhook events as processing progresses. Instead of polling, configure a webhook destination in the **Developer Console** and your endpoint will receive a `POST` request the moment an event fires.\n\n### Configuring a Destination\n\nIn the Developer Console, create a webhook destination with:\n- A publicly reachable HTTPS URL that accepts `POST` requests\n- The events you want to subscribe to (see table below)\n\nA secret is generated automatically when the destination is created. Use it to verify incoming payloads.\n\n### Document Verification Events\n\n| Event type | When it fires |\n|---|---|\n| `documentVerification.instance.created` | A new processing instance has been created |\n| `documentVerification.instance.updated` | The instance status or result has changed (fires after each pipeline stage completes, and again on final completion or failure) |\n| `documentVerification.instance.deleted` | An instance was deleted |\n\nSubscribe to `documentVerification.instance.updated` to be notified when processing finishes. Check the `status` field in the payload to distinguish an in-progress update from a final `completed` or `failed` result.\n\n### Webhook Payload\n\nEvery delivery is a `POST` request with a JSON body:\n\n```json\n{\n  \"id\": \"evt_01HZ...\",\n  \"type\": \"documentVerification.instance.updated\",\n  \"organizationId\": \"org_...\",\n  \"createdAt\": \"2026-03-05T11:35:06.000Z\",\n  \"data\": {\n    \"instanceId\": \"65f3c1a2b4e5f60012345678\",\n    \"status\": \"completed\",\n    ...\n  }\n}\n```\n\n### Verifying Signatures\n\nEvery delivery includes an `X-Webhook-Signature` header containing an HMAC-SHA256 hex digest of the raw request body, signed with your destination secret.\n\nTo verify:\n\n```js\nconst crypto = require('crypto');\n\nfunction isValidSignature(rawBody, secret, signature) {\n  const expected = crypto\n    .createHmac('sha256', secret)\n    .update(rawBody)\n    .digest('hex');\n  return crypto.timingSafeEqual(\n    Buffer.from(expected),\n    Buffer.from(signature),\n  );\n}\n```\n\nAlways verify the signature before trusting the payload. Use the raw (unparsed) request body for the HMAC computation — parsing JSON first will break the digest.\n\n### Delivery and Retries\n\n- Your endpoint must return a `2xx` response within **10 seconds**.\n- Failed deliveries (non-2xx or timeout) are retried automatically with exponential back-off.\n- Delivery history and per-event logs are available in the Developer Console under **Webhook Logs**.\n\n### Additional Headers\n\nEach delivery also includes:\n\n| Header | Value |\n|---|---|\n| `X-Webhook-Signature` | HMAC-SHA256 hex digest of the payload |\n| `X-Webhook-Event-Type` | Event type string (e.g. `documentVerification.instance.updated`) |\n| `X-Webhook-Event-Id` | Unique event ID |\n| `X-Webhook-Retry-Count` | Number of previous failed delivery attempts |","version":"1.0","contact":{}},"tags":[{"name":"Document Processing","description":"Submit documents for AI-powered validation and structured data extraction. Supports invoices, Sri Lankan identity documents, and company registration forms."},{"name":"AML Screening","description":"Screen individuals against global sanctions lists (OFAC, UN, FCDO, DFAT, CASL, INTERPOL), PEP registries, and adverse media databases."}],"servers":[{"url":"https://api.dossiers.wiki","description":"Production"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"JWT API key from the Dossiers Developer Console"}},"schemas":{"SanctionSearchInput":{"type":"object","properties":{"fullName":{"type":"string","description":"Full name of the individual to search for","example":"John Smith"},"sources":{"type":"array","description":"Filter by specific sanctions sources. If omitted, all sources are searched.","example":["ofac","un"],"items":{"type":"string","enum":["CASL","dfat","fcdo","interpol","ofac","un"]}},"countries":{"description":"Filter by ISO 3166-1 alpha-2 country codes to narrow results to specific jurisdictions","example":["LK","US"],"type":"array","items":{"type":"string"}}},"required":["fullName"]},"DossierSearchInput":{"type":"object","properties":{"fullName":{"type":"string","description":"Full name of the individual to search for","example":"John Smith"},"noCache":{"type":"boolean","description":"When true, bypasses cached results and runs a fresh search against all data sources. Default: false.","default":true},"onlyShowHighRiskProfiles":{"type":"boolean","description":"When true, only returns profiles flagged as high-risk (PEPs, sanctioned individuals, adverse media matches). Set to false to include all matching profiles. Default: true.","default":true}},"required":["fullName"]},"PersonIdentificationDocument":{"type":"object","properties":{"type":{"type":"string","description":"Document type (e.g. \"passport\", \"national_id\")"},"number":{"type":"string","description":"Document number or identifier"},"description":{"type":"string","description":"Additional details about the document"},"referenceDocumentIds":{"description":"IDs of source documents referencing this identification","type":"array","items":{"type":"string"}}},"required":["type","number","description","referenceDocumentIds"]},"AssociatesAndRelatives":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the associate or relative"},"relationship":{"type":"string","description":"Relationship to the dossier subject (e.g. \"spouse\", \"business partner\", \"sibling\")"},"description":{"type":"string","description":"Brief description of the association"},"referenceDocumentIds":{"description":"IDs of source documents supporting this association","type":"array","items":{"type":"string"}}},"required":["name","relationship","description","referenceDocumentIds"]},"PositionsHeld":{"type":"object","properties":{"position":{"type":"string","description":"Title or role held (e.g. \"Minister of Finance\")"},"organization":{"type":"string","description":"Organization or body where the position was held"},"period":{"type":"string","description":"Time period of the position (e.g. \"2015–2020\")"},"description":{"type":"string","description":"Description of the role and responsibilities"},"asOfDate":{"type":"string","description":"Date this information was current as of"},"referenceDocumentIds":{"description":"IDs of source documents supporting this position","type":"array","items":{"type":"string"}},"supportingText":{"type":"string","description":"Excerpt from source material"}},"required":["position","organization","period","description","asOfDate","referenceDocumentIds","supportingText"]},"DocumentMatch":{"type":"object","properties":{"matchingQueries":{"type":"array","items":{"type":"string"}},"matchingChunk":{"type":"string"}},"required":["matchingQueries","matchingChunk"]},"Document":{"type":"object","properties":{"id":{"type":"string"},"originalUrl":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"matches":{"$ref":"#/components/schemas/DocumentMatch"}},"required":["id","originalUrl","title","body","matches"]},"PEPScorecard":{"type":"object","properties":{"pepLikelihoodScore":{"type":"number","description":"PEP likelihood score from 0.0 (unlikely) to 1.0 (certain)","minimum":0,"maximum":1,"example":0.85},"category":{"type":"string","description":"PEP category (e.g. \"Head of State\", \"Senior Government Official\", \"State-Owned Enterprise Executive\")"},"reasoningSteps":{"description":"Step-by-step reasoning explaining how the PEP score was derived","type":"array","items":{"type":"string"}}},"required":["pepLikelihoodScore","category","reasoningSteps"]},"RiskScorecard":{"type":"object","properties":{"pepScorecard":{"description":"PEP-specific scoring breakdown (present when PEP indicators are found)","allOf":[{"$ref":"#/components/schemas/PEPScorecard"}]},"overallRiskScore":{"type":"number","description":"Overall risk score from 0.0 (low risk) to 1.0 (high risk)","minimum":0,"maximum":1,"example":0.72},"riskReasoning":{"type":"string","description":"Narrative explanation of the risk assessment"},"riskCategory":{"type":"string","description":"Risk category classification (e.g. \"high\", \"medium\", \"low\")"}},"required":["overallRiskScore","riskReasoning","riskCategory"]},"IndividualDossier":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this individual"},"fullName":{"type":"string","description":"Full name of the individual"},"countries":{"description":"Countries associated with this individual","type":"array","items":{"type":"string"}},"otherNames":{"description":"Known aliases and alternative names","type":"array","items":{"type":"string"}},"identificationDocuments":{"description":"Identification documents linked to this individual","type":"array","items":{"$ref":"#/components/schemas/PersonIdentificationDocument"}},"closeAssociatesOrFamilyMembers":{"description":"Known close associates and family members","type":"array","items":{"$ref":"#/components/schemas/AssociatesAndRelatives"}},"dateOfBirth":{"description":"Known dates of birth (multiple entries when sources disagree)","type":"array","items":{"type":"string"}},"tagline":{"type":"string","description":"One-line summary describing the individual"},"locations":{"description":"Known locations and addresses","type":"array","items":{"type":"string"}},"keywords":{"description":"Classification keywords (e.g. \"pep\", \"sanctions\", \"adverse-media\")","type":"array","items":{"type":"string"}},"positionsHeld":{"description":"Political and professional positions held","type":"array","items":{"$ref":"#/components/schemas/PositionsHeld"}},"documentIds":{"description":"IDs of supporting source documents","type":"array","items":{"type":"string"}},"documents":{"description":"Full source documents used to compile this dossier","type":"array","items":{"$ref":"#/components/schemas/Document"}},"individualSummary":{"type":"string","description":"AI-generated narrative summary of the individual and their risk profile"},"riskScorecard":{"description":"AI-generated risk scorecard including PEP analysis and overall risk assessment","allOf":[{"$ref":"#/components/schemas/RiskScorecard"}]},"cachedResult":{"type":"boolean","description":"Whether this result was served from cache"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when this dossier was created"}},"required":["id","fullName","countries","otherNames","identificationDocuments","closeAssociatesOrFamilyMembers","dateOfBirth","tagline","locations","keywords","positionsHeld","individualSummary","createdAt"]},"IdentificationDocumentInput":{"type":"object","properties":{"type":{"type":"string","description":"Document type (e.g. \"passport\", \"national_id\", \"drivers_license\")","example":"passport"},"number":{"type":"string","description":"Document number or identifier","example":"N1234567"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the issuing country","example":"LK"}}},"CreateScreeningRequestDto":{"type":"object","properties":{"fullName":{"type":"string","description":"Full name of the individual to screen","example":"John Smith"},"externalId":{"type":"string","description":"Your own reference ID for this screening request (e.g. customer ID, case number). Useful for correlating results with your internal systems.","example":"CUST-12345"},"identificationDocument":{"description":"Identification document details to improve match accuracy. When provided, the screening engine uses these details to reduce false positives.","allOf":[{"$ref":"#/components/schemas/IdentificationDocumentInput"}]},"dateOfBirth":{"type":"string","description":"Date of birth in YYYY-MM-DD format","example":"1985-03-15"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the individual's nationality or residence","example":"LK"}},"required":["fullName"]},"CreateScreeningRequestResponseDto":{"type":"object","properties":{"requestId":{"type":"string","description":"Unique ID of the created screening request. Use this to track the request status and retrieve results.","example":"65f3c1a2b4e5f60012345678"}},"required":["requestId"]},"CreateKycSessionDTO":{"type":"object","properties":{"externalId":{"type":"string","description":"External reference ID from your system, used to correlate this session with your records.","example":"usr_abc123"},"expiresInMs":{"type":"number","description":"Session expiry duration in milliseconds. Defaults to 1 hour (3,600,000 ms).","example":3600000},"customerEmail":{"type":"string","description":"Customer email address. When provided along with customerName, an invitation email with the session link is sent automatically.","example":"john@example.com"},"customerName":{"type":"string","description":"Customer display name, used in the invitation email greeting.","example":"John Doe"}}},"KycSessionDataOutputDTO":{"type":"object","properties":{"country":{"type":"string","description":"Selected country code.","example":"LK"},"documentType":{"type":"string","description":"Selected document type.","example":"national-id"},"documentRatio":{"type":"number","description":"Document aspect ratio (width / height).","example":1.586},"isDoubleSided":{"type":"boolean","description":"Whether the document has both front and back sides.","example":true}}},"KycDocumentVerificationDTO":{"type":"object","properties":{"instanceId":{"type":"string","description":"Document processor instance ID."},"processorId":{"type":"string","description":"Processor definition ID used for this verification."},"status":{"type":"string","description":"Processing status.","example":"completed","enum":["pending","running","completed","failed"]},"statusLabel":{"type":"string","description":"Human-readable status label.","nullable":true},"documentTypeId":{"type":"string","description":"Detected document type identifier.","nullable":true},"triggeredAt":{"type":"number","description":"Timestamp when verification was triggered (Unix ms).","example":1717430828000},"completedAt":{"type":"number","description":"Timestamp when verification completed (Unix ms). Null while in progress.","nullable":true},"error":{"type":"string","description":"Error message if processing failed, null on success.","nullable":true},"result":{"type":"object","description":"Full processing result including validation, extraction, and post-processing data.","nullable":true},"stageProgress":{"description":"Per-stage progress entries showing each pipeline stage and its status.","nullable":true,"type":"array","items":{"type":"string"}},"processingLog":{"description":"Chronological processing log with timestamps for each stage.","nullable":true,"type":"array","items":{"type":"string"}},"files":{"description":"Processing files with references to original, cropped, and detected face images.","nullable":true,"type":"array","items":{"type":"string"}}},"required":["instanceId","processorId","status","triggeredAt"]},"KycFaceVerificationDTO":{"type":"object","properties":{"verified":{"type":"boolean","description":"Whether the face on the document matches the liveness frame.","example":true},"distance":{"type":"number","description":"Computed distance between the two face embeddings (lower = more similar).","example":0.32},"threshold":{"type":"number","description":"Distance threshold used for the verification decision.","example":0.6},"model":{"type":"string","description":"Face recognition model used.","example":"VGG-Face"},"performedAt":{"type":"number","description":"Timestamp when the verification was performed (Unix ms).","example":1717430830000},"error":{"type":"string","description":"Error message if the verification failed, null on success.","nullable":true}},"required":["verified","distance","threshold","model","performedAt"]},"KycSessionOutputDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique session identifier.","example":"665f1a2b3c4d5e6f7a8b9c0d"},"organizationId":{"type":"string","description":"Organization that owns this session."},"externalId":{"type":"string","description":"External reference ID provided at creation.","example":"usr_abc123"},"customerName":{"type":"string","description":"Customer display name.","example":"John Doe"},"customerEmail":{"type":"string","description":"Customer email address.","example":"john@example.com"},"state":{"type":"string","description":"Current session state.","enum":["home","permission-granting","dv-get-started","dv-document-selection","dv-document-upload","dv-positioning-front","dv-capturing-front","dv-flip-prompt","dv-positioning-back","dv-capturing-back","dv-complete","lv-get-started","lv-initializing","lv-aligning","lv-countdown","lv-complete","lv-timeout"],"example":"home"},"data":{"description":"Session data including country and document type selections.","allOf":[{"$ref":"#/components/schemas/KycSessionDataOutputDTO"}]},"isInvalid":{"type":"boolean","description":"Whether the session has been flagged as invalid (e.g. exceeded attempt limit).","example":false},"isComplete":{"type":"boolean","description":"Whether the KYC verification flow has been completed.","example":false},"createdAt":{"type":"number","description":"Session creation timestamp (Unix ms).","example":1717430827000},"expiresAt":{"type":"number","description":"Session expiry timestamp (Unix ms). Null after completion.","example":1717434427000,"nullable":true},"completedAt":{"type":"number","description":"Completion timestamp (Unix ms). Null if not yet completed.","nullable":true},"documentVerification":{"description":"Document verification result, populated once document images are processed.","nullable":true,"allOf":[{"$ref":"#/components/schemas/KycDocumentVerificationDTO"}]},"faceVerification":{"description":"Face verification result comparing the document photo with a liveness frame.","nullable":true,"allOf":[{"$ref":"#/components/schemas/KycFaceVerificationDTO"}]}},"required":["id","organizationId","state","data","isInvalid","isComplete","createdAt"]},"CreateKycSessionOutputDTO":{"type":"object","properties":{"session":{"description":"The created KYC session.","allOf":[{"$ref":"#/components/schemas/KycSessionOutputDTO"}]},"token":{"type":"string","description":"Short-lived JWT token for customer access to the session."},"sessionUrl":{"type":"string","description":"Full URL the customer should visit to complete KYC verification.","example":"https://kyc.example.com/kyc/665f1a2b3c4d5e6f7a8b9c0d?token=eyJ..."}},"required":["session","token","sessionUrl"]},"DateRange":{"type":"object","properties":{}},"KycSessionFiltersDTO":{"type":"object","properties":{"searchQuery":{"type":"string","description":"Free-text search across session ID, external ID, customer name, and email.","example":"john"},"state":{"type":"string","description":"Filter by session state.","enum":["home","permission-granting","dv-get-started","dv-document-selection","dv-document-upload","dv-positioning-front","dv-capturing-front","dv-flip-prompt","dv-positioning-back","dv-capturing-back","dv-complete","lv-get-started","lv-initializing","lv-aligning","lv-countdown","lv-complete","lv-timeout"],"example":"home"},"isComplete":{"type":"boolean","description":"Filter by completion status.","example":false},"isInvalid":{"type":"boolean","description":"Filter by invalid/flagged status.","example":false},"createdAt":{"description":"Filter by creation date range (start/end as ISO 8601 strings).","allOf":[{"$ref":"#/components/schemas/DateRange"}]},"sortBy":{"type":"string","description":"Field to sort by.","enum":["createdAt","expiresAt","completedAt"],"default":"createdAt"},"sortOrder":{"type":"string","description":"Sort direction.","enum":["asc","desc"],"default":"desc"},"limit":{"type":"number","description":"Maximum number of results to return (1–100).","minimum":1,"maximum":100,"default":50,"example":20},"offset":{"type":"number","description":"Number of results to skip for pagination.","minimum":0,"default":0,"example":0}}},"PaginatedKycSessionsDTO":{"type":"object","properties":{"sessions":{"description":"List of KYC sessions matching the query.","type":"array","items":{"$ref":"#/components/schemas/KycSessionOutputDTO"}},"totalCount":{"type":"number","description":"Total number of sessions matching the filters (before pagination).","example":42}},"required":["sessions","totalCount"]},"DeleteSessionOutputDTO":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the deletion was successful.","example":true}},"required":["success"]},"FileInput":{"type":"object","properties":{"base64Data":{"type":"string","description":"Base64 encoded file data (required if url is not provided)","example":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},"url":{"type":"string","description":"URL to fetch the file from (required if base64Data is not provided)","example":"https://example.com/documents/invoice.pdf"},"mimeType":{"type":"string","description":"MIME type of the file (e.g., image/jpeg, application/pdf)","example":"image/jpeg"},"filename":{"type":"string","description":"Original filename (optional)","example":"document.pdf"}},"required":["mimeType"]},"InitiateDocumentProcessingInput":{"type":"object","properties":{"processorId":{"type":"string","description":"ID of the document processor to use.","enum":["INVOICE","SRI_LANKA_ID","SRI_LANKA_FORM1_COMPANY_REGISTRATION","SRI_LANKA_FORM15_ANNUAL_RETURN"],"example":"INVOICE"},"files":{"description":"Array of files to process (provide base64 data or URL for each file)","example":[{"base64Data":"base64-encoded-file-data...","mimeType":"application/pdf","filename":"invoice.pdf"}],"type":"array","items":{"$ref":"#/components/schemas/FileInput"}},"inputData":{"type":"object","description":"Optional key-value context passed to the AI for cross-checking extracted document fields against known values.\n\n**INVOICE** — supported keys:\n- `expectedVendor` — supplier name to verify against the document\n- `expectedAmount` — total amount to verify against the document\n\n**SRI_LANKA_ID** — supported keys:\n- `name` — full name to match against the document\n- `dateOfBirth` — expected date of birth (YYYY-MM-DD)\n- `idNumber` — NIC or passport number to verify\n- `address` — residential address to compare (warning-level check)","example":{"expectedVendor":"ACME Corp","expectedAmount":"1500.00"}},"shouldCropImages":{"type":"boolean","description":"Whether to crop images before processing (default: true). When true, document images are cropped before validation and extraction.","default":true},"backgroundProcessing":{"type":"boolean","description":"Whether processing should happen in the background (default: true). If true, validation and extraction are performed asynchronously; if false, waits for all processing to complete before returning a response.","default":true}},"required":["processorId","files"]},"DocumentProcessorTypeDTO":{"type":"object","properties":{}}}}}