> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# ComplyAdvantage Integration for Screening Alert Syncing

> Connect ComplyAdvantage Mesh to Corsa to work customer screening alerts in Corsa, with decisions and notes synced both ways.

Connect your [ComplyAdvantage Mesh](https://complyadvantage.com/) account to Corsa to work customer screening alerts (sanctions, PEP, adverse media, warnings, and fitness and probity) in Corsa. Each ComplyAdvantage alert becomes a Corsa alert, and each ComplyAdvantage risk becomes a screening match. Analysts can decide in either system: decisions and notes sync both ways.

## Quick Start

To connect ComplyAdvantage to Corsa:

1. In ComplyAdvantage Mesh, create an API credential with the [permissions listed below](#prerequisites) and copy the **access key** and **secret**.
2. In Corsa, go to **Developers Hub → Integrations → ComplyAdvantage**.
3. On the **Connect** screen, paste the access key and secret, choose your region, and save.
4. On the **Complete Setup** screen, choose the case stage for each outcome and save.
5. Optionally, contact ComplyAdvantage support to get your **webhook signing secret**, then add it so new alerts arrive within seconds.
6. Open the **Health** section on the integration card and confirm the backfill runs.

## How It Works

1. **Secure Connection** - Corsa checks your ComplyAdvantage credential and region, then stores it encrypted.
2. **Alert Sync** - Corsa imports open alerts from the last 30 days by default, then picks up new and changed alerts on every check. With a webhook signing secret, new alerts arrive within seconds.
3. **Client Linking** - Corsa links each alert to the matching Corsa client, or creates one when nothing matches.
4. **Two-Way Decisions** - Match decisions and notes made in Corsa are written to ComplyAdvantage, and decisions and notes made in ComplyAdvantage are copied to Corsa.
5. **Case Closure** - When every alert of a ComplyAdvantage case has ended, Corsa moves the case to the stage you mapped for its outcome.

## What Gets Synced

### Case types

Corsa syncs **customer onboarding** and **customer monitoring** cases. Payment screening and transaction monitoring cases are not synced.

### Alerts and screening matches

* One ComplyAdvantage alert becomes one Corsa alert, with a link back to the alert in ComplyAdvantage.
* Each ComplyAdvantage risk becomes a screening match on that alert.
* Match notes include the matched listings, PEP details, media articles, why the customer matched and, for monitoring alerts, what changed since the last screening.
* When a risk disappears after a re-screen, Corsa keeps the match and adds a note to it.

Corsa adds these custom fields to each alert:

* **ComplyAdvantage case ID**
* **ComplyAdvantage case type** (Onboarding or Monitoring)
* **ComplyAdvantage alert type**

### Priority mapping

| ComplyAdvantage priority | Corsa alert priority |
| - | - |
| 1–3 | High |
| 4–6 | Medium |
| 7–9 | Low |
| None | The **Default alert priority** you choose in setup |

### Decisions and notes

| You do this | In | Corsa syncs it as |
| - | - | - |
| Mark a match as a true or false match | Corsa | A true or false positive decision on the risk in ComplyAdvantage, with the decision reason as a risk note |
| Add an alert note | Corsa | An alert note in ComplyAdvantage, prefixed with the author and time |
| Decide a risk as true or false positive | ComplyAdvantage | A true or false match in Corsa, with a note naming who decided |
| Add an alert or risk note | ComplyAdvantage | A note in Corsa, naming the author |
| End or reopen an alert | ComplyAdvantage | The Corsa alert is resolved or reopened |

Pending and escalated decisions in Corsa are not sent to ComplyAdvantage. Note edits and deletions are not synced in either direction.

> [!NOTE]
>
> ComplyAdvantage ends an alert by itself once all its risks are decided. If you resolve a Corsa alert while matches are still undecided, Corsa adds a note in ComplyAdvantage and the alert stays open there.

### Case closure

When every alert of a ComplyAdvantage case has ended, in either system, Corsa moves the case to the stage you mapped, with a closing note. Corsa picks the outcome in this order:

1. **SAR** - the alert's Corsa case was closed as a SAR.
2. **Any true match** - at least one match was decided as a true match.
3. **All cleared** - otherwise.

If a write to ComplyAdvantage fails, Corsa retries it for up to 24 hours, then adds a note on the Corsa alert.

## Client Linking

Corsa links each ComplyAdvantage customer to a Corsa client. The first rule that applies wins:

1. **Remembered link** - a link set or confirmed earlier for the same ComplyAdvantage customer.
2. **Reference ID** - the ComplyAdvantage `external_identifier` equals the Corsa client `referenceId`.
3. **Exact name** - exactly one Corsa client has the same name. The alert shows **Linked by name, confirm client**.
4. **New client** - when nothing matches, Corsa creates an individual client for a person or a corporate client for a company, tagged `complyadvantage-imported`.
5. **Manual link** - otherwise the alert has no client and shows **Manual client link required**.

Corsa doesn't create a client when several clients match, when an analyst rejected the match, for vessels, or for customers without an `external_identifier`. Corsa never changes an existing client.

For the best matching, set the ComplyAdvantage `external_identifier` to the stable customer ID you use as the Corsa client `referenceId`.

### Fixing a client link

On a ComplyAdvantage alert, the client card shows:

* **Link client** or **Change client** - search for and select the client the alert is about.
* **Confirm** and **Reject** - shown while the alert is **Linked by name, confirm client**. Reject removes the link, and Corsa doesn't suggest that client for this customer again.

Corsa remembers your choice, so later alerts for the same customer link automatically. You need the **alerts:edit** permission to change a client link.

## Prerequisites

* A ComplyAdvantage **Mesh** account. Legacy ComplyAdvantage API keys are not supported.
* A ComplyAdvantage Mesh API credential that can:
  * view cases and alerts;
  * decide risks, add notes, and transition cases;
  * view case workflows (Supervisor or Admin role in ComplyAdvantage);
  * view, create, and update webhooks.
* At least one decision stage in both your onboarding and monitoring workflows in ComplyAdvantage.
* Optional, for webhooks: your ComplyAdvantage **webhook signing secret**. You can't create it yourself; contact ComplyAdvantage support to get it.
* Owner access to the Corsa application.

## Setting Up the ComplyAdvantage Integration

### Step 1: Connect

1. Log in to Corsa.
2. Go to **Developers Hub → Integrations**.
3. Click **Configure** on the ComplyAdvantage card.
4. Fill in the **Connect** screen:

| Field | Description | Default |
| - | - | - |
| **Access key** | The access key of your ComplyAdvantage Mesh API credential. | — |
| **Secret** | The secret of the same credential. | — |
| **Region** | **United States** or **Europe**: the region of your ComplyAdvantage account. | Your Corsa region |
| **Check interval** | How often Corsa checks ComplyAdvantage for new and changed alerts: 5, 10, 15, or 30 minutes, or 1 hour. | 5 minutes |
| **Import alerts from** | How far back the first import reaches: the last 7, 14, 30, 60, or 90 days. Ongoing checks are independent of this. | 30 days |
| **Default alert priority** | Used when a ComplyAdvantage alert has no priority. | Medium |

5. Save. Corsa checks the credential and the region, and loads your case workflows. The integration shows **Pending Setup**.

> [!WARNING]
>
> The region can't be changed after setup. To change it, remove the integration and set it up again.

### Step 2: Complete setup

On the **Complete Setup** screen, choose the ComplyAdvantage case stage Corsa moves a case to for each outcome. There are two groups, **Onboarding cases** and **Monitoring cases**, each with three outcomes:

* **All cleared**
* **Any true match**
* **SAR**

Only decision stages are listed. Save to activate the integration. Corsa then starts importing your open alerts.

> [!NOTE]
>
> If you change your workflows in ComplyAdvantage, open the integration and save again to refresh the stage lists.

### Step 3: Turn on webhooks (optional)

> [!NOTE]
>
> The webhook signing secret isn't available in the ComplyAdvantage app. Contact ComplyAdvantage support and ask for the webhook signing secret of your account.

Once you have it, enter it in **Webhook signing secret (optional)** on the **Complete Setup** screen. Corsa then registers its webhooks in ComplyAdvantage for you, and new alerts arrive within seconds. There is nothing to configure in ComplyAdvantage.

Without a signing secret, Corsa checks ComplyAdvantage on the check interval only.

### Step 4: Check the integration

Open the **Health** section on the ComplyAdvantage integration card. It shows:

* **Connection** and the last successful check.
* **Webhooks**: active, or polling only.
* **Backfill**: the progress of the first import.
* Updates to ComplyAdvantage that are waiting, on hold, or failed in the last 24 hours.
* The last error, if any.

Then open an imported alert in Corsa and confirm that it shows its screening matches and a linked client.

## Removing the Integration

When you remove the integration, Corsa turns off its webhooks in ComplyAdvantage, stops any running import, and cancels pending updates to ComplyAdvantage. Alerts already imported stay in Corsa. If you connect the same account again, Corsa doesn't duplicate alerts or clients.

## Troubleshooting

| Issue | Resolution |
| - | - |
| "Legacy ComplyAdvantage API keys are not supported" | Create a ComplyAdvantage **Mesh** API credential and use its access key and secret. |
| "ComplyAdvantage rejected the access key or secret" | Check both values. Paste the access key exactly as ComplyAdvantage issued it. |
| "ComplyAdvantage has locked this access key" | Unlock the key from the notification ComplyAdvantage sent to the account owner, then try again. |
| "These credentials don't belong to a ComplyAdvantage US/EU account" | Choose the region of your ComplyAdvantage account, or check the credentials. |
| "ComplyAdvantage denied access to the case workflows" | Give the credential the **View case workflows** permission (Supervisor or Admin role). |
| "The workflow has no decision stages" | Add decision stages to that workflow in ComplyAdvantage, then save again. |
| A mapped stage no longer exists | Choose another stage on the **Complete Setup** screen and save. |
| Webhooks show "polling only" | Check that the credential can view, create, and update webhooks, and that the signing secret is entered. If you don't have the signing secret, contact ComplyAdvantage support to get it. Alerts still arrive on the check interval. |
| Health shows "ComplyAdvantage is limiting requests" | No action needed. Corsa slows down and retries on its own. |
| An alert shows **Manual client link required** | Use **Link client** to choose the client. Corsa remembers the link for later alerts. |

***

Corsa offers native integrations with leading compliance, blockchain analytics, and custody providers. [See all integrations](https://docs.corsa.finance/integrations.md) or [schedule a demo](https://calendly.com/michellelatzer/welcome-to-corsa) to see how Corsa fits into your stack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.