Checklynx Developers

Checklynx API reference

Add your API key in the authentication panel, choose an endpoint, edit the example body, and send a request directly from the docs.

OpenAPI JSONLLM Export
POST/check/sanctions_pep

AML screening

Search sanctions, PEP, and wanted-list datasets for a target.

POST/check/sanctions_pep/batch

Batch screening

Screen multiple targets in one request and correlate by request_item_id.

POST/check/adv_media

Adverse media

Check open-source and news references for adverse media signals.

POST/transactions

Transaction screening

Screen parties involved in a payment or transaction reference.

EVENT*.case.opened

Webhooks

Receive signed case-opened events for customer and transaction screening.

Developer guide

Choose the right screening workflow

The API has four main request workflows, plus signed webhook events. Single AML and batch AML screen targets directly, adverse media checks news and open-source references, and transaction screening checks the parties in a payment, transfer, order, or other client transaction reference.

Single AML screening

POST /check/sanctions_pep screens one target against sanctions, PEP, and wanted-list data without creating a customer or case record.

  • Send exactly one of search_term or search_identity.
  • Use search_term for names, aliases, company names, vessel names, or aircraft names.
  • Use search_identity for passports, tax IDs, national IDs, document numbers, or vessel IMO numbers.
  • Use filters such as source_type, group_type, nationality, birth_year, and gender to narrow candidate results.

Batch AML screening

POST /check/sanctions_pep/batch screens many independent targets in one request.

  • Put shared controls such as source_type, fuzziness, exclude_deceased, and sanction-source filters at the request root.
  • Each check_items[] entry must send exactly one of search_term or search_identity.
  • Use request_item_id to correlate each response entry.
  • Use item-level filters only for target attributes such as group_type, nationality, birth_year, and gender.

Adverse media

POST /check/adv_media searches news and open-source references for adverse media signals.

  • Send search_term with the individual, entity, or organization name to investigate.
  • Use this endpoint when you need media context, not sanctions or PEP matching.
  • Like single AML screening, adverse media checks do not create customer or case records.

Transaction screening

POST /transactions creates one screening run for one client transaction reference.

  • Use this when the thing you are screening is a payment, order, transfer, or similar transaction with multiple parties.
  • Send parties under transaction.parties[] with roles such as debtor, creditor, customer, or counterparty. Use other only when no specific role fits.
  • Create or choose an AML screening profile in the Checklynx dashboard under Building Blocks, then send its id as screening.screening_profile_id.
  • Save the returned run id, and use transaction_reference_id only as your business reference, not as an idempotency key.

Transaction screening

Transaction screening details

Use transaction screening when you need to screen the people or entities involved in a payment, order, transfer, or other client transaction reference. Each request creates one Checklynx screening run and can optionally link hits to a compliance case.

Recommended integration flow

  1. Create each known customer in the Checklynx dashboard and set external_customer_id to the customer id from your own system.
  2. When a payment or transaction needs AML screening, choose your payment/order id and send it as transaction.transaction_reference_id.
  3. Add every party that should be screened under transaction.parties[]. Put the matching customer external_customer_id on parties you already know.
  4. Create or choose the AML screening profile in the dashboard under Building Blocks, then send its id as screening.screening_profile_id.
  5. Store the returned Checklynx run id. Use it to fetch the exact run later with GET /transactions/{id}.
  6. Use GET /transactions/references/{transaction_reference_id} when you want the aggregate view for all runs under the same client transaction reference.

Customer linking

external_customer_id is your customer id for that person or entity. Set it when creating the customer in Checklynx, then send the same value on transaction parties for that customer.

  • Use the same value you use as customer_id in your own system, for example cust_123.
  • Use the same value for the same customer every time, and do not reuse it for a different customer in the same Checklynx environment.
  • Checklynx keeps its own internal customer_id; clients should not send that internal id to this public endpoint.
  • In transaction screening, send the same value on the relevant party. If it resolves, the response returns customer_resolved: true and can include customer_type.
  • If it does not resolve, the screening still runs from the party request data, but Checklynx treats the party as an unlinked customer for that run.

Request shape

The public API uses a transaction-first body. Send transaction, screening.screening_profile_id, and at least one transaction.parties[] item.

  • Each party needs a role.
  • Each party needs a non-empty name or identity_documents[].
  • A request can include up to 100 parties.
  • Optional filters include group_type, nationality, birth_year, and gender.

Responses and lookups

A created run returns status, hit_status, hit_count, optional case_id, and per-party results.

  • id is the Checklynx-generated immutable screening run id.
  • hit_status is hit when actionable hits remain.
  • screening_summary separates total hits from actionable hits. Suppressed hits are matches hidden by existing false-positive decisions for a linked customer.
  • GET /transactions lists reference aggregates and supports hit_status, transaction_reference_id, limit, and cursor.
  • GET /transactions/references/{transaction_reference_id} returns the aggregate for one client reference.

Common mistakes

  • Using transaction_reference_id as an idempotency key. It is not one; each POST /transactions creates a new run.
  • Sending only external_customer_id without name or identity_documents[]. The party still needs executable AML input.
  • Expecting unknown external_customer_id values to fail. They do not fail; they simply do not link to a Checklynx customer.

Fields Checklynx returns

Do not send Checklynx internal customer_id in the request. Public transaction-screening responses do not expose it. Use customer_resolved and customer_type to understand whether external_customer_id linked to a known customer.

Webhooks

Webhook event contracts

Webhooks are outbound HTTP POST requests sent by Checklynx to subscribed receiver URLs. Use them to react when screening creates a case, and deduplicate deliveries with event_id.

Public event catalog

Supported public events notify receivers when screening opens a case.

  • customer_screening.case.opened is sent when a customer screening case is created in open state.
  • transaction_screening.case.opened is sent when transaction screening creates a new open case for actionable hits.

Delivered envelope

Every delivery uses the webhook envelope.

  • Use id or event_id as the stable webhook event id.
  • event_type selects the payload shape.
  • schema_version current value: 1.

Transaction payload

transaction_screening.case.opened includes the client transaction reference and optional party summaries.

  • Use data.transaction_reference_id and data.case_id as stable anchors.
  • Treat data.parties[] as optional. It is present when party-level hit records are available for the opened transaction case; otherwise it is omitted.
  • Do not expect internal Checklynx customer_id in webhook payloads.

Signing

Checklynx signs each outbound webhook request with X-Webhook-Signature.

  1. Read the raw request body before parsing JSON.
  2. Compute base64(HMAC-SHA256(signing_secret, raw_request_body)).
  3. Compare the computed value with the X-Webhook-Signature header.
  4. Reject the request if the signatures do not match.
  5. 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.