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

# Subscriber Registration

> Complete guide to registering OLIVE subscribers

# Subscriber Registration Guide

This guide covers the complete subscriber registration flow, including KYC requirements and error handling.

## Registration Flow

```mermaid theme={null}
flowchart LR
    REG[Register] --> BASIC[Basic KYC]
    BASIC --> ACTIVE[Active Account]
    ACTIVE --> ENHANCED[Enhanced KYC]
    ENHANCED --> FULL[Full KYC]
```

## Quick Registration

### Public Endpoint (No Auth)

```bash theme={null}
curl -X POST https://demo.api.vultlocal.com/api/v1/public/subscribers \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0771234567",
    "first_name": "John",
    "last_name": "Doe",
    "pin": "1234"
  }'
```

### Authenticated Endpoint

```bash theme={null}
curl -X POST https://demo.api.vultlocal.com/api/v1/subscribers \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "0771234567",
    "first_name": "John",
    "last_name": "Doe",
    "pin": "1234"
  }'
```

## Required Fields

| Field          | Type   | Validation                               |
| -------------- | ------ | ---------------------------------------- |
| `phone_number` | string | Sierra Leone format, 8 digits after +232 |
| `first_name`   | string | 1-100 characters                         |
| `last_name`    | string | 1-100 characters                         |
| `pin`          | string | 4 digits                                 |

## KYC Levels

### Basic (Default)

* Phone verification
* Name and PIN
* **Limits**: Daily 100,000 SLE, Monthly 500,000 SLE

### Enhanced

* ID document upload via Agent
* OCR validation
* **Limits**: Daily 500,000 SLE, Monthly 2,000,000 SLE

### Full

* Front + back ID verification
* Cross-validation passed
* **Limits**: Daily 2,000,000 SLE, Monthly 10,000,000 SLE

## KYC Upgrade via WhatsApp

Users can upgrade KYC through the WhatsApp agent:

1. **User**: "I want to upgrade my account"
2. **Agent**: "Please send a clear photo of the FRONT of your Sierra Leone National ID"
3. **User**: \[Sends front image]
4. **Agent**: "Front received. Now send the BACK of your ID"
5. **User**: \[Sends back image]
6. **Agent**: "Your KYC upgrade is complete!"

## Error Handling

| Error                      | Cause                      | Solution                  |
| -------------------------- | -------------------------- | ------------------------- |
| `PHONE_ALREADY_REGISTERED` | Phone exists               | User should login instead |
| `INVALID_PHONE_FORMAT`     | Wrong format               | Use Sierra Leone format   |
| `WEAK_PIN`                 | Sequential/repeated digits | Choose stronger PIN       |

## Phone Number Format

Valid Sierra Leone formats:

```
+23279123456   (E.164)
079123456      (local)
23279123456    (without +)
```

All are normalized to `+23279123456`.

## Best Practices

<AccordionGroup>
  <Accordion title="Customer Communication">
    Send welcome SMS after successful registration with basic instructions.
  </Accordion>

  <Accordion title="PIN Security">
    Never store or log PINs in plaintext. Hash before storage.
  </Accordion>

  <Accordion title="KYC Guidance">
    Prompt users to complete Enhanced KYC for higher limits.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="KYC Upgrade" icon="id-card" href="/guides/kyc-upgrade">
    Document validation details
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/subscribers/register">
    Registration endpoint details
  </Card>
</CardGroup>