{ "openapi": "3.1.0", "info": { "title": "Checklynx API", "version": "1.3.4", "description": "REST API for AML screening, batch screening, adverse media checks, transaction-party screening, and outbound webhook event contracts. Authenticate API requests with the x-api-key header.\n\n## Sanctions Sources\n\nUse these values with `include_only_sanction_source_id` to restrict AML screening to specific sanctions sources.\n\n| Source ID | Source name | Region |\n| --- | --- | --- |\n| `REPET` | Argentina REPET | Argentina |\n| `AUCL` | Australia DFAT Consolidated Sanctions List | Australia |\n| `BETRAS` | Belgium Treasury National Financial Sanctions List | Belgium |\n| `BCEAF` | Portal da Transparencia CEAF Sanctions | Brazil |\n| `BCEIS` | Portal da Transparencia CEIS Sanctions | Brazil |\n| `BCEPIM` | Portal da Transparencia CEPIM Sanctions | Brazil |\n| `BCNEP` | Portal da Transparencia CNEP Sanctions | Brazil |\n| `BLEAG` | Portal da Transparencia Leniency Agreements | Brazil |\n| `BRDISQ` | Banco Central do Brasil Register of Persons Disqualified from Senior Roles | Brazil |\n| `BRTCLUB` | TCU Ineligíveis / Licitantes Inidôneos | Brazil |\n| `CATL` | Canadian Counter-Terrorism Entity List | Canada |\n| `CCAS` | Consolidated Canadian Autonomous Sanctions List | Canada |\n| `EUCOM` | EU Consolidated Sanctions List | EU |\n| `EUCOMT` | EU Air Safety List | EU |\n| `EUCOV` | Consolidated List of Designated Vessels | EU |\n| `EUTB` | Consolidated List of Travel Restrictions | EU |\n| `MEFSIN` | Ministère de L'Économie, des Finances et de la Souveraineté | France |\n| `INMHA` | India terrorist organisations | India |\n| `NSEBI` | Securities and Exchange Board of India Debarred entities | India |\n| `AFRDB` | African Development Bank Debarment and Sanctions | International |\n| `ASIDB` | Asian Development Bank | International |\n| `EBRD` | EBRD Ineligible Entities | International |\n| `IAMDB` | IDB Sanctioned Firms and Individuals | International |\n| `TMOU` | Tokyo MOU Detention List (APCIS) | International |\n| `TWB` | World Bank Debarred Firms and Individuals | International |\n| `UNSC` | United Nations Consolidated List | International |\n| `NBCTF` | Israel NBCTF Terror List | Israel |\n| `JESL` | Ministry of Finance. Economic Sanctions Measures | Japan |\n| `JMETI` | METI End User List | Japan |\n| `CSSF` | CSSF Notifications Received List | Luxembourg |\n| `MYKDN` | Malaysia KDN sanctions list | Malaysia |\n| `NETL` | Netherlands National Terrorism List | Netherlands |\n| `NZMOFA` | New Zealand Sanctions Register | New Zealand |\n| `NIGSAC` | Nigeria Sanctions List | Nigeria |\n| `PLMSWIA` | Polish sanctions list of individuals and entities | Poland |\n| `SINMAS` | Monetary Authority of Singapore | Singapore |\n| `FSCA` | South Africa FSCA Enforcement Actions | South Africa |\n| `OCPO` | South African Restricted Suppliers | South Africa |\n| `SAFIC` | South Africa FIC Targeted Financial Sanctions List | South Africa |\n| `SSSA` | Switzerland SECO Sanctions Search | Switzerland |\n| `UAELT` | UAE Local Terrorist List | UAE |\n| `OFSI` | UK Sanctions List Consolidated | UK |\n| `UKDD` | UK Disqualified Officers | UK |\n| `UKRNSDC` | Ukraine NSDC | Ukraine |\n| `UKRTEL` | Ukraine FIU terrorist blacklist | Ukraine |\n| `AKHR` | Anti-Kleptocracy and Human Rights visa restrictions | USA |\n| `BISN` | Bureau of International Security and Nonproliferation Sanctions | USA |\n| `BISPL` | US Consolidated Screening List (BIS) | USA |\n| `DDTC` | DDTC Debarment List | USA |\n| `FINCEN` | FinCEN Special Measures | USA |\n| `OCC` | Office of the Comptroller of the Currency | USA |\n| `OFACCSL` | Office of Foreign Assets Control. Consolidated Sanctions List | USA |\n| `OFACSDN` | Office of Foreign Assets Control SDN List | USA |\n| `OFCUB` | Cuba Prohibited Accommodations List | USA |\n| `USCBP` | CBP Withhold Release Orders & Findings | USA |\n| `USUFLPA` | Uyghur Forced Labor Entity List | USA |" }, "servers": [ { "url": "https://api.checklynx.com/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Screening", "description": "AML checks against sanctions, PEP, and wanted-list datasets." }, { "name": "Adverse Media", "description": "Open-source and news reference checks for adverse media signals." }, { "name": "Transaction Screening", "description": "Screen parties in a payment, transfer, order, or other client transaction reference, then retrieve run and reference results." }, { "name": "Webhooks", "description": "Outbound webhook event contracts delivered by Checklynx to subscriber URLs." } ], "paths": { "/check/sanctions_pep": { "post": { "tags": [ "Screening" ], "summary": "Run an AML screening search", "description": "Search sanctions, politically exposed person, and wanted-list data for an individual, entity, vessel, or aircraft. This endpoint does not create a customer or case record.", "operationId": "createAmlScreening", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlSearchRequest" }, "examples": { "sanctionedIndividual": { "summary": "Individual sanctions search", "value": { "search_term": "Hamid Raja Chala Al-Tikriti", "fuzziness": "1", "exclude_related_close_associate": false, "filters": { "source_type": [ "sanctions" ], "nationality": [ "IQ", "SY" ], "group_type": [ "individual" ], "gender": [ "male" ], "birth_year": [ "1950" ] } } }, "entity": { "summary": "Entity search", "value": { "search_term": "Trading & Construction", "filters": { "source_type": [ "sanctions" ], "nationality": [ "SG" ], "group_type": [ "entity" ] } } }, "identity": { "summary": "Identity search", "value": { "search_identity": "P123456789", "filters": { "source_type": [ "sanctions" ], "group_type": [ "individual" ] } } } } } } }, "responses": { "200": { "description": "Screening results and match profiles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlSearchResponse" } } } }, "400": { "description": "Invalid request body or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingSearchInput": { "summary": "Missing search input", "value": { "code": "400_BAD_REQUEST_SEARCH", "message": "Missing search term or identity" } } } } } }, "401": { "$ref": "#/components/responses/MissingAuthenticationToken" }, "403": { "$ref": "#/components/responses/SubscriptionInactive" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/check/sanctions_pep/batch": { "post": { "tags": [ "Screening" ], "summary": "Run AML screening for multiple targets", "description": "Perform multiple AML checks in a single request. Batch-wide controls such as source_type apply to all check_items, and each item can include its own request_item_id for result correlation.", "operationId": "createAmlBatchScreening", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlBatchRequest" }, "examples": { "multipleIndividuals": { "summary": "Multiple individual checks", "value": { "fuzziness": "1", "source_type": [ "sanctions", "pep", "wanted" ], "exclude_deceased": true, "exclude_related_close_associate": false, "check_items": [ { "request_item_id": "u1i1", "search_term": "Joe Doe", "filters": { "group_type": [ "individual" ], "nationality": [ "RU" ], "gender": [ "male" ] } }, { "request_item_id": "px2", "search_term": "Maria Vladimirovna Vorontsova", "filters": { "group_type": [ "individual" ], "nationality": [ "RU" ], "gender": [ "female" ] } } ] } }, "mixedNameAndIdentity": { "summary": "Mixed name and identity checks", "value": { "fuzziness": "1", "source_type": [ "sanctions", "pep", "wanted" ], "exclude_deceased": true, "exclude_related_close_associate": false, "check_items": [ { "request_item_id": "person-name-1", "search_term": "John Smith", "filters": { "group_type": [ "individual" ], "nationality": [ "US" ] } }, { "request_item_id": "person-passport-1", "search_identity": "P123456789", "filters": { "group_type": [ "individual" ], "source_type": [ "sanctions" ] } }, { "request_item_id": "vessel-imo-1", "search_identity": "9305221", "filters": { "group_type": [ "vessel" ], "source_type": [ "sanctions" ] } } ] } } } } } }, "responses": { "200": { "description": "A map keyed by each request_item_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlBatchResponse" } } } }, "400": { "description": "Invalid request body or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingCheckItems": { "summary": "Missing check_items", "value": { "code": "400_BAD_REQUEST_SEARCH_BATCH", "message": "check_items is required" } }, "emptyCheckItems": { "summary": "Empty check_items", "value": { "code": "400_BAD_REQUEST_BODY", "message": "Invalid request body [array is too short: must have at least 1 elements but instance has 0 elements]" } }, "malformedRequestBody": { "summary": "Malformed request body", "value": { "code": "400_BAD_REQUEST_BODY", "message": "Invalid request body [Unknown error parsing request body]" } } } } } }, "401": { "$ref": "#/components/responses/MissingAuthenticationToken" }, "403": { "$ref": "#/components/responses/SubscriptionInactive" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/check/adv_media": { "post": { "tags": [ "Adverse Media" ], "summary": "Run an adverse media check", "description": "Search open sources and news references for adverse media signals related to an individual, entity, or organization. This endpoint does not create a customer or case record.", "operationId": "createAdverseMediaCheck", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdverseMediaRequest" }, "examples": { "person": { "summary": "Person or organization search", "value": { "search_term": "Crowe UK LLP" } } } } } }, "responses": { "200": { "description": "Adverse media references and AI assessment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdverseMediaResponse" } } } }, "400": { "description": "Invalid request body or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingSearchTerm": { "summary": "Missing search term", "value": { "code": "400_BAD_REQUEST_ADVERSE_MEDIA", "message": "Missing search term" } } } } } }, "401": { "$ref": "#/components/responses/MissingAuthenticationToken" }, "403": { "$ref": "#/components/responses/SubscriptionInactive" }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/transactions": { "get": { "tags": [ "Transaction Screening" ], "summary": "List transaction reference aggregates", "description": "Dashboard/list endpoint for transaction screening. `GET /v1/transactions` returns a paged list of transaction reference aggregates: one row per client-supplied `transaction_reference_id`, not one row per individual screening run.\n\nUse it to answer questions such as:\n- Which payment references currently have AML hits?\n- Show all transaction references with hits or clears.\n- For this payment reference, what is the aggregate screening state?\n- Which screening products contributed to the latest aggregate state?", "operationId": "listTransactionScreenings", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "hit_status", "in": "query", "schema": { "type": "string", "enum": [ "hit", "clear", "all" ], "default": "hit" }, "description": "Filter by aggregate hit status. Use all to include both hit and clear references." }, { "name": "transaction_reference_id", "in": "query", "schema": { "type": "string" }, "description": "Optional client transaction/payment reference to filter by." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paged transaction-screening reference aggregates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionScreeningListResponse" } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidHitStatus": { "summary": "Invalid hit status", "value": { "code": "400_BAD_REQUEST_TRANSACTION_SCREENING", "message": "hit_status must be hit, clear, or all" } } } } } }, "403": { "description": "Invalid API key or transaction screening disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "Invalid API key", "value": { "code": "403_INVALID_API_KEY", "message": "Forbidden " } }, "featureDisabled": { "summary": "Transaction screening disabled", "value": { "code": "403_FEATURE_DISABLED_TRANSACTION_SCREENING", "message": "TRANSACTION_SCREENING is not enabled" } } } } } }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Create transaction screening run", "description": "Creates one transaction-screening run for one client transaction reference.\n\nBefore calling this endpoint, prepare:\n- `screening.screening_profile_id`: required in the JSON body. Create or choose an active AML screening profile in the Checklynx dashboard under Building Blocks, then copy its `sp_...` id. This selects sources, search modes, fuzziness, deceased handling, associate handling, and source filters.\n- `transaction.transaction_reference_id`: required in the JSON body. Use your own payment, order, transfer, or transaction id. This is a business reference, not an idempotency key; every POST creates a new run.\n- `transaction.parties[]`: required in the JSON body. Add every debtor, creditor, customer, counterparty, agent, or merchant you want screened. Each party needs `role` plus `name` or `identity_documents[]`.\n- `transaction.parties[].external_customer_id`: optional in the JSON body. Send it only when that party is already a customer you created in Checklynx with your own customer id. Do not send Checklynx internal `customer_id`.", "operationId": "createTransactionScreening", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionScreeningCreateRequest" }, "examples": { "minimalTransaction": { "summary": "Minimal transaction screening", "description": "Use this shape when you want to screen transaction parties without linking them to existing Checklynx customers.", "value": { "screening": { "screening_profile_id": "sp_your_active_profile_id" }, "transaction": { "transaction_reference_id": "pay_12345", "type": "bank_payment", "occurred_at": "2026-05-01T10:15:30Z", "amount": { "value": "1000.00", "currency": "EUR" }, "parties": [ { "role": "debtor", "name": "John Smith" }, { "role": "creditor", "name": "Jane Doe" } ] } } }, "knownCustomerLinking": { "summary": "Transaction with known customer ids", "description": "Use external_customer_id only when the party maps to a customer you created in Checklynx with your own customer id.", "value": { "screening": { "screening_profile_id": "sp_your_active_profile_id" }, "transaction": { "transaction_reference_id": "pay_12345", "type": "bank_payment", "occurred_at": "2026-05-01T10:15:30Z", "amount": { "value": "1000.00", "currency": "EUR" }, "parties": [ { "role": "debtor", "external_customer_id": "cust_sender_001", "name": "John Smith", "identity_documents": [ { "document_type": "passport", "document_number": "P123456789", "issuing_country": "US", "expiry_date": "2030-01-01" } ] }, { "role": "creditor", "external_customer_id": "cust_receiver_001", "name": "Jane Doe" } ] } } } } } }, "description": "Start by replacing `screening.screening_profile_id` with an active `sp_...` profile id from Dashboard > Building Blocks. Then set your `transaction.transaction_reference_id` and add the parties to screen." }, "responses": { "201": { "description": "Transaction screening run created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionScreeningRun" } } } }, "400": { "description": "Invalid request body or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidRequest": { "summary": "Validation error", "value": { "code": "400_BAD_REQUEST_TRANSACTION_SCREENING", "message": "transaction must be an object" } } } } } }, "403": { "description": "Invalid API key or transaction screening disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "Invalid API key", "value": { "code": "403_INVALID_API_KEY", "message": "Forbidden " } }, "featureDisabled": { "summary": "Transaction screening disabled", "value": { "code": "403_FEATURE_DISABLED_TRANSACTION_SCREENING", "message": "TRANSACTION_SCREENING is not enabled" } } } } } }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Transaction Screening" ] } }, "/transactions/{id}": { "get": { "summary": "Get transaction screening run", "operationId": "getTransactionScreening", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction screening run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionScreeningRun" } } } }, "403": { "description": "Invalid API key or transaction screening disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "Invalid API key", "value": { "code": "403_INVALID_API_KEY", "message": "Forbidden " } }, "featureDisabled": { "summary": "Transaction screening disabled", "value": { "code": "403_FEATURE_DISABLED_TRANSACTION_SCREENING", "message": "TRANSACTION_SCREENING is not enabled" } } } } } }, "404": { "description": "Transaction screening run not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notFound": { "summary": "Run not found", "value": { "code": "404_NOT_FOUND_TRANSACTION_SCREENING", "message": "transaction screening not found" } } } } } }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Transaction Screening" ], "description": "Returns one transaction-screening run by Checklynx-generated run id. Use this endpoint when you saved the `id` returned by `POST /transactions` and need to audit or re-fetch the exact screening execution." } }, "/transactions/references/{transaction_reference_id}": { "get": { "summary": "Get transaction reference aggregate", "operationId": "getTransactionReferenceAggregate", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_reference_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Aggregate view for all screening runs associated with the client transaction reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionReferenceAggregate" } } } }, "403": { "description": "Invalid API key or transaction screening disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "Invalid API key", "value": { "code": "403_INVALID_API_KEY", "message": "Forbidden " } }, "featureDisabled": { "summary": "Transaction screening disabled", "value": { "code": "403_FEATURE_DISABLED_TRANSACTION_SCREENING", "message": "TRANSACTION_SCREENING is not enabled" } } } } } }, "404": { "description": "Transaction reference not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notFound": { "summary": "Reference not found", "value": { "code": "404_NOT_FOUND_TRANSACTION_REFERENCE", "message": "transaction reference not found" } } } } } }, "429": { "$ref": "#/components/responses/Throttled" }, "500": { "$ref": "#/components/responses/InternalError" } }, "tags": [ "Transaction Screening" ], "description": "Returns the aggregate view for all transaction-screening runs associated with the same client `transaction_reference_id`. This is a reference aggregate, not a unique transaction lookup, because the same client reference can have multiple screening runs." } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "BadRequest": { "description": "Invalid request body or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "amlSearch": { "summary": "AML search validation error", "value": { "code": "400_BAD_REQUEST_SEARCH", "message": "Missing search term or identity" } }, "adverseMedia": { "summary": "Adverse media validation error", "value": { "code": "400_BAD_REQUEST_ADVERSE_MEDIA", "message": "Missing search term" } }, "transactionScreening": { "summary": "Transaction screening validation error", "value": { "code": "400_BAD_REQUEST_TRANSACTION_SCREENING", "message": "transaction must be an object" } } } } } }, "MissingAuthenticationToken": { "description": "Wrong endpoint path or unsupported route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingAuthenticationToken": { "summary": "Wrong endpoint path", "value": { "code": "401_MISSING_AUTHENTICATION_TOKEN", "message": "Missing Authentication Token " } } } } } }, "SubscriptionInactive": { "description": "Invalid API key, missing API key, or inactive subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "Invalid API key", "value": { "code": "403_INVALID_API_KEY", "message": "Forbidden " } }, "subscriptionInactive": { "summary": "Subscription inactive", "value": { "code": "403_SUBSCRIPTION_INACTIVE", "message": "Subscription not active" } } } } } }, "Throttled": { "description": "Too many requests. Wait and retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "throttled": { "summary": "Rate limited", "value": { "code": "429_THROTTLED", "message": "Too many requests, please retry later" } } } } } }, "InternalError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internalError": { "summary": "Internal error", "value": { "code": "500_INTERNAL_ERROR", "message": "Internal error" } } } } } } }, "schemas": { "AmlSearchRequest": { "type": "object", "description": "Provide exactly one of search_term or search_identity. Use search_term for name-based screening and search_identity for identifier-based screening. Filters refine the target set before scoring.", "properties": { "search_term": { "type": "string", "minLength": 3, "description": "Name-based search input, such as a person name, alias, company name, vessel name, or aircraft name. Do not put passports, tax IDs, document numbers, or other identifiers here; use search_identity for those values." }, "search_identity": { "type": "string", "description": "Identifier-based search input, such as a passport number, tax ID, national ID, document number, or similar identity value." }, "fuzziness": { "type": "string", "enum": [ "0", "1", "2" ], "default": "1", "description": "0 is strict, 1 is default, and 2 is broad." }, "search_logic": { "type": "string", "enum": [ "OR", "AND" ], "default": "OR", "description": "Search operator used for query terms." }, "exclude_related_close_associate": { "type": "boolean", "default": false, "description": "When true, excludes matches triggered only through relatives or close associates." }, "filters": { "$ref": "#/components/schemas/AmlFilters" } }, "oneOf": [ { "required": [ "search_term" ] }, { "required": [ "search_identity" ] } ] }, "AmlBatchRequest": { "type": "object", "required": [ "check_items" ], "properties": { "fuzziness": { "type": "string", "enum": [ "0", "1", "2" ], "default": "1" }, "source_type": { "type": "array", "items": { "$ref": "#/components/schemas/SourceType" }, "default": [ "sanctions", "pep", "wanted" ], "description": "Batch-wide source selection. Keep this at the request root, not inside check_items[].filters." }, "exclude_deceased": { "type": "boolean", "default": true }, "exclude_related_close_associate": { "type": "boolean", "default": false }, "include_only_sanction_source_id": { "type": "array", "items": { "type": "string" }, "description": "Restricts batch results to specific sanction source IDs. This is a top-level batch field and cannot be combined with exclude_sanction_source_id." }, "exclude_sanction_source_id": { "type": "array", "items": { "type": "string" }, "deprecated": true, "description": "Deprecated top-level batch field that excludes specific sanction source IDs. Prefer include_only_sanction_source_id for new integrations. Cannot be combined with include_only_sanction_source_id." }, "check_items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AmlBatchItem" } } } }, "AmlBatchItem": { "type": "object", "description": "Batch item to screen. Use request_item_id to correlate the response.", "properties": { "request_item_id": { "type": "string", "description": "Preferred client-defined ID used to correlate the item with its response." }, "search_term": { "type": "string", "minLength": 3, "description": "Name-based search input, such as a person name, alias, company name, vessel name, or aircraft name. Do not put passports, tax IDs, document numbers, or other identifiers here; use search_identity for those values." }, "search_identity": { "type": "string", "description": "Identifier-based search input, such as a passport number, tax ID, national ID, document number, or similar identity value." }, "filters": { "$ref": "#/components/schemas/AmlBatchItemFilters" } }, "allOf": [ { "required": [ "request_item_id" ] }, { "oneOf": [ { "required": [ "search_term" ] }, { "required": [ "search_identity" ] } ] } ] }, "AmlBatchItemFilters": { "type": "object", "description": "Item-specific filters for a batch check. Batch-wide fields such as source_type, exclude_deceased, exclude_related_close_associate, and include_only_sanction_source_id belong at the request root.", "properties": { "group_type": { "type": "array", "items": { "type": "string", "enum": [ "individual", "entity", "vessel", "aircraft" ] }, "description": "Target type. Unknown target types are not filtered out." }, "nationality": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 country codes." }, "gender": { "type": "array", "items": { "type": "string", "enum": [ "male", "female" ] } }, "birth_year": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{4}$" } } } }, "AmlFilters": { "type": "object", "properties": { "group_type": { "type": "array", "items": { "type": "string", "enum": [ "individual", "entity", "vessel", "aircraft" ] }, "description": "Target type. Unknown target types are not filtered out." }, "nationality": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 country codes." }, "source_type": { "type": "array", "items": { "$ref": "#/components/schemas/SourceType" } }, "gender": { "type": "array", "items": { "type": "string", "enum": [ "male", "female" ] } }, "birth_year": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{4}$" } }, "exclude_related_close_associate": { "type": "boolean", "default": false }, "exclude_deceased": { "type": "boolean", "default": true }, "include_only_sanction_source_id": { "type": "array", "items": { "type": "string" }, "description": "Restrict results to specific Checklynx sanctions source IDs. See the Sanctions Sources section for the full source ID catalog. Cannot be combined with exclude_sanction_source_id." }, "exclude_sanction_source_id": { "type": "array", "items": { "type": "string" }, "deprecated": true, "description": "Deprecated filter that excludes specific sanction source IDs. Prefer include_only_sanction_source_id for new integrations. Cannot be combined with include_only_sanction_source_id." } } }, "SourceType": { "type": "string", "enum": [ "pep", "sanctions", "wanted" ] }, "AmlSearchResponse": { "type": "object", "required": [ "results", "match_profiles" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScreeningResult" } }, "match_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/MatchProfile" } } } }, "AmlBatchResponse": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AmlSearchResponse" }, "description": "Object keyed by request_item_id." }, "ScreeningResult": { "type": "object", "required": [ "id", "score", "target", "source" ], "properties": { "id": { "type": "string" }, "score": { "type": "string", "description": "Relative relevance score from 1.0 to 5.0, returned as a string." }, "target": { "$ref": "#/components/schemas/Target" }, "source": { "$ref": "#/components/schemas/Source" }, "case": { "type": "array", "items": { "$ref": "#/components/schemas/Case" } } } }, "Target": { "type": "object", "description": "Normalized target data returned from the matched source.", "properties": { "name": { "type": "string" }, "first_name": { "type": "string" }, "second_name": { "type": "string" }, "third_name": { "type": "string" }, "group_type": { "type": "string" }, "gender": { "type": "string" }, "nationality": { "type": "array", "items": { "type": "string" } }, "birth_year": { "type": "array", "items": { "type": "string" } }, "birth_date": { "type": "array", "items": { "type": "string" } }, "other_names": { "type": "array", "items": { "type": "string" } }, "associates": { "type": "array", "items": { "$ref": "#/components/schemas/Associate" } }, "identification": { "type": "array", "items": { "$ref": "#/components/schemas/Identification" } }, "address": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "birth_place": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "function": { "type": "array", "items": { "type": "string" } }, "occupation": { "type": "array", "items": { "type": "string" } }, "remarks": { "type": "array", "items": { "type": "string" } }, "title": { "type": "array", "items": { "type": "string" } }, "photo_url": { "type": "string", "format": "uri" }, "pep_active": { "type": "boolean" }, "is_deceased": { "type": "boolean" } }, "additionalProperties": true }, "Source": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "region": { "type": "string" }, "listing_id": { "type": "string" }, "source_type": { "$ref": "#/components/schemas/SourceType" } } }, "Case": { "type": "object", "properties": { "program": { "type": "string" }, "sanction_type": { "type": "string" }, "basis": { "type": "string" }, "designation_date": { "type": "string" }, "since": { "type": "string" }, "updated_on": { "type": "array", "items": { "type": "string" } }, "to": { "type": "string" }, "url": { "type": "string" }, "other_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "Associate": { "type": "object", "properties": { "type": { "type": "string" }, "details": { "type": "string" }, "value": { "type": "string" } } }, "Identification": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "details": { "type": "string" }, "issuer": { "type": "string" }, "issue_date": { "type": "string" } } }, "Address": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": true }, "MatchProfile": { "type": "object", "properties": { "match_profile_id": { "type": "string" }, "match_score": { "type": "string" }, "name": { "type": "string" }, "rca_name": { "type": "string" }, "rca_hit": { "type": "boolean" }, "id_hit": { "type": "boolean" }, "results_ids": { "type": "array", "items": { "type": "string" } } } }, "AdverseMediaRequest": { "type": "object", "required": [ "search_term" ], "properties": { "search_term": { "type": "string", "minLength": 3, "description": "Term used to search individuals, entities, or organizations in adverse media sources." } } }, "AdverseMediaResponse": { "type": "object", "properties": { "adverse_media": { "type": "array", "items": { "$ref": "#/components/schemas/AdverseMediaItem" } }, "AI_assessment_adverse_media": { "type": "string" } } }, "AdverseMediaItem": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "details": { "type": "string" }, "category": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "400_BAD_REQUEST_SEARCH" ] }, "message": { "type": "string", "examples": [ "Missing search term or identity" ] } } }, "TransactionScreeningCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "transaction", "screening" ], "properties": { "screening": { "$ref": "#/components/schemas/TransactionScreeningConfig", "description": "Required AML screening configuration. Create or choose this profile in the Checklynx dashboard under Building Blocks; the screening_profile_id must already exist and be active for your tenant." }, "transaction": { "$ref": "#/components/schemas/TransactionScreeningTransaction", "description": "Required client transaction, payment, order, or transfer context and the parties to screen." } }, "description": "Request body for creating one transaction-screening run. Required setup variables are an active screening_profile_id from the Checklynx dashboard Building Blocks tab, your transaction_reference_id, and at least one party to screen." }, "TransactionScreeningTransaction": { "type": "object", "additionalProperties": false, "required": [ "transaction_reference_id", "parties" ], "properties": { "transaction_reference_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Client transaction/payment reference. Not unique and not an idempotency key." }, "type": { "type": "string", "enum": [ "bank_payment", "card_payment", "remittance", "cash_deposit", "cash_withdrawal", "internal_transfer", "other" ], "description": "Optional client transaction type used for context and review filtering." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 timestamp for when the transaction occurred or was initiated." }, "amount": { "$ref": "#/components/schemas/TransactionAmount", "description": "Optional transaction amount and currency for review context." }, "parties": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/TransactionParty" }, "description": "Parties to screen in this transaction. Add every debtor, creditor, customer, counterparty, agent, intermediary, or merchant that should be AML-screened." } }, "description": "Client transaction context. Use transaction_reference_id to group related screening runs under your own business reference; it is not an idempotency key." }, "TransactionAmount": { "type": "object", "additionalProperties": false, "required": [ "value", "currency" ], "properties": { "value": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Decimal amount as a string to preserve precision." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 three-letter fiat currency code, for example EUR, USD, GBP." } } }, "TransactionParty": { "type": "object", "additionalProperties": false, "required": [ "role" ], "anyOf": [ { "required": [ "name" ] }, { "required": [ "identity_documents" ] } ], "properties": { "role": { "type": "string", "enum": [ "debtor", "creditor", "customer", "counterparty", "ultimate_debtor", "ultimate_creditor", "debtor_agent", "creditor_agent", "intermediary_agent", "merchant", "other" ], "description": "Role of this party in the transaction. Use other only when none of the specific debtor, creditor, customer, counterparty, agent, intermediary, or merchant roles fit." }, "external_customer_id": { "type": "string", "maxLength": 256, "description": "Customer id from your own system. Send the same value on a transaction party when that party is one of your known customers. If it does not resolve, screening still runs from the party request data, but Checklynx treats the party as an unlinked customer for that run." }, "name": { "type": "string", "maxLength": 512, "description": "Party name to screen. Use this for person names, aliases, company names, vessel names, or aircraft names.", "minLength": 1 }, "identity_documents": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/IdentityDocument" }, "description": "Structured identity evidence for the party, such as passport, national id, tax id, residence permit, driving license, or other document numbers." }, "filters": { "$ref": "#/components/schemas/PartyFilters", "description": "Optional party-level filters that narrow candidate AML results for this party." } }, "description": "One screened party in the transaction. Each party requires role plus name or identity_documents[]. external_customer_id is optional and is only for linking to a known customer." }, "IdentityDocument": { "type": "object", "additionalProperties": false, "required": [ "document_type", "document_number" ], "properties": { "document_type": { "type": "string", "enum": [ "passport", "national_id", "tax_id", "residence_permit", "driving_license", "other" ] }, "document_number": { "type": "string", "minLength": 1, "maxLength": 256 }, "issuing_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 issuing country code." }, "expiry_date": { "type": "string", "format": "date" } } }, "PartyFilters": { "type": "object", "additionalProperties": false, "properties": { "group_type": { "type": "array", "items": { "type": "string", "enum": [ "individual", "entity", "vessel", "aircraft" ] } }, "nationality": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "birth_year": { "type": "array", "items": { "type": "string", "pattern": "^(19|20)\\d{2}$" } }, "gender": { "type": "array", "items": { "type": "string", "enum": [ "male", "female" ] } } } }, "TransactionScreeningConfig": { "type": "object", "additionalProperties": false, "required": [ "screening_profile_id" ], "properties": { "screening_profile_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Required active Checklynx screening profile id. Create or choose the AML screening profile in the Checklynx dashboard under Building Blocks, then copy its `sp_...` id into this field. This selects the AML sources and matching behavior. Do not invent this value." } }, "description": "Screening configuration for transaction-party AML screening." }, "TransactionScreeningRun": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "transaction": { "$ref": "#/components/schemas/TransactionScreeningTransactionSummary" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "hit_status": { "type": "string", "enum": [ "hit", "clear" ] }, "hit_count": { "type": "integer", "minimum": 0, "description": "Number of actionable, unsuppressed AML result ids across all parties." }, "screening_summary": { "$ref": "#/components/schemas/TransactionScreeningSummary" }, "case_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionPartyScreeningResult" } } }, "required": [ "id", "transaction", "status", "hit_status", "hit_count", "screening_summary", "case_id", "created_at", "parties" ] }, "TransactionScreeningTransactionSummary": { "type": "object", "additionalProperties": false, "properties": { "transaction_reference_id": { "type": "string" }, "type": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "amount": { "$ref": "#/components/schemas/TransactionAmount" } }, "required": [ "transaction_reference_id" ] }, "TransactionPartyScreeningResult": { "type": "object", "additionalProperties": true, "properties": { "role": { "type": "string" }, "external_customer_id": { "type": "string", "nullable": true, "description": "Normalized client customer id echoed from the request, or null when not provided." }, "name": { "type": "string", "nullable": true, "description": "Party name echoed from the request, or null when the party was screened only by identity document." }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "hit_status": { "type": "string", "enum": [ "hit", "clear" ] }, "hit_count": { "type": "integer", "minimum": 0, "description": "Number of actionable, unsuppressed AML result ids for this party." }, "screening_summary": { "$ref": "#/components/schemas/TransactionScreeningSummary" }, "results": { "type": "array", "items": { "type": "object" } }, "match_profiles": { "type": "array", "items": { "type": "object" } }, "customer_type": { "type": "string", "nullable": true, "enum": [ "individual", "entity" ], "description": "Customer type when external_customer_id resolves, otherwise null." }, "customer_resolved": { "type": "boolean", "description": "True when external_customer_id resolved to a known Checklynx customer. Internal Checklynx customer ids are not exposed." } }, "required": [ "role", "external_customer_id", "name", "customer_resolved", "customer_type", "status", "hit_status", "hit_count", "screening_summary", "results", "match_profiles" ] }, "TransactionReferenceAggregate": { "type": "object", "additionalProperties": false, "required": [ "transaction_reference_id", "hit_status", "hit_count", "screening_summary", "execution_status", "case_id", "created_at", "screenings", "next_cursor" ], "properties": { "transaction_reference_id": { "type": "string" }, "hit_status": { "type": "string", "enum": [ "hit", "clear" ] }, "hit_count": { "type": "integer", "minimum": 0, "description": "Number of actionable, unsuppressed AML result ids." }, "screening_summary": { "$ref": "#/components/schemas/TransactionScreeningSummary" }, "execution_status": { "type": "string", "enum": [ "completed", "running", "failed" ] }, "case_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "screenings": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionReferenceScreeningSummary" } }, "next_cursor": { "type": "string", "nullable": true } }, "description": "Aggregate view for all screening runs associated with one client transaction_reference_id. Suppressed-only results stay clear: no actionable hit, no case, and case_id is null." }, "TransactionReferenceScreeningSummary": { "type": "object", "additionalProperties": false, "required": [ "type", "latest_run_id", "status", "hit_status", "hit_count", "run_count", "screening_summary", "case_id", "created_at" ], "properties": { "type": { "type": "string", "enum": [ "aml", "sigap", "adverse_media" ] }, "latest_run_id": { "type": "string", "nullable": true, "description": "Latest screening run id for this screening type under the transaction reference." }, "status": { "type": "string", "enum": [ "completed", "running", "failed" ] }, "hit_status": { "type": "string", "enum": [ "hit", "clear" ] }, "hit_count": { "type": "integer", "minimum": 0, "description": "Number of actionable, unsuppressed result ids for this screening type." }, "run_count": { "type": "integer", "minimum": 0, "description": "Number of screening runs observed for this screening type under the transaction reference." }, "screening_summary": { "$ref": "#/components/schemas/TransactionScreeningSummary" }, "case_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionScreeningSummary": { "type": "object", "additionalProperties": false, "properties": { "total_hits": { "type": "integer", "minimum": 0, "description": "Total AML result ids returned before customer false-positive suppression." }, "suppressed_hits_total": { "type": "integer", "minimum": 0, "description": "Result ids hidden by existing false-positive decisions for a linked customer." }, "actionable_hits_total": { "type": "integer", "minimum": 0, "description": "Result ids remaining after suppression. This value drives hit_count and case creation." } } }, "TransactionScreeningListResponse": { "type": "object", "additionalProperties": false, "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionReferenceAggregate" } }, "next_cursor": { "type": "string", "nullable": true }, "reference": { "$ref": "#/components/schemas/TransactionReferenceAggregate" } } }, "WebhookEnvelope": { "type": "object", "additionalProperties": false, "required": [ "id", "event_id", "event_type", "occurred_at", "tenant_id", "schema_version", "data" ], "properties": { "id": { "type": "string", "description": "Webhook event id. Same value as event_id. Receivers should deduplicate deliveries by this value.", "example": "evt_abc123def456" }, "event_id": { "type": "string", "description": "Stable webhook event id. Use this for receiver-side idempotency and deduplication.", "example": "evt_abc123def456" }, "event_type": { "type": "string", "enum": [ "customer_screening.case.opened", "transaction_screening.case.opened" ], "description": "Public webhook event type." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when Checklynx created the webhook event." }, "tenant_id": { "type": "string", "description": "Checklynx tenant identifier associated with the event." }, "schema_version": { "type": "string", "description": "Webhook payload schema version.", "example": "1" }, "data": { "type": "object", "description": "Event-specific payload. Shape depends on event_type." } }, "description": "Canonical delivered webhook envelope." }, "CustomerScreeningCaseOpenedWebhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "required": [ "event_type", "data" ], "properties": { "event_type": { "type": "string", "const": "customer_screening.case.opened" }, "data": { "$ref": "#/components/schemas/CustomerScreeningCaseOpenedData" } } } ] }, "CustomerScreeningCaseOpenedData": { "type": "object", "additionalProperties": false, "required": [ "case_id", "case_type", "status", "review_status" ], "properties": { "case_id": { "type": "string", "example": "case_123" }, "case_type": { "type": "string", "enum": [ "screening" ], "example": "screening" }, "status": { "type": "string", "example": "open" }, "review_status": { "type": "string", "example": "pending" }, "external_customer_id": { "type": "string", "description": "Client customer id when the case can be linked to a known external customer.", "example": "client_customer_123" }, "customer_resolved": { "type": "boolean", "description": "True when external_customer_id resolved to a known Checklynx customer.", "example": true }, "screening_summary": { "type": "object", "additionalProperties": false, "properties": { "total_hits": { "type": "integer", "minimum": 0, "example": 3 }, "actionable_hits_total": { "type": "integer", "minimum": 0, "example": 2 } } } }, "description": "Payload for customer_screening.case.opened. Uses external client identifiers and does not expose internal Checklynx customer_id." }, "TransactionScreeningCaseOpenedWebhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "required": [ "event_type", "data" ], "properties": { "event_type": { "type": "string", "const": "transaction_screening.case.opened" }, "data": { "$ref": "#/components/schemas/TransactionScreeningCaseOpenedData" } } } ] }, "TransactionScreeningCaseOpenedData": { "type": "object", "additionalProperties": false, "required": [ "case_id", "case_type", "status", "review_status", "transaction_reference_id" ], "properties": { "case_id": { "type": "string", "example": "case_txn_abc123" }, "case_type": { "type": "string", "enum": [ "transaction_screening" ], "example": "transaction_screening" }, "status": { "type": "string", "example": "open" }, "review_status": { "type": "string", "example": "pending" }, "transaction_reference_id": { "type": "string", "description": "Client transaction/payment reference from the original transaction screening request.", "example": "pay_12345" }, "parties": { "type": "array", "description": "Optional party-level hit summary. Present when party-level hit records are available for the opened transaction case; otherwise omitted.", "items": { "$ref": "#/components/schemas/TransactionScreeningWebhookParty" } } }, "description": "Payload for transaction_screening.case.opened. Sent when transaction screening creates a new open case for actionable hits." }, "TransactionScreeningWebhookParty": { "type": "object", "additionalProperties": false, "required": [ "role", "customer_resolved", "hit_status", "hit_count" ], "properties": { "role": { "type": "string", "example": "debtor" }, "external_customer_id": { "type": "string", "nullable": true, "description": "Client customer id for this party when supplied and resolvable.", "example": "cust_sender_001" }, "customer_resolved": { "type": "boolean", "description": "True when the party is linked to a known Checklynx customer.", "example": true }, "hit_status": { "type": "string", "enum": [ "hit" ], "example": "hit" }, "hit_count": { "type": "integer", "minimum": 1, "example": 1 } } }, "WebhookReceiverResponse": { "type": "object", "additionalProperties": true, "description": "Receiver response body is ignored by Checklynx. Return any 2xx status to acknowledge delivery." } } }, "webhooks": { "customer_screening.case.opened": { "post": { "tags": [ "Webhooks" ], "summary": "Customer screening case opened webhook", "description": "Outbound event delivered to subscribed webhook URLs when a customer screening case is created in open state. Checklynx signs each request with X-Webhook-Signature. To verify it, compute base64(HMAC-SHA256(signing_secret, raw_request_body)) using the exact raw request body bytes received by your server before parsing JSON, then compare the result with the header. Reject requests with mismatched signatures and deduplicate retries by event_id.", "operationId": "receiveCustomerScreeningCaseOpenedWebhook", "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 HMAC SHA-256 signature. Verify by computing base64(HMAC-SHA256(signing_secret, raw_request_body)) over the exact raw request body bytes before parsing JSON." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerScreeningCaseOpenedWebhook" }, "examples": { "customerCaseOpened": { "summary": "Customer screening case opened", "value": { "id": "evt_abc123def456", "event_id": "evt_abc123def456", "event_type": "customer_screening.case.opened", "occurred_at": "2026-05-05T12:34:56Z", "tenant_id": "tenant_123", "schema_version": "1", "data": { "case_id": "case_123", "case_type": "screening", "status": "open", "review_status": "pending", "external_customer_id": "client_customer_123", "customer_resolved": true, "screening_summary": { "total_hits": 3, "actionable_hits_total": 2 } } } } } } } }, "responses": { "2XX": { "description": "Receiver accepted the event. Any 2xx response is treated as successful delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReceiverResponse" } } } } } } }, "transaction_screening.case.opened": { "post": { "tags": [ "Webhooks" ], "summary": "Transaction screening case opened webhook", "description": "Outbound event delivered to subscribed webhook URLs when transaction screening creates a new open case for actionable hits. Checklynx signs each request with X-Webhook-Signature. To verify it, compute base64(HMAC-SHA256(signing_secret, raw_request_body)) using the exact raw request body bytes received by your server before parsing JSON, then compare the result with the header. Reject requests with mismatched signatures and deduplicate retries by event_id.", "operationId": "receiveTransactionScreeningCaseOpenedWebhook", "parameters": [ { "name": "X-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 HMAC SHA-256 signature. Verify by computing base64(HMAC-SHA256(signing_secret, raw_request_body)) over the exact raw request body bytes before parsing JSON." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionScreeningCaseOpenedWebhook" }, "examples": { "transactionCaseOpened": { "summary": "Transaction screening case opened", "value": { "id": "evt_abc123def456", "event_id": "evt_abc123def456", "event_type": "transaction_screening.case.opened", "occurred_at": "2026-05-05T12:34:56Z", "tenant_id": "tenant_123", "schema_version": "1", "data": { "case_id": "case_txn_abc123", "case_type": "transaction_screening", "status": "open", "review_status": "pending", "transaction_reference_id": "pay_12345", "parties": [ { "role": "debtor", "external_customer_id": "cust_sender_001", "customer_resolved": true, "hit_status": "hit", "hit_count": 1 } ] } } } } } } }, "responses": { "2XX": { "description": "Receiver accepted the event. Any 2xx response is treated as successful delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReceiverResponse" } } } } } } } } }