Sumsub Node SDK

Modern TypeScript/JavaScript SDK for the Sumsub KYC/AML platform with full TypeScript support and dual module format compatibility.

Installation

npm install sumsub-node-sdk
# or
yarn add sumsub-node-sdk

Quick Start

import { sdk } from "sumsub-node-sdk";
// or
import SumsubSDK from "sumsub-node-sdk";

const sumsub = sdk({
  baseURL: "https://api.sumsub.com",
  secretKey: "your-secret-key",
  appToken: "your-app-token"
});

// Check API status
const status = await sumsub.getStatus();
console.log("API Status:", status.data);

Configuration

interface SumsubConfig {
  baseURL: string; // Sumsub API base URL
  secretKey: string; // Your secret key
  appToken: string; // Your app token
}

API Methods

Applicant Management

// Create new applicant
const applicant = await sumsub.createApplicant("external-user-id", "basic-kyc-level", {
  email: "[e-mail]",
  phone: "[phone]"
});

// Get applicant by ID
const applicantData = await sumsub.getApplicant(applicantId);

// Get applicant by external user ID
const applicantByExternal = await sumsub.getApplicantByExternalUserId("external-user-id");

// Generate access token for web SDK
const accessToken = await sumsub.generateAccessToken("external-user-id", "basic-kyc-level", 1800);

// Get required documents
const requiredDocs = await sumsub.getRequiredIdDocs(applicantId);

// Get applicant status
const status = await sumsub.getReviewStatus(applicantId);

Document Management

// Add ID document
const document = await sumsub.addIdDocument(
  applicantId,
  {
    idDocType: "PASSPORT",
    country: "USA"
  },
  fileBuffer
);

// Get document image
const image = await sumsub.getDocumentImage(inspectionId, imageId);

Transaction Monitoring (KYT)

// Submit transaction
const transaction = await sumsub.submitTransaction(applicantId, {
  txnId: "unique-transaction-id",
  txnType: "DEPOSIT",
  amount: "1000.00",
  currency: "USD"
});

// Get transaction
const txnData = await sumsub.getTransaction(transactionId);

// Find transactions
const transactions = await sumsub.findTransactions({
  limit: 10,
  order: "createdAt:desc"
});

Web SDK Integration

// Generate Web SDK link
const webSDK = await sumsub.generateWebSDKLink({
  externalUserId: "user-123",
  levelName: "basic-kyc-level",
  ttlInSecs: 1800
});

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { SumsubConfig, IdDocType } from "sumsub-node-sdk";

const config: SumsubConfig = {
  baseURL: "https://api.sumsub.com",
  secretKey: process.env.SUMSUB_SECRET_KEY!,
  appToken: process.env.SUMSUB_APP_TOKEN!
};

// Enum support for document types
const docType: IdDocType = IdDocType.PASSPORT;

Error Handling

try {
  const applicant = await sumsub.getApplicant("invalid-id");
} catch (error) {
  if (error.response) {
    console.error("API Error:", error.response.status, error.response.data);
  } else {
    console.error("Network Error:", error.message);
  }
}

Environment Variables

SUMSUB_BASE_URL=https://api.sumsub.com
SUMSUB_SECRET_KEY=your-secret-key
SUMSUB_APP_TOKEN=your-app-token

Module Compatibility

This SDK supports both CommonJS and ES modules:

// CommonJS
const { sdk } = require("sumsub-node-sdk");

// ES Modules
import { sdk } from "sumsub-node-sdk";
import SumsubSDK from "sumsub-node-sdk"; // Default export

Requirements

• Node.js >= 18.0.0
• TypeScript >= 4.7 (for TypeScript usage)

Dependencies

• axios (peer dependency) - HTTP client
• form-data - Multipart form data support

Development

Build from source

npm run build

Run tests

npm test

Test examples

See /tests/sumsub.spec.ts for comprehensive usage examples.

Breaking Changes

Version 2.0.0

⚠️ BREAKING CHANGE: Automatic URI Encoding

Starting with version 2.0.0, all URL parameters are automatically URI-encoded using encodeURIComponent(). This ensures proper handling of special characters in parameters.

What Changed:

• All user-provided parameters in URL paths and query strings are now automatically encoded
• Affects parameters like externalUserId, levelName, clientId, shareToken, etc.
• Special characters (spaces, pipes |, dots ., etc.) are now properly encoded

Migration Guide:

If your code manually encodes parameters, you must remove the manual encoding:

// ❌ Before (v1.x.x) - Manual encoding required
const externalUserId = "auth0|user123";
await sumsub.getApplicantByExternalUserId(encodeURIComponent(externalUserId));

// ✅ After (v2.0.0+) - Automatic encoding, manual encoding will cause double-encoding
const externalUserId = "auth0|user123";
await sumsub.getApplicantByExternalUserId(externalUserId);

Affected Methods:

• getApplicantByExternalUserId()
• createApplicant() (levelName parameter)
• importApplicant() (levelName parameter)
• changeApplicantLevel() (levelName parameter)
• generateAccessToken() (externalUserId and levelName parameters)
• createShareToken() (clientId parameter)
• shareApplicant() (shareToken and resetIdDocSetTypes parameters)
• getModerationStates() (applicantId parameter)
• requestApplicantCheckWithVerificationType() (reasonCode parameter)
• getAvailableCurrencies() (type parameter)

This change improves reliability when working with external user IDs containing special characters (like Auth0 user IDs with pipes: auth0|123456).

API Reference

For complete API documentation, visit: https://developers.sumsub.com/api-reference

License

ISC

Links

• https://github.com/agio-digital
• https://www.npmjs.com/package/sumsub-node-sdk
• https://agiodigital.com

Contact

[e-mail]