Client portal integration

Client portal integration

How to generate, retrieve and monitor client portal links

Overview

Client Portal Links provide clients with a single URL to complete all onboarding tasks in one centralized dashboard. This eliminates multiple emails and provides visibility into overall completion status.

Benefits:

• One link for all tasks instead of individual onboarding request emails
• Real-time completion monitoring via webhooks
• Easy to embed in your application or customer portals

Quick Start

1. Generate Portal Link

Enable Client Portal for an account:

PATCH /clients/{clientId}/accounts/{accountId}

{
  "client_onboarding": {
    "share_progress": true
  }
}

Note: Use this same request to refresh an expiring link.

2. Retrieve Portal Link

Get the portal link and completion status:

GET /clients/{clientId}/accounts/{accountId}

Response:

{
  "client_onboarding": {
    "completed": false,
    "expires_at": "2026-02-21T15:40:35.692Z",
    "link": "https://platform.xamatech.com/client-onboarding?code=..."
  }
}

Key Fields:

• link - The URL to share with clients
• completed - true when the account has no outstanding ID verification requests
• expires_at - When the link expires

3. Monitor Completion with Webhooks

Subscribe to account updates to know when clients complete all tasks:

POST /clients/{clientId}/subscriptions

{
  "callback_url": "https://yourapp.com/webhooks/xama",
  "type": "WEBHOOK",
  "config": {
    "api_secret": "your-secret",
    "entities": [
      {
        "entity": "ACCOUNT",
        "events": ["ENTITY_UPDATED"]
      }
    ]
  }
}

When you receive an ENTITY_UPDATED webhook:

1. Retrieve the account via GET request
2. Check if client_onboarding.completed = true
3. Take action (notify team, update status, proceed with onboarding)

Common Use Cases

Onboarding Wizard:

• Create account and onboarding requests (with email suppressed)
• Generate portal link
• Display link in your onboarding flow
• Monitor completion via webhooks

Customer Portal:

• Display portal link on dashboard for incomplete verifications
• Show “Completed” status when completed = true
• Hide link once complete

Coming Soon

Enhanced Portal Insights API - Endpoint to retrieve detailed task breakdown and individual onboarding links (partner API key required).

Reference

• Accounts API - Full endpoint documentation (see API reference)
• Webhooks API - Webhook setup and signatures (see API reference)
• Onboarding Guide - Creating onboarding requests (see ID verification guide)