Welcome to the FAQ for migrating from the classic Customer Screening & Ongoing Monitoring (CSOM) API to the new Mesh platform. This document is a practical reference for developers and implementation partners, covering the most critical structural shifts, endpoint mappings, common pitfalls, and new concepts introduced in Mesh.

It is designed to be read alongside the full API Migration Guide. Where a question relates to a specific article in that guide, a pointer is included.

A. General & Structural Changes

1. What are the primary differences between CSOM and Mesh?

Mesh introduces a structured, multi-entity approach in place of CSOM's single-search model. The five most important conceptual shifts are:

•       Customer vs. Case: a Customer is a persistent, long-lived entity; Cases (onboarding or monitoring) are evaluations attached to that Customer.

•       Case vs. Alert: Cases now contain Alerts, and Alerts contain Risks (profile matches). Remediation happens at the alert/risk level.

•       Dynamic workflows: case stages are fully customizable instead of being a fixed enum of match statuses.

•       Synchronous and asynchronous processing: you choose per call which fits your latency and volume needs.

•       Deferred results: the initial create-and-screen call returns identifiers, not full match details. Match details are fetched in a follow-up call (often triggered by a webhook).

See the “Conceptual Differences” section of the Migration Guide.

2. Who is this guide and FAQ intended for?

Primarily developers and implementation partners moving an existing CSOM API integration to Mesh. Compliance and operations stakeholders will also find the sections on case management, monitoring, and audit useful.

3. What is the new ownership/access hierarchy in Mesh?

Mesh uses three levels of ownership:

• Client: the parent organization (e.g., X Company Ltd).

• Account: a sub-environment within the client (e.g., Sandbox, Production, or a regional account like X Company Ltd – India). Data between accounts is fully segregated.

• User: an individual person with access to the platform (e.g., [email protected]).

4. Do I need separate API users for different environments?

Yes. API authentication is keyed to whichever account a user last accessed, so it is strongly recommended to create separate API users per sub-environment, for example [email protected] for Sandbox and a different user for Production. Requesting a new token effectively “refreshes” the user state.

5. What are the different API integration models available in Mesh?

Two models are common:

• Standard / Mesh Case Management: clients use Mesh's UI for remediation and use API + webhooks only for submission and synchronization. Faster to implement and benefits from new UI features automatically.

• Custom External Case Management: clients build remediation and case-management screens into their own product, and analysts never need to open the Mesh UI. More development work, but unlocks custom workflows.

Within the Migration Guide, sections specific to External Case Management are flagged with a green symbol you can skip if you'll be using the Mesh UI.

6. Is there an API “emulation” / “translator” layer so I don't have to re-integrate?

Currently emulated endpoints include POST /searches, GET /searches and /searches/{id}/details, GET /searches/{id}/monitors, PATCH /searches/{id}, PATCH /searches/{id}/entities, PATCH /searches/{id}/monitors, and the three classic webhooks.

Known limitations to be aware of when scoping emulation:

• Latency at 50 TPS measured around p50 ≈ 1.4s, p99 ≈ 5.4s. Not suitable for real-time UX requirements.

• The risk_level field is not supported (returned as unknown).

• The share_url public-link field is not supported.

• The numeric search_id / mysql_id is not supported — retrieval is by search_ref only.

• If a client reuses a client_ref, the second and subsequent searches will have search_ref appended to keep it unique in Mesh.

• Invalid country codes (e.g., EU, XX, UK, OA, or any non-alpha-2 string) cause the request to fail. CSOM did not validate these.

• PATCH /searches/{id} only updates the latest case, not all cases sharing a client_ref.

• Webhooks can fire multiple times for the same event in Mesh — your webhook handlers should be idempotent.

B. Authentication

7. How has API authentication changed in Mesh?

This is one of the biggest changes. CSOM used a permanent, static API key passed in the Authorization header. Mesh uses OAuth2 with short-lived bearer tokens. Even if a token is leaked, its short lifespan limits exposure.

See Article 1 of the Migration Guide.

8. How do I authenticate API calls now?

Two-step process:

1. POST your credentials (username, password, realm) to the token endpoint to receive an access_token valid for 24 hours.

2. Include the token in every subsequent call using the standard Authorization: Bearer {access_token} header.

Your application must refresh the token before it expires to ensure uninterrupted service.

9. What permissions do I need for admin or migration endpoints?

Most day-to-day endpoints work with standard account permissions. Admin endpoints (account management, migration tooling) require a “super” account with admin write permissions. If you receive a 403 with “Missing required permissions”, your user is not in the right account — contact ComplyAdvantage support to request access or switch account using PUT /v2/accounts/me.

C. Identifiers & Data Structure

10. What replaces the CSOM search_id and search_ref?

Both have been replaced by a hierarchy of identifiers. The most important is the customer_identifier — a system-generated UUID that represents the long-lived customer record. Below that, each Case has a case_identifier, each Alert has an alert_identifier, and each individual profile match has a risk_identifier. You'll use these to make subsequent calls about that customer, case, alert, or risk.

See Article 3 of the Migration Guide for the full identifier hierarchy.

11. Where is the client_ref in Mesh?

It has been replaced by external_identifier, which is the client-provided identifier that uniquely links a Mesh customer to your internal records.

12. I used to reuse client_ref to group related customers. How do I do that in Mesh?

Because external_identifier must be unique per customer, grouping has to move somewhere else. Common options:

•       Use Labels to tag related customers with a shared key. Best for low-cardinality groupings.

•       Use a custom field on the customer schema. Best for high-cardinality identifiers such as a CRM account number that may be shared across many customers.

•       Use the acquisition_source field if it fits your model. Note that a customer can only have one acquisition source.

If your migration source data already contains duplicates with the same client_ref, the migration tooling will keep the first occurrence as-is and append the CSOM search_ref to all subsequent ones to enforce uniqueness. You can still find all related customers in the UI by searching for the original client_ref string.

13. How do I retrieve the customer_identifier if I only have the external_identifier?

Use GET /v2/customers/external/{external_identifier}. This redirects to the standard customer-details response, so you also get the internal customer_identifier you'll need for downstream calls.

14. What's the difference between a Customer, Case, Alert and Risk?

Think of it as a four-level hierarchy:

•       Customer: the long-lived person, company, or undefined entity record in Mesh.

•       Case: a specific evaluation event for that customer (an onboarding case, a monitoring case).

•       Alert: a flagged risk dimension within a case (e.g., customer screening, payment screening). One case can contain multiple alerts.

•       Risk: an individual profile match inside an alert. This is where remediation happens (true positive, false positive, etc.).

15. How do I retrieve match details in the new system?

Match details are deferred. The initial create-and-screen response gives you identifiers, not the full match payload. To get the actual profile matches you make a second call using the alert_identifier — typically GET /v2/alerts/{alert_identifier}/risks. For synchronous workflows, you can ask the API to wait for alerts to be generated before responding by setting last_sync_step="ALERTING".

D. Workflows, Onboarding & Case Management

16. What is the difference between case states and case stages in Mesh?

In CSOM, match statuses were a fixed enum (Unknown, No Match, Potential Match, False Positive, True Positive, etc.) and could not be customized.

In Mesh both case.state and case.stage appear in API responses, but state is deprecated. Use stage instead — it is fully configurable and supports your own review and decision stages.

17. How do customizable workflows work?

Each case type (Customer Onboarding, Customer Monitoring, Transaction Monitoring) has one workflow. Each workflow has stages of two types:

•       Review stages — active investigation (e.g., “Level 1 Triage”, “Escalated to MLRO”). Minimum 1, maximum 8 per workflow.

•       Decision stages — terminal outcomes (e.g., “Approved”, “Rejected”). Minimum 2 (one positive, one negative); maximum 8 in total.

Each stage has its own UUID. Your API integration transitions a case from stage to stage by referencing those identifiers.

18. What happens to existing cases if we change our workflow?

Modifying a workflow creates a new version. Older cases stay on the version they were created under, preserving audit history. New cases are routed through the new version.

19.  How do synchronous and asynchronous onboarding differ?

Both use the same payload — only the endpoint and response shape differ:

• Synchronous: the request blocks until processing reaches the step you specified, then returns the workflow's status and identifiers. Best for real-time UI flows.
  

• Asynchronous: the API immediately returns a workflow_instance_identifier and continues processing in the background. Best for batch processing and webhook-driven architectures.

20. When should I use last_sync_step=SCREENING vs ALERTING?

In a synchronous call:

• Use SCREENING (default) when you only need a fast hit/no-hit signal. Typical latency around 750 ms. Alerts continue generating in the background and can be retrieved later via webhook or polling.

• Use ALERTING when you need alert identifiers in the response so you can immediately fetch full risk details. Latency is higher because the API waits for the alerting step to finish.

21. How are case management actions handled?

CSOM used one generic PATCH /searches/{id} endpoint for many actions. Mesh splits these into dedicated, action-oriented endpoints. The most common are:

• Assign analyst: POST /v2/cases/{case_identifier}/assign

• Transition case stage: POST /v2/cases/{case_identifier}/transition

• Bulk transition: POST /v2/cases/transitions/bulk

• Set decision on a risk profile: POST /v2/alerts/{alert_identifier}/risks/{risk_identifier}/decision

•  Manually override risk score: PATCH /v2/customers/{customer_identifier}/scores

• Add a note to a case: POST /v2/cases/{case_identifier}/notes

•  Add a note to a risk: POST /v2/entity-screening/risks/{risk_identifier}/notes

22. Can I leave a note on a customer (not just a case)?

Not currently. Notes in Mesh are scoped to cases and to individual risks. When CSOM searches with search-level comments are migrated, those comments are attached to the resulting case(s).

23. Can I still delete a search like in CSOM?

Yes, but with caveats. Deletion in Mesh is at the customer level (DELETE /v2/customers/{customer_identifier}) and is currently:

• Available on request for CSOM-only clients — ask your CSM or support.

• A soft delete: the record disappears from the UI and API but a copy is retained in the backend database.

• Limited to single-record deletion today. Bulk deletion is on the product roadmap (target block 5 or 6).

If a wrong decision was made on a case, you cannot edit or delete the audit entry. Audit logs are intentionally immutable. The right workflow is to reopen the case, apply the correct decision, and leave an explanatory note.

24. How long is case and alert data retained?

Indefinitely on Mesh CSOM. Soft-deleting a customer hides their cases and alerts. There is no automatic expiry.

E. Monitoring

25. At what level is monitoring managed in Mesh?

In CSOM, monitoring was attached to each individual search. In Mesh, monitoring is attached to the persistent Customer. You enable or disable monitoring once per customer, against a chosen screening configuration.

26. If I monitor the same customer with different screening configs, what happens?

Each customer has one monitoring configuration at a time. If you change it, future monitor runs use the new config; historical cases remain on the configuration they were created under.

27. What is alert grouping and should I enable it?

Alert grouping controls whether new alerts on a monitored customer create a new case each time, or attach to an existing open case:

•       Enabled: subsequent alerts group inside the open case. Recommended in most situations, and strongly recommended for transaction monitoring.

•       Disabled: every new alert creates a brand-new case.

This affects which webhook fires. With alert grouping enabled, new alerts on existing cases trigger CASE_ALERT_LIST_UPDATED, not CASE_CREATED.

28. What replaces whitelisting in Mesh?

Whitelisting is now called “alert muting.” Muting an alert prevents new monitoring activity on that profile from creating fresh alerts for that customer.

F. Response Payload & Field Changes

29. I read aml_types from CSOM responses today — will my code still work?

30. Where did the risk_level field go in responses?

In CSOM, risk_level appeared on the case response. In Mesh it has moved to the customer level and is calculated dynamically by your configurable risk model. You can fetch it via GET /v2/customers/{customer_identifier}/scores or override it manually using PATCH on that endpoint. Once overridden, the score is marked MANUAL and the system will no longer recalculate it automatically until you remove the override.

31. What about share_url / public links?

Mesh has no direct equivalent to the CSOM share_url. Workarounds depending on the use case:

• Generate a Screening Certificate via POST /v2/customers/{customer_identifier}/reports and store the resulting PDF link.

• Build your own URL structure, e.g. https://<region>.mesh.complyadvantage.com/customers/{customer_identifier} or .../cases/{case_identifier}. This requires the user to have Mesh access.

• Save the rendered HTML of the customer or case page to your internal store — no Mesh user access required for later viewing.

32. What about country fields? My CSOM array of country_codes does not map 1:1.

CSOM had a single generic country_codes array that Matcher used to filter results. Mesh splits this into specific schema fields:

• For Person: country_of_birth, nationality, residential_information, and address.country.

• For Company: address.country.

• For Undefined entities (Vessel, Aircraft, or “All” in CSOM): a generic countries field that accepts a list, like CSOM.

During migration, because CSOM does not record which country field a code belonged to, all CSOM countries are mapped into address objects in Mesh (one address per country). If you later use the customer-update endpoint, you can re-distribute them across the more specific Mesh fields.

33. Are there other validation rules in Mesh that were lenient in CSOM?

Yes. Mesh applies stricter validation on several fields. The most common surprises are:

• Phone numbers: validated using Google's libphonenumber. Numbers that pass loose syntactic checks in CSOM (e.g., +44 followed by all 9s) may be rejected by Mesh.

• Email addresses: standard format validation.

• Country codes: must be valid ISO 3166-1 alpha-2 (see Q32).

Run your migration test set through Mesh before go-live and decide whether you need to scrub or strip non-essential fields.

34. How do CSOM tags map to Mesh?

Mesh has no key/value tags concept. CSOM tags are converted to Mesh Labels by concatenating key and value with “ - ”, so Retail Customer: Crypto becomes a label Retail Customer - Crypto.

This works well for low-cardinality groupings. For high-cardinality data, like CRM IDs, map them to a customer-schema field or a custom field instead of a label.

G. Common Endpoint Mappings

35. What is the Mesh equivalent of POST /searches?

Use POST /v2/workflows/sync/create-and-screen for synchronous creation, or POST /v2/workflows/create-and-screen for asynchronous creation.

Importantly, these endpoints don't create searches — they create Customers. Cases (onboarding or monitoring) are attached to the customer when there are hits.

36. What replaces GET /searches?

Depending on what you actually want:

• Listing customers → GET /v2/customers.

• Listing cases (across customers) → GET /v2/cases.

• Listing cases for a specific customer → GET /v2/customers/{customer_identifier}/cases.

37. What replaces GET /searches/{id}/details?

Two endpoints, depending on the level you want: GET /v2/customers/{customer_identifier} for the persistent customer record, or GET /v2/cases/{case_identifier} for a specific case.

38. What replaces GET /searches/{id}/certificate?

POST /v2/customers/{customer_identifier}/reports with report_type=SCREENING_REPORT. Reports in Mesh are generated at the customer level and cover the full screening history.

39. What replaces PATCH /searches/{id} and PATCH /searches/{id}/entities?

In Mesh these split into action-specific endpoints. See Q21 for the full list.

40. How do I rescreen an existing customer?

POST /v2/customers/{customer_identifier}/workflows/sync/rescreen. By default it runs a DELTA screen — alerting only on new or changed risk factors. You can also pass an X-ComplyAdvantage-Idempotency-Key header to safely retry a failed rescreen without double-running.

41. How do I export data from Mesh?

Mesh exposes a dedicated exports API:

• POST /v2/exports to request an export.

• GET /v2/exports/{export_identifier}/download to fetch the download URL.

• GET /v2/exports to list your previous exports.

Supported export types include CUSTOMER_SCREENING, CUSTOMER, SCREENING_AND_MONITORING_CASES, PROFILES, and PAYMENT_SCREENING_CASES or TRANSACTION_MONITORING_CASES_AND_ALERTS depending on enabled modules.

42. Will my migrated historical data appear in Mesh exports?

For pre-migration history, ComplyAdvantage shares an all-time CSOM Search, Entity, and Audit report at migration time. Store it as your retained pre-migration record.

H. Webhooks

43. How do classic CSOM webhooks map to Mesh?

44. Are there new webhook types in Mesh that didn't exist in CSOM?

45. Are Mesh webhook payloads different from CSOM?

Yes. Payloads are more structured and contain richer context, reducing the need for immediate follow-up API calls. They include identifiers at each level (customer, case, alert) and subject metadata where applicable.

46. Will the same event trigger a webhook more than once?

It can. Unlike CSOM, in Mesh a webhook may fire multiple times for the same underlying change. Build idempotent handlers — deduplicate on case_identifier + alert_identifier + event-type + timestamp, or use an idempotency table keyed on the payload.

47. How do I register a webhook in Mesh?

Two options:

• Via the Mesh UI (one of the most common approaches, simplest for small numbers of endpoints).

• Via the API — POST to the webhooks endpoint. Use /v2/webhooks rather than the deprecated v1 path.

I. Migration Logistics

48. Should I complete the API integration first or wait for the data migration?

Either is technically possible. Two common patterns:

• Integrate first, migrate later: start sending net-new customers to Mesh via API immediately, complete the data migration later. Works, but your ops team must work across both systems until the migration is done.

• Big-bang: align the API switchover and the data migration in a single window. Cleaner but requires tighter coordination.

Whichever path you take, agree a firm date for the full migration up front. Without one, parallel running tends to drag on indefinitely.

49. Can I run CSOM and Mesh in parallel during a validation window?

If a client wants parallel running purely to validate data quality, ComplyAdvantage can usually confirm the underlying screening algorithm is the same. That sometimes removes the need to run side-by-side.

50. How does the migration tool handle CSOM client_refs that aren't unique?

The migration tooling enforces Mesh's uniqueness requirement deterministically:

• The first customer encountered with a given client_ref is migrated using that value as the external_identifier.

• Every subsequent customer with the same client_ref is migrated with client_ref-search_ref appended to make it unique.

• If a CSOM search has no client_ref, its search_ref is used as the external_identifier.

All four resulting customers can still be retrieved by searching for the original client_ref string — a partial-match search returns the original record plus the appended duplicates.

51. What does the migration tooling do with Search Profiles?

Each CSOM Search/Risk Profile becomes one or more Mesh Screening Configurations — one per unique combination of (Risk Profile, fuzziness, limit, options). A single CSOM profile used at three different fuzziness levels therefore becomes three Mesh Screening Configurations after migration.

Migrated configs are named after the original Risk Model, with a description containing the source ID, fuzziness, and limit so you can identify them later.

You can also request a test-environment migration of just your Search Profiles before the full migration by providing one CSOM search_ref per profile.

52. What happens to my monitored searches during migration?

Each CSOM monitor run that returned profile hits becomes an Alert inside a Case in Mesh. So a single CSOM monitored search can become several Mesh cases:

•       An onboarding case for the initial search.

•       A monitoring case for each monitor run with hits.

Removed profiles in CSOM do not create new Mesh cases — they're just absent from later cases.

53. How are CSOM match statuses mapped to Mesh stages by default?

The default mapping is shown below. You can override this per migration by telling your CSM how you want your statuses mapped before the migration ticket is raised.

Profile-level mapping (CSOM → Mesh): Unknown → Not Reviewed, No Match → False Positive, Potential Match → Not Reviewed, False Positive → False Positive, True Positive → True Positive.

54. How are CSOM entity types mapped to Mesh?

Dedicated Vessel and Aircraft entity types are on the Mesh roadmap, but today they map to the generic Undefined customer type.

55. What about CSOM audit logs?

Audit logs are not migrated into Mesh because the Mesh UI doesn't show audit logs the same way. Instead, ComplyAdvantage provides a CSV export of your CSOM audit logs at migration time. Any audit logs from screens performed in Mesh post-migration are then captured by Mesh's own audit log.

56. Can I rate-limit increase be requested for the migration window?

Yes. Clients regularly request a temporary increase for migration or bulk-loading work. Contact ComplyAdvantage technical support before you start, specifying:

•       Scope — which endpoints (all, or a specific high-traffic one).

•       Throughput tier required.

•       Duration if temporary.

Mesh's default rate limit is 300 RPM (advisory). CSOM's default is 600 RPM. If your integration exceeds whatever limit is in place, you'll receive HTTP 429.

57. What about NextGen Data / CSOM v3 — should we wait?

The current recommendation is to move from CSOM Classic (v1) to Mesh v2 first, and then move from v2 to v3 when that pathway opens (currently targeted for a later product block). Moving v1 → v3 directly is technically possible but means treating the customer base as if it's coming from a different vendor — you'd need to bulk-remediate or re-remediate alerts.

Most API-side changes from v2 to v3 are minor (the most important one is aml_types being replaced by risk_type_taxonomies — see Q29). UI changes are also minor.

J. Errors, Reliability & Operational Topics

58. What are the most common HTTP error codes I should plan for?

59. Does Mesh support idempotency keys?

Yes, on selected endpoints. The rescreen endpoint, for example, accepts X-ComplyAdvantage-Idempotency-Key. Use a fresh key per logical operation and reuse the exact same key when retrying a failed call. Check the public API docs per endpoint for support status before relying on it.

60. Where do I find up-to-date API documentation?

Public Mesh API docs live at https://docs.mesh.complyadvantage.com. For a recap of structural changes between CSOM Classic, Mesh, and Mesh+NGD see the internal “API Changes” Confluence page. Raise gaps in the docs through your CSM or support contact.

61. I get “missing required permissions” on migration or admin endpoints — why?

Migration and admin endpoints require admin write permissions in the super account. Run GET /v2/accounts/me to confirm your current account, then switch with PUT /v2/accounts/me and re-fetch your token.

62. A migration job is stuck in CREATED or PROCESSING — what now?

These are operational scenarios handled by the ComplyAdvantage migration team. Common causes:

• Stuck in CREATED: the migration tooling has not yet started the job, often because blacklists (custom lists) are still being created upstream.

• Stuck in PROGRESSING with idempotency errors: an internal worker pod restart left an instruction marked as in-progress. Requires manual remediation by the migration team.

If you see a migration stalled for more than your agreed SLA, raise it with your CSM — they have the runbook to investigate and retry.

Quick Glossary