# 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": "3My1ffQr5qQzmq4aBFgRqwRYqfB5zPAt8t", "filters": { "source_type": [ "sanctions" ] } } ``` 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, vessel IMO number, crypto wallet, bank account, or similar identity value. - `fuzziness` (string, optional). Values: 0, 1, 2. 0 is strict, 1 is default, and 2 is broad. - `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 filter. Use one or more of `individual`, `entity`, `vessel`, or `aircraft`. Omit this field or send an empty array to consider all target types. - `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. Key rules: - Send exactly one of `search_term` or `search_identity`. - `search_term` has minimum length 3. - `source_type` values are: pep, sanctions, wanted. - Do not document removed internal sanction-source exclusion filters in public request contracts. # 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. - `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, vessel IMO number, crypto wallet, bank account, or similar identity value. - `filters` (AmlBatchItemFilters, optional). Batch item filter fields: - `group_type` (array, optional). Target type filter. Use one or more of `individual`, `entity`, `vessel`, or `aircraft`. Omit this field or send an empty array to consider all target types. - `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. To create a run, send an active `screening.screening_profile_id`, your `transaction.transaction_reference_id`, and the `transaction.parties[]` to screen. Each party needs a `role` plus at least one of `name`, `identity_documents[]`, or `payment_instruments[]`. Use your own payment, order, transfer, or transaction id for `transaction.transaction_reference_id`. It is a business reference, not an idempotency key; every POST creates a new run. Supported payment instrument types are `bank_account` and `wallet_address`. Checklynx echoes payment instruments in run responses and does not create separate instrument objects. Payment instrument checks require sanctions identity screening in the selected profile. Send `transaction.parties[].external_customer_id` 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" } ], "payment_instruments": [ { "type": "bank_account", "account_number": "123456789", "bic": "CAIXESBBXXX", "external_instrument_id": "acct_sender_001" } ] }, { "role": "creditor", "external_customer_id": "cust_receiver_001", "name": "Jane Doe" } ] } } ``` Example: bankAccountInstrument ```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", "payment_instruments": [ { "type": "bank_account", "account_number": "123456789", "bic": "CAIXESBBXXX", "external_instrument_id": "acct_sender_001" } ] } ] } } ``` Example: walletAddressInstrument ```json { "screening": { "screening_profile_id": "sp_your_active_profile_id" }, "transaction": { "transaction_reference_id": "crypto_withdrawal_12345", "type": "other", "occurred_at": "2026-05-01T10:15:30Z", "amount": { "value": "2.50", "currency": "USD" }, "parties": [ { "role": "creditor", "external_customer_id": "cust_receiver_001", "payment_instruments": [ { "type": "wallet_address", "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "network": "ethereum", "external_instrument_id": "wallet_receiver_001" } ] } ] } } ``` Create request fields: - `screening` (TransactionScreeningConfig, required). AML screening profile to use for this run. - `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. Role of this party in the transaction. - `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. - `payment_instruments` (array, optional). Structured payment instrument evidence attached to this party. Supported types are `bank_account` and `wallet_address`. - `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. Payment instrument checks require sanctions identity screening to be enabled. Payment instrument fields: - `bank_account.type` (string, required). Value: bank_account. - `bank_account.account_number` (string, required). Account evidence stored with the run. It may look like an IBAN, but Checklynx does not parse it, validate its checksum, or screen it in this release. - `bank_account.bic` (string, required). ISO 9362 BIC/SWIFT code. Checklynx screens this value for bank account instruments. - `bank_account.external_instrument_id` (string, optional). Client-side stable identifier, returned as request/run evidence only. - `wallet_address.type` (string, required). Value: wallet_address. - `wallet_address.address` (string, required). Crypto wallet address. Checklynx screens this value for wallet instruments. - `wallet_address.network` (string, optional). Blockchain network, for example ethereum. - `wallet_address.external_instrument_id` (string, optional). Client-side stable identifier, returned as request/run evidence only. 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, or merchant 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` Transaction request rules: - Each party needs `role` and at least one usable screening input: non-empty `name`, `identity_documents[]`, or `payment_instruments[]`. - Supported payment instrument types are `bank_account` and `wallet_address`. - For `bank_account`, Checklynx screens `bic` and stores `account_number` as evidence. - For `wallet_address`, Checklynx screens `address`. - Payment instrument checks use sanctions exact identity matching and require sanctions identity screening in the selected profile. - `external_instrument_id` is returned with the run, but not included in case hit records or webhook payloads. - 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. Create transaction response fields: - `id` (string, required). - `transaction` (TransactionScreeningTransactionSummary, required). Original transaction metadata, excluding `transaction.parties[]`. Echoed party evidence is returned under the top-level `parties[]` array. - `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 or null, required). Response-only. Returned when actionable hits synchronously open or link a case; null when the run is clear or all hits are suppressed. - `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 or null, required). Always present. Party name echoed from the request, or null for instrument-only parties. Checklynx does not create a name from BICs or wallet addresses. - `payment_instruments` (array, optional). Echoed payment instrument evidence from the request. Checklynx stores it with the run, not as a reusable instrument record. - `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 and return `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 data Checklynx can screen: `name`, `identity_documents[]`, or `payment_instruments[]`. - Sending payment instruments with a profile that does not enable sanctions identity screening. - 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.