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. Email the Link to a Contact

Xama can email the link for you, using a CLIENT_ONBOARDING email template. First retrieve the templates available to the client:

GET /clients/{clientId}/mail-templates?q:type=CLIENT_ONBOARDING&q:status=ACTIVE

Then send the link, choosing the template and the recipient:

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

{
  "client_onboarding": {
    "share_progress": true,
    "ttl_in_hours": 720,
    "mail_template_id": "client-onboarding-invite",
    "recipient_contact_id": "1410c740-f1f9-11f0-99b0-ffb521a97a75"
  }
}

Fields:

• share_progress - true to enable or regenerate the link, false to revoke it
• ttl_in_hours - How long the link stays valid, for example 720 for 30 days
• mail_template_id - The CLIENT_ONBOARDING template to send. It must be ACTIVE; an archived template is rejected
• recipient_contact_id - The contact who receives the email. That contact must have an email address on file

All fields are optional, so send only the combination you need. Use share_progress on its own to generate a link without emailing it, and use it with false to revoke:

{ "client_onboarding": { "share_progress": false } }

Make sure you filter templates to CLIENT_ONBOARDING. The ONBOARDING type is for individual onboarding requests and is not interchangeable — see the ID verification guide.

Note: These endpoints return 402 Payment Required if the client does not have the required subscription. Treat that as a permanent condition for that client and hide the portal option rather than retrying.

3. 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

4. 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)