KYC (Know Your Customer) API

Sznd provides KYC (Know Your Customer) verification through the business API to help you onboard and verify your customers programmatically.

Overview

KYC verification is required for customers to access certain features including deposits, withdrawals, and currency exchanges. Our KYC process securely verifies customer identities and documents through our integrated verification system.

Programmatic KYC

Submit KYC documents and customer information directly through the business API when you want onboarding to stay inside your own integration flow.

Submit KYC via API

Full Customer Registration with KYC

Endpoint: POST /api/v1/client/customers/full

Authentication: Required (HMAC - Business API Key)

This endpoint allows you to register a customer and submit all KYC data including documents in a single transaction. See the for complete details.

Supported Identity Documents

The following government-issued identity documents are accepted for KYC verification:

Primary Identity Documents

  1. Passport

    • Valid passport from any country
    • Must include front page with photo and personal details
    • Must be current and not expired

  2. National ID Card

    • Government-issued national identification card
    • Must include front and back images
    • Must be current and not expired
    • Examples: Nigerian National ID, US State ID, etc.

  3. Driver's License

    • Valid driver's license from any country
    • Must include front and back images
    • Must be current and not expired

  4. Residence Permit

    • Valid residence permit or visa
    • Required for non-citizens in certain jurisdictions
    • Must be current and not expired

  5. Proof of Address (Additional Document)

    • Utility bill (electricity, water, gas)
    • Bank statement
    • Government-issued document with address
    • Must be dated within the last 3 months

Document Requirements

All identity documents must meet the following requirements:

  • Validity: Documents must be current and not expired (unless expiry date is not applicable)
  • Clarity: Images must be clear, legible, and in good condition
  • Completeness: Both front and back images are required (where applicable)
  • Format: Documents must be submitted as high-quality images (minimum 20KB file size)
  • Authenticity: Documents must be genuine and not altered or tampered with

Document Image Specifications

  • Format: JPEG, PNG, or PDF
  • Minimum Size: 20KB per image
  • Minimum Dimensions: Must meet minimum resolution requirements for verification
  • Quality: Clear, readable text and visible photo
  • Orientation: Correctly oriented (not rotated)

Personal Data Collected

During the KYC verification process, the following personal information is collected:

Required Information

Data FieldDescriptionAPI Field
First NameLegal first name as it appears on identity documentfirst_name
Last NameLegal last name as it appears on identity documentlast_name
Date of BirthDate of birth in YYYY-MM-DD formatdate_of_birth
Email AddressValid email addressemail
Phone NumberContact phone numberphone_number
Country CodeISO country codecountry_code
AddressComplete residential addressaddress_line_1, address_line_2, city, postal_code, province, country_code

Address Information

The following address details are collected:

  • Street Address (Line 1) - Primary street address (required)
  • Street Address (Line 2) - Apartment, suite, or unit number (optional)
  • City - City name (required)
  • State/Province - State or province (if applicable)
  • Postal Code - ZIP code or postal code (required)
  • Country - Country of residence (required, ISO country code)

Optional Information

Data FieldDescriptionWhen Required
Middle NameMiddle name or initialIf present on identity document
Tax IDTax identification number (e.g., SSN, TIN)Required for certain jurisdictions or high-value transactions
Occupation CodeProfessional occupation classificationFor compliance and risk assessment
Employment StatusCurrent employment statusFor compliance and risk assessment
Source of FundsOrigin of funds for transactionsFor compliance and anti-money laundering
Account PurposeIntended use of the accountFor compliance and risk assessment
Monthly Transaction AmountsExpected monthly transaction volumeFor compliance and risk assessment

Document-Specific Information

For each identity document submitted, the following information is collected:

  • Document Type - Type of document (Passport, National ID, Driver's License, etc.)
  • Document Number - Unique identifier on the document (if available)
  • Issuing Country - Country that issued the document
  • Issue Date - Date when the document was issued
  • Expiry Date - Date when the document expires (if applicable)
  • Front Image - Image of the front side of the document (base64 encoded)
  • Back Image - Image of the back side of the document (where applicable, base64 encoded)

KYC Verification Flow

Using KYC Link (Method 1)

  1. Generate Link - Call registration or resume onboarding endpoint
  2. Send Link to Customer - Pass the link from the response to your customer
  3. Customer Completes KYC - Customer completes verification on our secure interface
  4. Onboard Contact - Use the token to onboard the contact via /business/contact/onboard

Using API Submission (Method 2)

  1. Collect KYC Data - Gather all required customer information and documents
  2. Submit via API - Call /client/customers/full with all KYC data and documents
  3. Receive User - Get back the user object with KYC status

KYC Status

After onboarding, you can check the KYC status in the user object:

  • APPROVED - KYC verification completed successfully
  • PENDING - Verification is in progress
  • REJECTED - Verification failed (check for additional details)
  • NOT_STARTED - KYC verification has not been initiated

Check KYC Status

javascript
// After onboarding, check the user's KYC statusconst user = await onboardContactWithKYCToken(tokenId, accessToken);
if (user.kyc_status === 'APPROVED') {  console.log('Customer is verified and ready to transact');} else if (user.kyc_status === 'PENDING') {  console.log('KYC verification is in progress');} else if (user.kyc_status === 'REJECTED') {  console.log('KYC verification failed - customer needs to resubmit');}

Error Handling

Common Errors

Status CodeErrorDescription
400Bad RequestInvalid request format or missing required fields
401UnauthorizedInvalid or missing authentication token
403ForbiddenEmail mismatch or unauthorized access
404Not FoundUser not found (for resume onboarding)
500Internal Server ErrorServer error during processing

Error Response Format

json
{  "error": "Token is required",  "message": "The token_id field is required for onboarding"}

Best Practices

  1. Handle Expiration - KYC links expire (typically 3 days). Generate new links if needed
  2. Monitor Status - Regularly check KYC status after onboarding
  3. Error Handling - Implement proper error handling for failed verifications
  4. Retry Logic - Implement retry logic for transient failures
  5. Webhook Integration - Set up webhooks to receive KYC status updates automatically
  6. Document Quality - Ensure document images are clear, legible, and meet minimum quality requirements
  7. Transaction Safety - When using the full registration endpoint, be aware that all operations are transactional and will roll back on failure

Webhook Integration

Consider setting up webhooks to receive real-time KYC status updates. This allows you to:

  • Get notified when KYC verification completes
  • Handle status changes automatically
  • Update your system when verification fails

See the for more information.

Compliance and Regulations

Our KYC process complies with:

  • Anti-Money Laundering (AML) regulations
  • Know Your Customer (KYC) requirements
  • Customer Due Diligence (CDD) standards
  • Financial Action Task Force (FATF) recommendations
  • Local regulatory requirements in jurisdictions where we operate

Next Steps

  • - Learn about API authentication
  • - Set up webhooks for KYC status updates
  • - Create quotes for verified customers