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

# KYC Upgrade

> Complete guide for upgrading user KYC levels

# KYC Upgrade Guide

Complete guide for upgrading user KYC (Know Your Customer) levels to unlock higher transaction limits.

## Overview

OLIVE uses a tiered KYC system that balances ease of use with regulatory compliance. Higher KYC levels unlock greater transaction limits.

***

## KYC Levels

| Level        | Requirements          | Daily Limit   | Monthly Limit  |
| ------------ | --------------------- | ------------- | -------------- |
| **Basic**    | Phone + Name          | 100,000 SLE   | 500,000 SLE    |
| **Enhanced** | ID Front + Back       | 500,000 SLE   | 2,500,000 SLE  |
| **Full**     | Verified ID + Address | 2,000,000 SLE | 10,000,000 SLE |

<Info>
  All new users start at Basic level after phone verification.
</Info>

***

## Upgrade Methods

<Tabs>
  <Tab title="WhatsApp Agent">
    Users can upgrade via the WhatsApp conversational agent
  </Tab>

  <Tab title="Admin Dashboard">
    Admins can upgrade users after manual document review
  </Tab>

  <Tab title="API">
    Third-party integrations can submit KYC documents via API
  </Tab>
</Tabs>

***

## WhatsApp Upgrade Flow

The most common upgrade path uses the WhatsApp agent:

<Steps>
  <Step title="Initiate Upgrade">
    User messages: "upgrade my account" or "I want higher limits"
  </Step>

  <Step title="Agent Explains">
    Agent explains requirements and asks for ID front photo
  </Step>

  <Step title="Upload ID Front">
    User sends photo of ID card (front)
  </Step>

  <Step title="Upload ID Back">
    Agent asks for ID back photo, user sends
  </Step>

  <Step title="Validation">
    System validates both images using OCR and AI
  </Step>

  <Step title="Result">
    If valid, account upgraded. If issues found, user notified.
  </Step>
</Steps>

### Example Conversation

```
User: upgrade my account
Agent: I can help you upgrade your account! This will increase your 
       transaction limits. Please send a clear photo of the FRONT 
       of your Sierra Leone National ID card.

User: [sends ID front photo]
Agent: Great! Now please send the BACK of your ID card.

User: [sends ID back photo]  
Agent: Your documents have been verified. Your account has been 
       upgraded to Enhanced level. Your new daily limit is 500,000 SLE.
```

***

## ID Requirements

### Accepted Documents

| Document                 | Requirements          |
| ------------------------ | --------------------- |
| Sierra Leone National ID | Front and back photos |
| Passport                 | Photo page            |
| Driver's License         | Front and back photos |

### Photo Requirements

<CardGroup cols={2}>
  <Card title="Do" icon="check">
    * Clear, well-lit photo
    * All text readable
    * Full document visible
    * Flat surface
  </Card>

  <Card title="Don't" icon="x">
    * Blurry or dark images
    * Glare covering text
    * Cropped or partial
    * Tampered documents
  </Card>
</CardGroup>

***

## Validation Process

### Multi-Layer Verification

The system uses multiple validation layers:

<AccordionGroup>
  <Accordion title="1. OpenAI Vision" icon="eye">
    * Validates document authenticity
    * Checks for photo presence
    * Verifies official document look
    * Detects obvious tampering
  </Accordion>

  <Accordion title="2. OCR Extraction" icon="scan">
    * Extracts text using Tesseract
    * Parses ID number, name, dates
    * Calculates confidence scores
    * Detects low-quality images
  </Accordion>

  <Accordion title="3. Cross-Validation" icon="code-compare">
    * Compares front and back data
    * Verifies name consistency
    * Checks dates match
    * Flags mismatches
  </Accordion>
</AccordionGroup>

### Extracted Fields

For Sierra Leone National ID:

| Field           | Source | Example           |
| --------------- | ------ | ----------------- |
| NIN (ID Number) | Front  | `SL-NIN-12345678` |
| Full Name       | Front  | `John Doe Smith`  |
| Date of Birth   | Front  | `1990-05-15`      |
| Gender          | Front  | `Male`            |
| Date of Expiry  | Back   | `2028-03-20`      |

***

## Fraud Detection

The system automatically detects:

<Warning>
  Fraudulent documents are flagged and may result in account suspension.
</Warning>

| Indicator            | Detection Method                            |
| -------------------- | ------------------------------------------- |
| Tampered text        | OCR confidence analysis                     |
| Missing headers      | Pattern matching for official text          |
| Suspicious patterns  | Keywords like "sample", "test", "photoshop" |
| Repeating ID numbers | Pattern detection (e.g., 11111111)          |
| Front/back mismatch  | Cross-validation of names/numbers           |
| Low image quality    | Confidence score thresholds                 |

### Fraud Response Example

```json theme={null}
{
  "valid": false,
  "fraudDetected": true,
  "fraudIndicators": [
    "OCR confidence below threshold (45%)",
    "Missing official header text",
    "ID number contains repeating pattern"
  ]
}
```

***

## API Integration

For third-party integrations that need to submit KYC documents:

### Upload Single Image

```bash theme={null}
curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/:id/kyc/upload" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_type": "id_front",
    "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }'
```

### Complete KYC Upgrade

```bash theme={null}
curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/:id/kyc/upgrade" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target_level": "enhanced",
    "id_front": "data:image/jpeg;base64,/9j/...",
    "id_back": "data:image/jpeg;base64,/9j/..."
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "previous_level": "basic",
  "new_level": "enhanced",
  "subscriber_id": "sub_abc123",
  "validation": {
    "front": { "valid": true, "confidence": 0.95 },
    "back": { "valid": true, "confidence": 0.92 },
    "crossValidation": { "consistent": true }
  }
}
```

***

## Troubleshooting

### "Image validation failed"

| Cause         | Solution                            |
| ------------- | ----------------------------------- |
| Blurry image  | Ask user to retake in good lighting |
| Glare on card | Tilt card to avoid reflections      |
| Partial image | Ensure entire document is visible   |
| Wrong format  | Convert to JPEG or PNG              |

### "Documents don't match"

* Front and back should be same document
* Names should match exactly
* Dates should be consistent

### "OCR confidence too low"

* Image may be too dark or have shadows
* Text may be obscured or damaged
* Ask for better quality photo

***

## Related

<CardGroup cols={2}>
  <Card title="KYC Validation Technical" icon="code" href="/agent-ts/kyc-validation">
    Technical OCR and validation details
  </Card>

  <Card title="Compliance API" icon="scale-balanced" href="/api-reference/compliance/overview">
    Compliance monitoring endpoints
  </Card>
</CardGroup>