> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Onboarding Page

> The quickest way to build optimized identity verification pages, hosted on Gu1 — in the gu1 KYC API for identity verification flows.

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

<Info>
  **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.
</Info>

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Client as Your Client
    participant YourApp as Your Backend
    participant Gu1API as Gu1 API
    participant HostedPage as Hosted Page

    YourApp->>Gu1API: 1. Create person entity (POST /api/entities)
    Gu1API-->>YourApp: entity ID

    YourApp->>Gu1API: 2. Create KYC validation (POST /api/kyc/validations)
    Gu1API-->>YourApp: providerSessionUrl

    YourApp->>Client: 3. Send providerSessionUrl<br/>(Email, SMS, etc.)

    Client->>HostedPage: 4. Open providerSessionUrl
    HostedPage->>Client: Customized verification page

    Client->>HostedPage: 5. Upload document & selfie
    HostedPage->>Gu1API: Process verification

    Gu1API->>YourApp: 6. Webhook (approved/rejected)
    YourApp->>YourApp: Update user status

    Client->>HostedPage: See completion status
```

## Customization Parameters

You can customize the onboarding page using these parameters:

### Branding & Visual Customization

<ParamField path="domain" type="string">
  The web page can be hosted on your own domain
</ParamField>

<ParamField path="lang" type="string" default="en">
  The default page language. Supported values: `en`, `es`, `pt`
</ParamField>

<ParamField path="icon" type="string">
  The page icon (favicon)
</ParamField>

<ParamField path="logo" type="string">
  The main logo displayed on the page
</ParamField>

### Color Customization

All color parameters accept hex color codes (e.g., `#6366f1`):

<ParamField path="headersColor" type="string">
  Hex code for the headers color
</ParamField>

<ParamField path="paragraphsColor" type="string">
  Hex code for the paragraphs color
</ParamField>

<ParamField path="supportTextsColor" type="string">
  Hex code for the support texts color
</ParamField>

<ParamField path="backgroundColor" type="string">
  Hex code for the background color
</ParamField>

<ParamField path="pillsColor" type="string">
  Hex code for the pills color
</ParamField>

<ParamField path="progressBarColor" type="string">
  Hex code for the progress bar color
</ParamField>

<ParamField path="primaryButtonColor" type="string">
  Hex code for the primary button color
</ParamField>

<ParamField path="secondaryButtonColor" type="string">
  Hex code for the secondary button color
</ParamField>

<ParamField path="selectorColor" type="string">
  Hex code for the selector color
</ParamField>

<ParamField path="primaryButtonTextColor" type="string">
  Hex code for the primary button text color
</ParamField>

<ParamField path="secondaryButtonTextColor" type="string">
  Hex code for the secondary button text color
</ParamField>

<ParamField path="borderRadius" type="number">
  Web border radius. Number between 0 and 50
</ParamField>

## Validation Rules Configuration

You can customize the validation rules using these parameters:

### Age Verification

<ParamField path="Exclude By Age" type="number">
  Decline automatically all sessions performed by users under a certain age. Number between 1 and 100
</ParamField>

### Document Capture

<ParamField path="Capture Method" type="string">
  Select allowed methods for images:

  * `Camera` - Only camera capture
  * `Upload` - Only file upload
  * `Both` - Allow both methods
</ParamField>

### Duplicate Detection

<ParamField path="Duplicated users" type="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
</ParamField>

### Document Validation Rules

<ParamField path="QR / barcode" type="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
</ParamField>

<ParamField path="MRZ not valid" type="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
</ParamField>

<ParamField path="Expiration date" type="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
</ParamField>

<ParamField path="Invalid validation" type="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
</ParamField>

<ParamField path="Invalid document liveness" type="string">
  This issue arises when we are unable to validate document liveness:

  * `Approve` - Automatically approve
  * `Review` - Send to manual review
  * `Decline` - Automatically decline
</ParamField>

<ParamField path="Address not processed" type="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
</ParamField>

<Note>
  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.
</Note>

## How to Get the Onboarding Page URL?

<Steps>
  <Step title="Create a person entity">
    Create a person entity in Gu1 via the Entities API with your customer's basic information (name, taxId, countryCode).

    [Learn how to create an entity →](/api-reference/entities/create)
  </Step>

  <Step title="Create a KYC validation">
    Create a KYC validation session for that entity using `POST /api/kyc/validations` with the entity ID and `integrationCode` (e.g. `global_gueno_validation_kyc`).

    [Learn how to create a validation →](/en/use-cases/kyc/create-validation)
  </Step>

  <Step title="Get the providerSessionUrl">
    Retrieve the `providerSessionUrl` from the validation response. This is the hosted page URL you share with your client.
  </Step>

  <Step title="Share with your client">
    Share the `providerSessionUrl` with your client via email, SMS, or embed it in your application.
  </Step>
</Steps>

## Example Implementation

<CodeGroup>
  ```javascript Node.js theme={null}
  // 1. Create a person entity (Entities API)
  const entityRes = await fetch('https://api.gu1.ai/api/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'person',
      name: 'John Doe',
      taxId: '12345678900',
      countryCode: 'US',
      entityData: { person: { email: 'john@example.com' } }
    })
  });
  const entityData = await entityRes.json();
  const entityId = entityData.entity?.id ?? entityData.id;

  // 2. Create a KYC validation session
  const validationRes = 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,
      integrationCode: 'global_gueno_validation_kyc'
    })
  });
  const validationData = await validationRes.json();

  // 3. Get the hosted page URL (providerSessionUrl)
  const hostedPageUrl = validationData.providerSessionUrl;
  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}`
  });
  ```

  ```python Python theme={null}
  import requests

  # 1. Create a person entity (Entities API)
  entity_response = requests.post(
      'https://api.gu1.ai/api/entities',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'type': 'person',
          'name': 'John Doe',
          'taxId': '12345678900',
          'countryCode': 'US',
          'entityData': { 'person': { 'email': 'john@example.com' } }
      }
  )
  entity_data = entity_response.json()
  entity_id = entity_data.get('entity', {}).get('id') or entity_data.get('id')

  # 2. Create a KYC validation session
  validation_response = requests.post(
      'https://api.gu1.ai/api/kyc/validations',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': entity_id,
          'integrationCode': 'global_gueno_validation_kyc'
      }
  )
  validation_data = validation_response.json()

  # 3. Get the hosted page URL (providerSessionUrl)
  hosted_page_url = validation_data['providerSessionUrl']
  print('Share this URL with your client:', hosted_page_url)

  # 4. Share with client (via email, SMS, etc.)
  send_email(
      to='john@example.com',
      subject='Complete Your Identity Verification',
      body=f'Please complete your verification here: {hosted_page_url}'
  )
  ```

  ```curl cURL theme={null}
  # 1. Create a person entity (Entities API)
  curl -X POST https://api.gu1.ai/api/entities \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "person",
      "name": "John Doe",
      "taxId": "12345678900",
      "countryCode": "US"
    }'

  # Response: {"entity": {"id": "entity-uuid", ...}, ...} or {"id": "entity-uuid", ...}

  # 2. Create a KYC validation session
  curl -X POST https://api.gu1.ai/api/kyc/validations \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "entity-uuid",
      "integrationCode": "global_gueno_validation_kyc"
    }'

  # Response: {"id": "...", "providerSessionUrl": "https://...", "status": "pending", ...}

  # 3. Share the providerSessionUrl with your client
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Customize for Your Brand">
    Configure the color scheme, logo, and language to match your brand identity. This creates a seamless experience for your users.
  </Accordion>

  <Accordion title="Set Appropriate Validation Rules">
    Configure validation rules based on your compliance requirements and risk tolerance. More strict rules provide better security but may result in more manual reviews.
  </Accordion>

  <Accordion title="Monitor Session Status">
    Use webhooks to receive real-time notifications when verification completes. This allows you to immediately update user access in your system.
  </Accordion>

  <Accordion title="Handle Expiration & Security">
    **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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Entity" icon="user" href="/api-reference/entities/create">
    Learn how to create a person entity
  </Card>

  <Card title="Create Validation" icon="shield-check" href="/en/use-cases/kyc/create-validation">
    Create a KYC validation session
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/en/use-cases/kyc/webhook-integration">
    Receive real-time status updates
  </Card>

  <Card title="Client Integration" icon="code" href="/en/use-cases/kyc/client-integration">
    Embed in your mobile or web app
  </Card>
</CardGroup>