Skip to main content

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.

This guide walks you through ingesting KYC/KYB Verifications — records that capture the outcome of identity checks performed by external providers such as SumSub, Persona, or any other KYC/KYB vendor. Full API reference is available in the API Reference.
Before ingesting verifications, make sure the related client has already been ingested. See the Ingesting Clients guide. All SDK examples assume you have initialized the Corsa client as shown in the Node.js SDK Configuration or Python SDK Configuration guide.

​
Overview

A verification represents a single identity check run against a client by an external KYC/KYB provider. Corsa normalizes the result into a unified status field while also preserving the provider’s raw status for audit purposes. Each verification belongs to exactly one client and is uniquely identified by the combination of provider + providerId. Verification statuses:
StatusMeaning
REQUESTEDVerification has been requested but not yet started
PENDINGVerification is in progress at the provider
APPROVEDClient passed the verification check
REJECTEDClient failed the verification check
EXPIREDVerification expired before completion
CANCELLEDVerification was cancelled

​
Step 1: Create a Verification

Endpoint: POST /v1/clients/{clientId}/verifications Returns 409 Conflict if a verification with the same provider + providerId already exists for this client. 
POST /v1/clients/123e4567-e89b-12d3-a456-426614174000/verifications
Content-Type: application/json

{
  "provider": "SUMSUB",
  "providerId": "applicant_abc123",
  "providerStatus": "completed",
  "providerLink": "https://cockpit.sumsub.com/checkus/#/applicant/applicant_abc123",
  "status": "APPROVED",
  "startedAt": "2024-01-15T09:00:00Z",
  "completedAt": "2024-01-15T09:05:00Z",
  "checks": [
    { "type": "IDENTITY", "status": "GREEN" },
    { "type": "DOCUMENT", "status": "GREEN" }
  ]
}

​
Request Fields

FieldRequiredDescription
providerYesKYC/KYB provider name (e.g. SUMSUB, PERSONA)
providerIdYesUnique verification ID in the provider’s system
providerStatusYesRaw status string from the provider (e.g. completed, pending)
statusYesCorsa-normalized status: REQUESTED, PENDING, APPROVED, REJECTED, EXPIRED, or CANCELLED
providerLinkNoDirect link to this verification in the provider’s dashboard
reviewCommentNoSummary of the verification outcome
rejectLabelsNoArray of provider-specific rejection reason labels
startedAtNoISO 8601 timestamp when the verification was initiated
completedAtNoISO 8601 timestamp when the verification was completed
checksNoArray of individual checks performed (e.g. identity, document, liveness)
metadataNoAdditional provider-specific data as a JSON string

​
Step 2: Update a Verification

Endpoint: PUT /v1/clients/{clientId}/verifications/{verificationId} Use this endpoint to update a verification when its status changes at the provider — for example, when a PENDING check is completed. 
PUT /v1/clients/123e4567-e89b-12d3-a456-426614174000/verifications/ver_789xyz
Content-Type: application/json

{
  "providerStatus": "rejected",
  "status": "REJECTED",
  "rejectLabels": ["FORGERY", "FACE_MISMATCH"],
  "reviewComment": "Document appears tampered. Face does not match ID photo.",
  "completedAt": "2024-01-15T09:10:00Z"
}

​
Step 3: Look Up a Verification

Endpoint: GET /v1/clients/{clientId}/verifications/lookup?provider={provider}&providerId={providerId} Use this to retrieve an existing verification by provider + providerId without storing the Corsa verification ID on your side. 
GET /v1/clients/123e4567-e89b-12d3-a456-426614174000/verifications/lookup
  ?provider=SUMSUB
  &providerId=applicant_abc123

​
Verification Response

A successful create or update returns the full verification object: 
{
  "id": "ver_789xyz",
  "platformId": "platform_abc",
  "clientId": "123e4567-e89b-12d3-a456-426614174000",
  "provider": "SUMSUB",
  "providerId": "applicant_abc123",
  "providerStatus": "completed",
  "providerLink": "https://cockpit.sumsub.com/checkus/#/applicant/applicant_abc123",
  "status": "APPROVED",
  "reviewComment": null,
  "rejectLabels": [],
  "startedAt": "2024-01-15T09:00:00Z",
  "completedAt": "2024-01-15T09:05:00Z",
  "checks": [
    { "type": "IDENTITY", "status": "GREEN" },
    { "type": "DOCUMENT", "status": "GREEN" }
  ],
  "metadata": null,
  "createdAt": "2024-01-15T09:05:30Z",
  "updatedAt": "2024-01-15T09:05:30Z"
}

​
Integration Pattern

The typical flow when integrating with a KYC provider:
  1. Client submits verification at your platform — create a PENDING verification in Corsa.
  2. Provider webhook fires with the result — update the verification status in Corsa.
  3. Corsa reflects the updated status on the client profile for compliance review.
This keeps the client’s verification history in Corsa synchronized with your KYC provider in real time.