eKYC API - Sumsub Integration

Electronic Know Your Customer (eKYC) verification powered by Sumsub. Supports both individual verification (eKYC) and business verification (eKYB) with automatic database synchronization via webhooks.

Verification Levels:

eKYC (Individual): brdz-ekyc-indonesia-standard
eKYB (Company): brdz-kyb-level

Get eKYC Status

GET/api/ekyc/status/{user_id}

Get eKYC Status

Retrieve the current eKYC verification status for a user. Returns verification status, timestamps, and user status information.

Parameters

user_idstringrequired

User ID (path parameter)

client_idstringrequired

Client ID (query parameter)

Response

200eKYC status retrieved successfully

{
  "message": "Status eKYC user Found",
  "data": {
    "user_id": "12345",
    "ekyc_status": "APPROVED",
    "ekyc_verified_at": "2024-01-15T10:30:00Z",
    "user_status": "ACTIVE"
  }
}

400Missing required parameters

{
  "error": "user_id and client_id need to fill."
}

404User or client not found

{
  "error": "User or Client not found or not match."
}

500Server error

{
  "error": "Failed to get status of eKYC user",
  "details": "Database connection failed"
}

200_no_dataUser has no eKYC data

{
  "message": "Dont have eKYC data",
  "data": {
    "user_id": "12345",
    "ekyc_status": "Not yet Submit",
    "ekyc_verified_at": null,
    "user_status": "PENDING"
  }
}

curl -X GET "https://api.brdz.link/api/ekyc/status/12345?client_id=67890" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Generate Sumsub Token (eKYC)

POST/api/ekyc/sumsub/token

Generate Sumsub Access Token for eKYC

Generate Sumsub SDK access token for individual verification (eKYC). Token has 10-minute expiration and uses individual verification level.

Request Body

{}

Response

200Token generated successfully

{
  "token": "sbx:uY0CgwELmgQAAAAJ-0S4d-JwqtVOmWPGZzAIKLLkVQKgBMASIJIbLJWLHxJD"
}

400Sumsub API error

{
  "error": "INVALID_PARAMS",
  "description": "Invalid verification level"
}

500Server error

{
  "error": "Internal server error"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/token \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

Generate Sumsub Token (eKYB)

POST/api/ekyc/sumsub/token-kyb

Generate Sumsub Access Token for eKYB

Generate Sumsub SDK access token for business verification (eKYB). Token has 10-minute expiration and uses company verification level.

Request Body

{}

Response

200KYB token generated successfully

{
  "token": "sbx:uY0CgwELmgQAAAAJ-0S4d-JwqtVOmWPGZzAIKLLkVQKgBMASIJIbLJWLHxJD"
}

400Sumsub KYB API error

{
  "error": "INVALID_PARAMS",
  "description": "Invalid KYB verification level"
}

500Server error

{
  "error": "Internal server error"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/token-kyb \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

Generate Web SDK Link (eKYC)

POST/api/ekyc/sumsub/websdk/{userId}

Generate Web SDK Link for eKYC

Generate Sumsub Web SDK direct link for individual verification. Creates applicant record and returns hosted verification URL.

Parameters

userIdstringrequired

User ID for verification (path parameter)

Request Body

{}

Response

200Web SDK link generated successfully

{
  "sdkLink": "https://cockpit.sumsub.com/checkus/websdk/i/brdz-ekyc-indonesia-standard/12345?utm_medium=websdk&accessToken=sbx:..."
}

400Sumsub API error

{
  "error": "INVALID_PARAMS",
  "description": "Invalid user ID or verification level"
}

500Failed to generate Web SDK link

{
  "error": "Failed to generate Web SDK link"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/websdk/12345 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

Generate Web SDK Link (eKYB)

POST/api/ekyc/sumsub/websdk-kyb/{userId}

Generate Web SDK Link for eKYB

Generate Sumsub Web SDK direct link for business verification. Creates applicant record and returns hosted KYB verification URL.

Parameters

userIdstringrequired

User ID for business verification (path parameter)

Request Body

{}

Response

200KYB Web SDK link generated successfully

{
  "sdkLink": "https://cockpit.sumsub.com/checkus/websdk/i/brdz-kyb-level/12345?utm_medium=websdk&accessToken=sbx:..."
}

400Sumsub KYB API error

{
  "error": "INVALID_PARAMS",
  "description": "Invalid user ID or KYB verification level"
}

500Failed to generate KYB Web SDK link

{
  "error": "Failed to generate KYB Web SDK link"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/websdk-kyb/12345 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

Sync Sumsub Status

POST/api/ekyc/sumsub/syncSumsubStatus

Manual Sync Sumsub Status

Manually synchronize verification status from Sumsub. Used for manual status updates when webhook fails or for testing purposes. No authentication required.

Parameters

applicantIdstringrequired

Sumsub applicant ID

user_idstringrequired

BRDZ user ID

reviewStatusstringrequired

Review status from Sumsub (completed, pending, etc.)

reviewAnswerstringrequired

Review answer from Sumsub (GREEN, RED, etc.)

verification_typestring

Type of verification: 'KYC' or 'KYB' (default: KYC)

Request Body

{
  "applicantId": "64f8a9b2c1e2d3f4a5b6c7d8",
  "user_id": "12345",
  "reviewStatus": "completed",
  "reviewAnswer": "GREEN",
  "verification_type": "KYC"
}

Response

200Status updated successfully

{
  "message": "User status updated to APPROVED"
}

400Missing required fields

{
  "error": "Missing required fields (user_id, applicantId, reviewStatus, reviewAnswer)"
}

500Database error

{
  "error": "Failed to update database",
  "details": "Connection timeout"
}

200_kybKYB status updated successfully

{
  "message": "eKYB status updated to APPROVED"
}

200_not_approvedStatus not yet approved

{
  "message": "Status not yet APPROVED",
  "current_status": "pending",
  "reviewAnswer": "RED"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/syncSumsubStatus \
-H "Content-Type: application/json" \
-d '{
  "applicantId": "64f8a9b2c1e2d3f4a5b6c7d8",
  "user_id": "12345",
  "reviewStatus": "completed",
  "reviewAnswer": "GREEN",
  "verification_type": "KYC"
}'

Change Verification Level

POST/api/ekyc/sumsub/changeLevel

Change Verification Level

Move user from one verification level to another (e.g., from eKYC to eKYB). Admin access required. Uses Sumsub moveToLevel API.

Parameters

user_idstringrequired

User ID to change verification level

levelNamestringrequired

New verification level name

Request Body

{
  "user_id": "12345",
  "levelName": "brdz-kyb-level"
}

Response

200Verification level changed successfully

{
  "success": true,
  "data": {
    "applicantId": "64f8a9b2c1e2d3f4a5b6c7d8",
    "levelName": "brdz-kyb-level",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

400Missing required fields

{
  "error": "Missing user_id or levelName"
}

404Applicant not found

{
  "error": "ApplicantId not found for this user"
}

500Server error

{
  "error": "Internal Server Error"
}

400_sumsubSumsub API error

{
  "error": "INVALID_PARAMS",
  "description": "Invalid level name or applicant state"
}

curl -X POST https://api.brdz.link/api/ekyc/sumsub/changeLevel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "user_id": "12345",
  "levelName": "brdz-kyb-level"
}'

eKYC Status Values

Individual Verification (eKYC)

Not yet Submit: User hasn't started verification
PENDING: Verification documents submitted, under review
APPROVED: Successfully verified, user activated
REJECTED: Verification failed or documents rejected

Business Verification (eKYB)

PENDING: Business documents submitted, under review
APPROVED: Company successfully verified
REJECTED: Business verification failed

Verification Flow

Individual (eKYC) Flow

Generate Token: Get Sumsub SDK token for individual verification
Initialize SDK: User completes identity verification in browser
Webhook Processing: Sumsub automatically notifies BRDZ of results
Database Sync: Internal systems update user status
Wallet Activation: Auto-create user wallet if approved

Business (eKYB) Flow

Generate KYB Token: Get Sumsub SDK token for business verification
Company Verification: Admin submits business documents
Enhanced Review: Additional compliance checks for businesses
Webhook Processing: Sumsub notifies of KYB results
Client Activation: Company client status updated

Webhook Integration

Sumsub automatically sends verification results to BRDZ via secure webhooks:

Signature Verification: SHA256 HMAC validation
Auto Status Sync: Real-time database updates
Wallet Creation: Automatic wallet setup for approved users
Client Updates: Company status synchronization

Error Handling

Common Sumsub Errors

INVALID_PARAMS: Invalid verification level or user data
APPLICANT_NOT_FOUND: User doesn't exist in Sumsub system
LEVEL_NOT_FOUND: Verification level configuration missing
TOKEN_EXPIRED: SDK token expired (10-minute limit)

Database Errors

User Not Found: Invalid user_id or client_id mismatch
Connection Failed: Database connectivity issues
Transaction Failed: Data consistency errors during updates

Security Features

Authentication

JWT Tokens: User authentication for all protected endpoints
API Keys: Application-level authentication
Role-based Access: Admin-only endpoints for sensitive operations

Data Protection

Webhook Signatures: HMAC-SHA256 verification for webhook security
Token Expiration: Short-lived SDK tokens (10 minutes)
Encrypted Storage: Secure storage of verification data
Audit Logging: Complete verification history tracking

Compliance

KYC Standards: Meets international identity verification requirements
AML Compliance: Anti-money laundering checks integrated
Data Retention: Configurable document retention policies
Privacy Controls: GDPR-compliant data handling

Integration

Use SDK tokens for seamless frontend integration with Sumsub Web SDK. Tokens are short-lived (10 minutes) for security.

Webhook Security

Webhook endpoints must validate Sumsub signatures to prevent unauthorized status updates. Never trust unverified webhook data.

Manual Sync

Use syncSumsubStatus for manual verification status updates when webhooks fail or for testing scenarios.

Get eKYC Status​

Get eKYC Status

Parameters

Response

Generate Sumsub Token (eKYC)​

Generate Sumsub Access Token for eKYC

Request Body

Response

Generate Sumsub Token (eKYB)​

Generate Sumsub Access Token for eKYB

Request Body

Response

Generate Web SDK Link (eKYC)​

Generate Web SDK Link for eKYC

Parameters

Request Body

Response

Generate Web SDK Link (eKYB)​

Generate Web SDK Link for eKYB

Parameters

Request Body

Response

Sync Sumsub Status​

Manual Sync Sumsub Status

Parameters

Request Body

Response

Change Verification Level​

Change Verification Level

Parameters

Request Body

Response

eKYC Status Values​

Individual Verification (eKYC)​

Business Verification (eKYB)​

Verification Flow​

Individual (eKYC) Flow​

Business (eKYB) Flow​

Webhook Integration​

Error Handling​

Common Sumsub Errors​

Database Errors​

Security Features​

Authentication​

Data Protection​

Compliance​

Get eKYC Status

Generate Sumsub Token (eKYC)

Generate Sumsub Token (eKYB)

Generate Web SDK Link (eKYC)

Generate Web SDK Link (eKYB)

Sync Sumsub Status

Change Verification Level

eKYC Status Values

Individual Verification (eKYC)

Business Verification (eKYB)

Verification Flow

Individual (eKYC) Flow

Business (eKYB) Flow

Webhook Integration

Error Handling

Common Sumsub Errors

Database Errors

Security Features

Authentication

Data Protection

Compliance