> ## 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.

# Integration Skill

> AI skill that guides developers through Corsa API integration — SDK setup, authentication, data ingestion, webhooks, and error handling.

## Overview

The **corsa-integration** skill adds Corsa API knowledge to your coding tool (Cursor, Claude Code, VS Code, etc.) so it can help you integrate with the Corsa compliance platform. It covers the full integration lifecycle from SDK installation to webhook handling.

### What It Helps With

* Setting up and configuring the `@corsa-labs/sdk`
* Authentication with the correct `Bearer <TOKEN>:<SECRET>` format
* Ingesting clients, members, accounts, wallets, sessions, and operations in the right order
* Configuring webhook receivers with proper signature verification
* Handling API errors, rate limits, and edge cases

***

## Quick Start

After installing the skill, ask your coding tool questions like:

* *"Set up the Corsa SDK in my project"*
* *"Ingest an individual client with upsert"*
* *"Create a deposit operation linked to a client"*
* *"Set up a webhook handler for alert events"*
* *"Handle Corsa API rate limiting"*

Your coding tool will generate code using the correct SDK patterns, authentication format, and entity relationships.

***

## What the Skill Knows

### SDK Setup & Authentication

* `CorsaClient` initialization (not the deprecated `ComplianceClient`)
* Bearer token format: `Bearer <API_TOKEN>:<API_SECRET>`
* Base URLs for US (`api.corsa.finance`) and EU (`api.eu.corsa.finance`)
* Rate limiting (500 req/60s) and `Retry-After` handling

### Data Model & Ingestion Order

The skill understands the Corsa entity graph and enforces the correct ingestion order:

1. **Clients** (Individual / Corporate)
2. **Members** (UBOs, Directors — corporate only)
3. **Accounts & Wallets** (Bank accounts, Blockchain wallets, Payment accounts)
4. **Sessions** (Device/IP data)
5. **Operations** (Deposits, Withdrawals, Trades → Transactions)
6. **Alerts & Cases** (linked to Clients and Transactions)
7. **Verifications** (KYC/KYB results from identity providers)

### `referenceId` and Upsert

The skill knows that `referenceId` is your internal system ID for an entity, and that you can use either `referenceId` or the Corsa-generated `id` interchangeably in subsequent API calls. It guides correct `upsert=true` usage.

### All 22 SDK Services

Full awareness of every service on `CorsaClient`: `clients`, `members`, `deposits`, `withdrawals`, `transfers`, `trades`, `transactions`, `alerts`, `cases`, `bankAccounts`, `blockchainWallets`, `paymentAccounts`, `sessions`, `rules`, `ruleTemplates`, `evaluation`, `checklists`, `attachments`, `subDispositions`, `externalRules`, `verifications`, and `platform`.

### Webhooks

Express handler setup with `express.raw()`, signature verification via `verifyWebhookSignature`, and all 32 event types.

### Error Handling

`ApiError` structured errors with `status`, `body`, and `requestId` for debugging.

***

## Common Mistakes It Prevents

| Mistake                                          | What the skill does                                    |
| ------------------------------------------------ | ------------------------------------------------------ |
| Using `Bearer <TOKEN>` without the secret        | Generates the correct `Bearer <TOKEN>:<SECRET>` format |
| Parsing webhook body as JSON before verification | Uses `express.raw()` and verifies the raw buffer       |
| Creating operations before clients               | Follows the data model dependency order                |
| Using deprecated `ComplianceClient`              | Always uses `CorsaClient`                              |
| Omitting `referenceId`                           | Includes it and explains upsert behavior               |
| Ignoring rate limits                             | Adds `Retry-After` handling to error logic             |

***

## Source

<Card title="GitHub Repository" icon="github" href="https://github.com/corsa-labs/corsa-skills/tree/main/corsa-integration">
  View the full skill source, including the detailed API reference with all method signatures and code templates.
</Card>