# Checklynx API Export for LLMs and Codex This file is a machine-friendly integration guide for the public Checklynx API. It is intended for LLMs, Codex, and developer agents that need enough context to generate correct client code without guessing. Authoritative machine-readable schema: /openapi/checklynx.json Base URL: https://api.checklynx.com/v1 Auth header: `x-api-key: ` Content type for request bodies: `application/json` Do not treat examples as tenant-specific configuration. Placeholder ids such as `sp_your_active_profile_id` must be replaced with values from the customer's Checklynx dashboard. # Endpoint Map - POST /check/sanctions_pep: Run an AML screening search. - POST /check/sanctions_pep/batch: Run AML screening for multiple targets. - POST /check/adv_media: Run an adverse media check. - GET /transactions: List transaction reference aggregates. - POST /transactions: Create transaction screening run. - GET /transactions/{id}: Get transaction screening run. - GET /transactions/references/{transaction_reference_id}: Get transaction reference aggregate. - Webhook customer_screening.case.opened: Outbound case-opened event for customer screening cases. - Webhook transaction_screening.case.opened: Outbound case-opened event for transaction screening cases. # Global Rules - Never put the API key in query parameters or request bodies. Use the `x-api-key` header. - All JSON request examples are public request contracts. Do not invent fields not present in the OpenAPI schema. - For AML search, `search_term` and `search_identity` are different inputs. Do not mix them unless the OpenAPI/backend contract explicitly changes. - `search_term` is name-based: person names, aliases, company names, vessel names, or aircraft names. - `search_identity` is identifier-based: passport numbers, tax ids, national ids, document numbers, vessel IMO numbers, or similar identity values. - Do not mention or use private/internal source types that are not in the public `SourceType` enum. - Transaction screening setup values belong in the JSON request body. # Workflow Selection Use `POST /check/sanctions_pep` for one AML screening target without creating a customer or case record. Use `POST /check/sanctions_pep/batch` for many independent AML screening targets in one request without creating customer or case records. Use `POST /check/adv_media` for adverse media/open-source/news reference checks. Use `POST /transactions` to screen the parties in a payment, transfer, order, or other client transaction reference. Use webhooks when the integration needs asynchronous notifications that a screening case was opened. # AML Screening ## POST /check/sanctions_pep Run an AML screening search 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. Example: sanctionedIndividual ```json { "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" ] } } ``` Example: entity ```json { "search_term": "Trading & Construction", "filters": { "source_type": [ "sanctions" ], "nationality": [ "SG" ], "group_type": [ "entity" ] } } ``` Example: identity ```json { "search_identity": "P123456789", "filters": { "source_type": [ "sanctions" ], "group_type": [ "individual" ] } } ``` Request fields: - `search_term` (string, optional). - 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` (string, optional). - Identifier-based search input, such as a passport number, tax ID, national ID, document number, or similar identity value. - `fuzziness` (string, optional). Values: 0, 1, 2. - 0 is strict, 1 is default, and 2 is broad. - `search_logic` (string, optional). Values: OR, AND. - Search operator used for query terms. - `exclude_related_close_associate` (boolean, optional). - When true, excludes matches triggered only through relatives or close associates. - `filters` (AmlFilters, optional). Filter fields: - `group_type` (array, optional). - Target type. Unknown target types are not filtered out. - `nationality` (array, optional). - ISO 3166-1 alpha-2 country codes. - `source_type` (array, optional). - `gender` (array, optional). - `birth_year` (array, optional). - `exclude_related_close_associate` (boolean, optional). - `exclude_deceased` (boolean, optional). - `include_only_sanction_source_id` (array, optional). - Restrict results to specific Checklynx sanctions source IDs such as AUCL, CCAS, EUCOM, OFACSDN, or UNSC. Cannot be combined with exclude_sanction_source_id. - `exclude_sanction_source_id` (array, optional). - 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. Key rules: - Send exactly one of `search_term` or `search_identity`. - `search_term` has minimum length 3. - `source_type` values are: pep, sanctions, wanted. - `exclude_sanction_source_id` is deprecated. Prefer `include_only_sanction_source_id` for new integrations. - `exclude_sanction_source_id` and `include_only_sanction_source_id` are mutually exclusive. # Batch AML Screening ## POST /check/sanctions_pep/batch Run AML screening for multiple targets 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. Example: multipleIndividuals ```json { "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" ] } } ] } ``` Example: mixedNameAndIdentity ```json { "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" ] } } ] } ``` Batch request fields: - `fuzziness` (string, optional). Values: 0, 1, 2. - `source_type` (array, optional). - Batch-wide source selection. Keep this at the request root, not inside check_items[].filters. - `exclude_deceased` (boolean, optional). - `exclude_related_close_associate` (boolean, optional). - `include_only_sanction_source_id` (array, optional). - 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` (array, optional). - 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` (array, required). Batch item fields: - `request_item_id` (string, required). - Client-defined ID used to correlate the item with its response. - `search_term` (string, optional). - 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` (string, optional). - Identifier-based search input, such as a passport number, tax ID, national ID, document number, or similar identity value. - `filters` (AmlBatchItemFilters, optional). Batch item filter fields: - `group_type` (array, optional). - Target type. Unknown target types are not filtered out. - `nationality` (array, optional). - ISO 3166-1 alpha-2 country codes. - `gender` (array, optional). - `birth_year` (array, optional). Key rules: - `check_items[]` is required. - Each item must include `request_item_id`. - Each item sends exactly one of `search_term` or `search_identity`. - Batch-wide controls such as `source_type`, `exclude_deceased`, `exclude_related_close_associate`, and sanction source filters belong at the request root. - Item-level filters are target attributes only: `group_type`, `nationality`, `birth_year`, `gender`. # Adverse Media ## POST /check/adv_media Run an adverse media check 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. Example: person or organization ```json { "search_term": "Crowe UK LLP" } ``` Request fields: - `search_term` (string, required). - Term used to search individuals, entities, or organizations in adverse media sources. Key rules: - Use `search_term` for the person, entity, or organization name. - This endpoint is for adverse media context, not sanctions/PEP/wanted matching. - This endpoint does not create a customer or case record. # Transaction Screening ## POST /transactions Create transaction screening run Creates one transaction-screening run for one client transaction reference. Before calling this endpoint, prepare: - `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. - `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. - `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[]`. - `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`. Example: minimalTransaction ```json { "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" } ] } } ``` Example: knownCustomerLinking ```json { "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" } ] } } ``` Create request fields: - `screening` (TransactionScreeningConfig, required). - 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` (TransactionScreeningTransaction, required). - Required client transaction, payment, order, or transfer context and the parties to screen. Transaction fields: - `transaction_reference_id` (string, required). - Client transaction/payment reference. Not unique and not an idempotency key. - `type` (string, optional). Values: bank_payment, card_payment, remittance, cash_deposit, cash_withdrawal, internal_transfer, other. - Optional client transaction type used for context and review filtering. - `occurred_at` (string, optional). - Optional ISO 8601 timestamp for when the transaction occurred or was initiated. - `amount` (TransactionAmount, optional). - Optional transaction amount and currency for review context. - `parties` (array, required). - Parties to screen in this transaction. Add every debtor, creditor, customer, counterparty, agent, intermediary, or merchant that should be AML-screened. Party fields: - `role` (string, required). Values: debtor, creditor, customer, counterparty, ultimate_debtor, ultimate_creditor, debtor_agent, creditor_agent, intermediary_agent, merchant, other. - 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` (string, optional). - 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` (string, optional). - Party name to screen. Use this for person names, aliases, company names, vessel names, or aircraft names. - `identity_documents` (array, optional). - Structured identity evidence for the party, such as passport, national id, tax id, residence permit, driving license, or other document numbers. - `filters` (PartyFilters, optional). - Optional party-level filters that narrow candidate AML results for this party. Screening config fields: - `screening_profile_id` (string, required). - 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. Transaction setup variables developers must prepare: - `screening.screening_profile_id`: required. Create or choose an active AML screening profile in Checklynx Dashboard > Building Blocks, then copy the `sp_...` id into the JSON body. - `transaction.transaction_reference_id`: required. Use the client's payment/order/transfer/transaction id. It is not an idempotency key; each POST creates a new run. - `transaction.parties[]`: required. Add every debtor, creditor, customer, counterparty, agent, intermediary, merchant, or other party that should be screened. - `transaction.parties[].external_customer_id`: optional. Use only when the party is already a customer in the client's system and that customer was created in Checklynx with this same external id. Transaction party role values: - `debtor` - `creditor` - `customer` - `counterparty` - `ultimate_debtor` - `ultimate_creditor` - `debtor_agent` - `creditor_agent` - `intermediary_agent` - `merchant` - `other` Transaction request rules: - Each party needs `role` and either non-empty `name` or `identity_documents[]`. - Use role `other` only when no specific role fits. - Do not send Checklynx internal `customer_id`. - Public transaction party responses do not expose internal `customer_id`. - Use `customer_resolved` and `customer_type` to understand whether `external_customer_id` resolved to a known Checklynx customer. Transaction response fields: - `id` (string, required). - `transaction` (TransactionScreeningTransactionSummary, required). - `status` (string, required). Values: completed, failed. - `hit_status` (string, required). Values: hit, clear. - `hit_count` (integer, required). - Number of actionable, unsuppressed AML result ids across all parties. - `screening_summary` (TransactionScreeningSummary, required). - `case_id` (string, required). Nullable. - `created_at` (string, required). - `parties` (array, required). Transaction party response fields: - `role` (string, required). - `external_customer_id` (string, required). Nullable. - Normalized client customer id echoed from the request, or null when not provided. - `name` (string, required). Nullable. - Party name echoed from the request, or null when the party was screened only by identity document. - `status` (string, required). Values: completed, failed. - `hit_status` (string, required). Values: hit, clear. - `hit_count` (integer, required). - Number of actionable, unsuppressed AML result ids for this party. - `screening_summary` (TransactionScreeningSummary, required). - `results` (array, required). - `match_profiles` (array, required). - `customer_type` (string, required). Nullable. Values: individual, entity. - Customer type when external_customer_id resolves, otherwise null. - `customer_resolved` (boolean, required). - True when external_customer_id resolved to a known Checklynx customer. Internal Checklynx customer ids are not exposed. Suppression semantics: - `screening_summary.total_hits` counts result ids before customer false-positive suppression. - `screening_summary.suppressed_hits_total` counts result ids hidden by existing false-positive decisions for a linked customer. - `screening_summary.actionable_hits_total` drives `hit_count` and case creation. - Suppressed-only results have no actionable hit, no case, and `case_id: null`. # Transaction Screening Lookups ## GET /transactions/{id} Get transaction screening run 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. Parameters: - `id` (path, required): ## GET /transactions/references/{transaction_reference_id} Get transaction reference aggregate 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. Parameters: - `transaction_reference_id` (path, required): ## GET /transactions List transaction reference aggregates 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. Use it to answer questions such as: - Which payment references currently have AML hits? - Show all transaction references with hits or clears. - For this payment reference, what is the aggregate screening state? - Which screening products contributed to the latest aggregate state? Parameters: - `hit_status` (query, optional): Filter by aggregate hit status. Use all to include both hit and clear references. - `transaction_reference_id` (query, optional): Optional client transaction/payment reference to filter by. - `limit` (query, optional): - `cursor` (query, optional): Reference aggregate fields: - `transaction_reference_id` (string, required). - `hit_status` (string, required). Values: hit, clear. - `hit_count` (integer, required). - Number of actionable, unsuppressed AML result ids. - `screening_summary` (TransactionScreeningSummary, required). - `execution_status` (string, required). Values: completed, running, failed. - `case_id` (string, required). Nullable. - `created_at` (string, required). - `updated_at` (string, optional). - `screenings` (array, required). - `next_cursor` (string, required). Nullable. List response fields: - `items` (array, required). - `next_cursor` (string, required). Nullable. - `reference` (TransactionReferenceAggregate, optional). Reference screening summary fields: - `type` (string, required). Values: aml, sigap, adverse_media. - `latest_run_id` (string, required). Nullable. Latest screening run id for this screening type. - `status` (string, required). Values: completed, running, failed. - `hit_status` (string, required). Values: hit, clear. - `hit_count` (integer, required). - Number of actionable, unsuppressed result ids for this screening type. - `run_count` (integer, required). - Number of screening runs observed for this screening type under the transaction reference. - `screening_summary` (TransactionScreeningSummary, required). - `case_id` (string, required). Nullable. - `created_at` (string, required). - `updated_at` (string, optional). Lookup rules: - Use `GET /transactions/{id}` when you saved the immutable run id from `POST /transactions`. - Use `GET /transactions/references/{transaction_reference_id}` for the aggregate view of one client transaction reference. - Use `GET /transactions` to list reference aggregates with optional `hit_status`, `transaction_reference_id`, `limit`, and `cursor` filters. - `case_id` and `next_cursor` are nullable but present where required by the public contract. # Webhooks Webhooks are outbound HTTP POST requests sent by Checklynx to subscribed receiver URLs. They are not API endpoints that clients call. Receivers should return any 2xx status to acknowledge delivery. Supported public events: - `customer_screening.case.opened`: A customer screening case was created in open state. - `transaction_screening.case.opened`: A transaction screening case was created in open state. Delivered envelope fields: - `id` (string, required). Same value as event_id. - `event_id` (string, required). Stable webhook event id. Receivers should deduplicate deliveries by this value. - `event_type` (string, required). Values: customer_screening.case.opened, transaction_screening.case.opened. - `occurred_at` (string, required). ISO 8601 timestamp. - `tenant_id` (string, required). - `schema_version` (string, required). Current value: 1. - `data` (object, required). Event-specific payload. Signing: - Checklynx signs each outbound webhook request with `X-Webhook-Signature`. - Read the raw request body before parsing JSON. - Compute `base64(HMAC-SHA256(signing_secret, raw_request_body))`. - Compare the computed value with the `X-Webhook-Signature` header. - Reject the request if the signatures do not match. - Use `event_id` to deduplicate retries. - Do not parse and re-stringify the JSON before verification. Use the exact raw request body bytes received by your server. Example: customer screening case opened webhook ```json { "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 } } } ``` Example: transaction screening case opened webhook ```json { "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 } ] } } ``` Transaction webhook rules: - `transaction_screening.case.opened` is sent when transaction screening creates a new open case for actionable hits. - `data.parties[]` is optional. It is present when party-level hit records are available for the opened transaction case; otherwise it is omitted. - Use `data.transaction_reference_id` and `data.case_id` as stable anchors. - Do not expect internal Checklynx `customer_id` in webhook payloads. # Common Mistakes to Avoid - Omitting `screening.screening_profile_id`. It must identify an active screening profile from Dashboard > Building Blocks. - Inventing a screening profile id. Developers must create or select it in Dashboard > Building Blocks. - Sending Checklynx internal `customer_id` in transaction-screening requests. - Treating `transaction_reference_id` as idempotent. It is a client business reference; every POST creates a run. - Sending only `external_customer_id` for a party. The party still needs executable AML input: `name` or `identity_documents[]`. - Reusing `search_term` for passports or IDs. Use `search_identity` for identifiers. - Sending `source_type` inside batch item filters. It belongs at the batch request root. - Treating webhook event names as API endpoints. They are outbound event types. # Public Source Types - `pep` - `sanctions` - `wanted` # Error Handling Notes - Invalid or missing API keys can return 403 or API gateway authentication errors depending on the route. - Transaction screening can return 403 when disabled for the tenant. - Transaction create returns 400 for invalid body, unknown/inactive screening profile, unsupported party shape, or unsupported inline screening options. - Unknown `external_customer_id` does not fail transaction screening. The party is screened but is not linked to a known customer.