Skip to main content

​
IdCanopy SDK

The IdCanopy SDK is not a traditional installable library.
Instead, it is a lightweight API + Hosted UI flow that lets you embed fully managed KYC/KYB journeys into your application with minimal effort. You make a handshake API call, receive a uiHandle URL, and then iframe or redirect your user into IdCanopy’s hosted verification interface. No package installation, no build-time dependencies — just HTTPS calls and a URL.

​
Integration in a nutshell

  1. Authenticate:
    • SDK obtains and manages the bearer token for you.
  2. Handshake:
    • create a journey and receive transactionId and uiHandle.
  3. Run the flow:
    • either embed the Hosted UI (iframe/redirect) or mount UI modules.
  4. Listen to events & webhooks:
    • update your UI in real time and consume final results from your webhook.
  5. Retrieve results:
    • via webhook payloads (recommended) or service APIs.

​
Prerequisites

  • API Key and Customer ID (from your IdCanopy account)
  • Environment: Sandbox or Production
    • Base API (prod): https://api-umbrella.io/api/services
    • Auth (prod): https://api-umbrella.io/api/services/auth
    • Auth (sandbox): https://sandbox-umbrella-api.azurewebsites.net/api/services/auth
  • Webhook URL reachable over HTTPS + Webhook Secret (for HMAC verification)

​
Basics

  • Error Handling: The IdCanopy API responds with clear error codes and messages in case of any issues during the journey. You can integrate these error responses into your application logic for appropriate user handling.
  • Scalability and Performance: IdCanopy’s infrastructure is designed to handle high volumes of verification requests while maintaining performance and reliability.
  • Security Considerations:
  • Secure communication protocols (JWT, OAuth2) ensure data confidentiality and integrity.
  • Data encryption protects sensitive user information both at rest and in transit.
  • Regular security audits and penetration testing guarantee a secure platform.

​
Authentication

IdCanopy supports secure communication through industry-standard authentication protocols:
  • JWT (JSON Web Token): A self-contained token containing encoded information for user verification.
  • OAuth2: An authorization framework enabling secure delegation of user authentication.
  • Basic Authentication

​
Handshake (Journey Creation)

Defines the entire verification flow:
  • steps and modules (documentVerification, amlScreening, mobileIdent, idvProtocol, etc.)
  • configuration options for each step
  • validationData (fullName, DOB, address, iban, phoneNumber, etc.)
  • optional developer mode (magicFlow)
  • optional pass-through metadata (passThroughData)
The handshake returns a uiHandle that your frontend loads.

​
Hosted Verification UI

The UI at the uiHandle link handles:
  • document verification
  • face match & liveness
  • AML screening
  • phone identity checks
  • and all configured steps
This allows you to ship verification without building UI components yourself.

​
Webhooks

When the journey finishes, IdCanopy sends a detailed structured payload to your webhook:
  • identity data
  • authoritative document data
  • fraud signals
  • proof-of-work artifacts
  • full audit trail
  • your original passThroughData metadata

​
Customer Journeys

Customer journeys represent multi-step verification processes a user undergoes. Each journey can encompass various steps like documentVerification (KYC), address verification, and sanction checks. Benefits:
  • Streamlined user experience: users interact with a single experience for the entire verification process.
  • Customization: Tailor behavior for individual journeys through handshake parameters.
  • Flexibility: Pass-through data allows for custom information exchange.
  • Reduced Costs: Efficient automation saves time and resources compared to manual verification.
  • Increased Compliance: Adherence to KYC and AML regulations ensures regulatory compliance.