Skip to main content

Overview

Our hosted solution is a secure, fully customizable, hosted KYC and identity verification page that enables you to verify your clients quickly without any code. The hosted onboarding page is the fastest way to get started with KYC verification.
Mobile-Responsive Design: The hosted page is fully responsive and optimized for all devices (desktop, tablet, and mobile). Your users will have a seamless verification experience regardless of the device they use.

How It Works

Customization Parameters

You can customize the onboarding page using these parameters:

Branding & Visual Customization

domain
string
The web page can be hosted on your own domain
lang
string
default:"en"
The default page language. Supported values: en, es, pt
icon
string
The page icon (favicon)
The main logo displayed on the page

Color Customization

All color parameters accept hex color codes (e.g., #6366f1):
headersColor
string
Hex code for the headers color
paragraphsColor
string
Hex code for the paragraphs color
supportTextsColor
string
Hex code for the support texts color
backgroundColor
string
Hex code for the background color
pillsColor
string
Hex code for the pills color
progressBarColor
string
Hex code for the progress bar color
primaryButtonColor
string
Hex code for the primary button color
secondaryButtonColor
string
Hex code for the secondary button color
selectorColor
string
Hex code for the selector color
primaryButtonTextColor
string
Hex code for the primary button text color
secondaryButtonTextColor
string
Hex code for the secondary button text color
borderRadius
number
Web border radius. Number between 0 and 50

Validation Rules Configuration

You can customize the validation rules using these parameters:

Age Verification

Exclude By Age
number
Decline automatically all sessions performed by users under a certain age. Number between 1 and 100

Document Capture

Capture Method
string
Select allowed methods for images:
  • Camera - Only camera capture
  • Upload - Only file upload
  • Both - Allow both methods

Duplicate Detection

Duplicated users
string
When a user has previously approved documents from the same application, you can set an automatic rule on how to proceed:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline

Document Validation Rules

QR / barcode
string
If a barcode or QR code was expected in the document but couldn’t be read, you can set an automatic rule:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline
MRZ not valid
string
When a Machine-Readable Zone (MRZ) is expected in the document but cannot be read:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline
Expiration date
string
When a document’s expiration date is expected but cannot be read or is in an invalid format:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline
Invalid validation
string
This issue arises when we are unable to validate a date, detect a document number, or accurately recognize the document:
  • Review - Send to manual review
  • Decline - Automatically decline
Invalid document liveness
string
This issue arises when we are unable to validate document liveness:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline
Address not processed
string
This issue arises when the address on the document could not be found or geolocated, likely due to an invalid or missing address:
  • Approve - Automatically approve
  • Review - Send to manual review
  • Decline - Automatically decline
These validation parameters must be communicated to the Gu1 team through your dedicated support channel. If you need to make changes or modifications to these parameters, please submit a request via your dedicated client support channel. In the future, these parameters will be editable in the Gu1 dashboard.

How to Get the Onboarding Page URL?

1

Create a Person

First, create a person entity in Gu1 with your customer’s basic informationLearn how to create a person →
2

Create a Session

Create a KYC validation session for that personLearn how to create a validation →
3

Get the sessionUrl

Retrieve the sessionUrl from the response. This is the hosted page URL you can share with your client
4

Share with Your Client

You can share the sessionUrl with your client via email, SMS, or embed it in your application

Example Implementation

// 1. Create a person
const person = await fetch('https://api.gu1.ai/api/person', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com',
    taxId: '12345678900',
    type: 'person'
  })
});

const personData = await person.json();

// 2. Create a KYC validation session
const validation = await fetch('https://api.gu1.ai/api/kyc/validations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entityId: personData.id,
    workflowId: 'your-workflow-id'
  })
});

const validationData = await validation.json();

// 3. Get the hosted page URL
const hostedPageUrl = validationData.sessionUrl;
console.log('Share this URL with your client:', hostedPageUrl);

// 4. Share with client (via email, SMS, etc.)
await sendEmail({
  to: 'john@example.com',
  subject: 'Complete Your Identity Verification',
  body: `Please complete your verification here: ${hostedPageUrl}`
});

Best Practices

Configure the color scheme, logo, and language to match your brand identity. This creates a seamless experience for your users.
Configure validation rules based on your compliance requirements and risk tolerance. More strict rules provide better security but may result in more manual reviews.
Use webhooks to receive real-time notifications when verification completes. This allows you to immediately update user access in your system.
Session Expiration: Sessions typically expire after 7 days. If a user’s session expires, create a new validation to generate a fresh URL.Security Best Practices:
  • Never expose the sessionUrl publicly (don’t share in public forums, public URLs, etc.)
  • Always generate URLs server-side - never expose API keys in client-side code
  • Use HTTPS when sharing URLs via your own systems
  • Implement proper authentication before generating sessions for users
  • Consider implementing rate limiting on session creation to prevent abuse
  • Store validation IDs in your database linked to user records for audit trails

Next Steps