Ingest KYC/KYB Client Data - Corsa Documentation

This guide walks you through ingesting client data into Corsa. Clients are the foundation of your compliance data - all transactions, alerts, and cases are linked back to them. Full API endpoint details are available in the API Reference (requires API credentials).

All SDK examples on this page assume you have initialized the Corsa client as shown in the Node.js SDK Configuration or Python SDK Configuration guide.

Overview

Corsa supports two types of clients:

Individuals - Natural persons (retail customers).
Corporates - Legal entities (businesses, organizations).

Both types support upsert behavior: if a client with the same referenceId already exists, it will be updated instead of duplicated.

Step 1: Prepare Your Client Data

Before calling the API, gather the required data for each client type.

Individual Clients

Category	Fields
Personal Information	Name, Date of Birth, Gender, Citizenship
Documents	Passport, Driver’s License, etc. (managed via identity verification integrations)
Address	Residential address
Contact Details	Email, Phone Number

Corporate Clients

Category	Fields
Entity Details	Legal Name, Registration Number, Date of Incorporation
Business Info	Industry, Business Type, Description
Structure	Ownership type, Complexity
Members	Associated Members (Individual or Corporate) who act as UBOs, Directors, or Signatories

Step 2: Ingest Individual Clients

Endpoint: POST /v1/clients/individuals Use the upsert=true query parameter to update an existing client if they already exist (matched by referenceId).

POST /v1/clients/individuals?upsert=true
Content-Type: application/json

{
  "referenceId": "USER-12345",
  "accountStatus": "APPROVED",
  "activityStatus": "ACTIVE",
  "general": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1985-06-15",
    "citizenship": "USA",
    "personalId": "123-45-6789",
    "gender": "MALE"
  },
  "address": {
    "addressLine1": "123 Main St",
    "city": "New York",
    "country": "USA",
    "postalCode": "10001"
  },
  "contact": {
    "emailAddress": "john.doe@example.com",
    "phoneNumber": "+1-555-0199"
  },
  "tags": ["retail", "high-volume"]
}

The response will include the Corsa-generated client id - save this for linking transactions and alerts later.

Step 3: Ingest Corporate Clients

Endpoint: POST /v1/clients/corporates Use this endpoint to onboard business entities.

POST /v1/clients/corporates?upsert=true
Content-Type: application/json

{
  "referenceId": "CORP-98765",
  "accountStatus": "APPROVED",
  "activityStatus": "ACTIVE",
  "general": {
    "legalEntityName": "Acme Innovations LLC",
    "dateOfIncorporation": "2018-04-12",
    "countryOfIncorporation": "USA"
  },
  "business": {
    "industry": "Technology",
    "description": "SaaS provider for financial services",
    "businessType": "FINANCIAL_INSTITUTIONS",
    "incorporationType": "LIMITED_LIABILITY_COMPANY"
  },
  "address": {
    "registrationAddress": {
      "addressLine1": "456 Tech Park Blvd",
      "city": "Austin",
      "country": "USA",
      "postalCode": "73301"
    }
  },
  "tags": ["enterprise", "saas"]
}

Step 4: Retrieve a Client

Use the GET endpoints to fetch client data by their Corsa-generated ID.

Get an Individual Client

Endpoint: GET /v1/clients/individuals/{clientId}

GET /v1/clients/individuals/client-uuid-123

Get a Corporate Client

Endpoint: GET /v1/clients/corporates/{clientId}

GET /v1/clients/corporates/client-uuid-456

Step 5: Update a Client

Use the PUT endpoints to update existing client data. All fields are optional on update - only include the fields you want to change.

Update an Individual Client

Endpoint: PUT /v1/clients/individuals/{clientId}

PUT /v1/clients/individuals/client-uuid-123
Content-Type: application/json

{
  "general": {
    "firstName": "John",
    "lastName": "Doe-Smith"
  },
  "contact": {
    "emailAddress": "john.doesmith@example.com"
  },
  "accountStatus": "APPROVED",
  "activityStatus": "ACTIVE"
}

Update a Corporate Client

Endpoint: PUT /v1/clients/corporates/{clientId}

PUT /v1/clients/corporates/client-uuid-456
Content-Type: application/json

{
  "activityStatus": "ACTIVE",
  "accountStatus": "APPROVED",
  "business": {
    "industry": "Financial Services",
    "description": "Updated business description"
  }
}

Step 6: Bulk Update Clients

Apply the same field changes to up to 100 clients in a single request. Use this when you need to update risk assessments, statuses, or screening results across a group of clients at once.

Bulk Update Individual Clients

Endpoint: PATCH /v1/clients/individuals/bulk/update

PATCH /v1/clients/individuals/bulk/update
Content-Type: application/json

{
  "clientIds": ["client-uuid-001", "client-uuid-002", "client-uuid-003"],
  "update": {
    "accountStatus": "FROZEN",
    "currentRisk": {
      "score": 90,
      "level": "HIGH",
      "reason": "Periodic review triggered elevated risk score"
    }
  }
}

Bulk Update Corporate Clients

Endpoint: PATCH /v1/clients/corporates/bulk/update

PATCH /v1/clients/corporates/bulk/update
Content-Type: application/json

{
  "clientIds": ["corp-uuid-001", "corp-uuid-002"],
  "update": {
    "sanctionsStatus": "FLAGGED",
    "tagsToAdd": ["under-review"],
    "tagsToRemove": ["clear"]
  }
}

Bulk Update Request Fields

Field	Required	Description
`clientIds`	Yes	Array of client IDs or `referenceId`s to update (maximum 100).
`update`	Yes	Fields to apply to every client in the list.
`update.accountStatus`	No	`APPROVED`, `WAITING_FOR_REVIEW`, `IN_REVIEW`, `REJECTED`, `OFF_BOARDED`, `FROZEN`, `PENDING_DOCUMENTS`, `CLOSED_BY_CLIENT`, `APPLICATION_IN_PROGRESS`.
`update.activityStatus`	No	`ACTIVE` or `NOT_ACTIVE`.
`update.sanctionsStatus`	No	`CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`.
`update.pepStatus`	No	`CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`.
`update.adverseMediaStatus`	No	`CLEAR`, `FLAGGED`, `UNDER_REVIEW`, `NOT_CHECKED`.
`update.currentRisk`	No	Risk assessment object (`score`, `level`, `reason`, `calculatedAt`).
`update.tagsToAdd`	No	Tags to add (additive — existing tags are preserved).
`update.tagsToRemove`	No	Tags to remove.
`update.customFields`	No	Key-value custom fields.

Bulk Update Response

{
  "updatedClients": [
    { "id": "client-uuid-001", "referenceId": "USER-001", "appliedChanges": { "accountStatus": "FROZEN" } },
    { "id": "client-uuid-002", "referenceId": "USER-002", "appliedChanges": { "accountStatus": "FROZEN" } }
  ],
  "failedClients": [],
  "totalProcessed": 3,
  "successCount": 2,
  "failureCount": 0
}

The response includes a per-client breakdown so you can identify any partial failures without re-querying each record individually.

What’s Next?

Once your clients are ingested, add their members, accounts, and transactional data.

Ingest Members

Add UBOs, directors, and signatories to corporate clients.

Accounts & Wallets

Ingest bank accounts and blockchain wallets.

Ingest Operations

Ingest deposits, withdrawals, and trades.

​Overview

​Step 1: Prepare Your Client Data

​Individual Clients

​Corporate Clients

​Step 2: Ingest Individual Clients

​Step 3: Ingest Corporate Clients

​Step 4: Retrieve a Client

​Get an Individual Client

​Get a Corporate Client

​Step 5: Update a Client

​Update an Individual Client

​Update a Corporate Client

​Step 6: Bulk Update Clients

​Bulk Update Individual Clients

​Bulk Update Corporate Clients

​Bulk Update Request Fields

​Bulk Update Response

​What’s Next?

Ingest Members

Accounts & Wallets

Ingest Operations

Overview

Step 1: Prepare Your Client Data

Individual Clients

Corporate Clients

Step 2: Ingest Individual Clients

Step 3: Ingest Corporate Clients

Step 4: Retrieve a Client

Get an Individual Client

Get a Corporate Client

Step 5: Update a Client

Update an Individual Client

Update a Corporate Client

Step 6: Bulk Update Clients

Bulk Update Individual Clients

Bulk Update Corporate Clients

Bulk Update Request Fields

Bulk Update Response

What’s Next?