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

# Subscribers

> Manage subscriber accounts, KYC, and profile information

<Info>
  Subscribers are the end-users of the OLIVE platform. Each subscriber has a wallet, can link NFC cards, and perform transactions.
</Info>

## Quick Start

<Steps>
  <Step title="Register Subscriber">
    Create account with phone number and PIN
  </Step>

  <Step title="Link Card">
    Associate NFC card for payments
  </Step>

  <Step title="Upgrade KYC">
    Submit documents for higher limits
  </Step>

  <Step title="Transact">
    P2P transfers, POS payments, cash-in/out
  </Step>
</Steps>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Register" icon="user-plus" href="/api-reference/subscribers/register">
    `POST /api/v1/subscribers`

    Create new subscriber account
  </Card>

  <Card title="Get Subscriber" icon="user" href="/api-reference/subscribers/get">
    `GET /api/v1/subscribers/{id}`

    Retrieve subscriber by ID
  </Card>

  <Card title="Lookup" icon="search" href="/api-reference/subscribers/lookup">
    `GET /api/v1/subscribers/lookup`

    Find subscriber by phone number
  </Card>

  <Card title="List" icon="users" href="/api-reference/subscribers/list">
    `GET /api/v1/subscribers`

    List all subscribers with filters
  </Card>

  <Card title="Update" icon="user-pen" href="/api-reference/subscribers/update">
    `PUT /api/v1/subscribers/{id}`

    Update profile and KYC info
  </Card>

  <Card title="Block" icon="ban" href="/api-reference/subscribers/block">
    `POST /api/v1/subscribers/{id}/block`

    Block subscriber account
  </Card>

  <Card title="Unblock" icon="check-circle" href="/api-reference/subscribers/unblock">
    `POST /api/v1/subscribers/{id}/unblock`

    Restore blocked account
  </Card>

  <Card title="Verify PIN" icon="lock-keyhole" href="/api-reference/subscribers/verify-pin">
    `POST /api/v1/subscribers/{id}/verify-pin`

    Verify subscriber's PIN
  </Card>

  <Card title="Change PIN" icon="key" href="/api-reference/subscribers/change-pin">
    `POST /api/v1/subscribers/{id}/change-pin`

    Change subscriber's PIN
  </Card>

  <Card title="Cards" icon="credit-card" href="/api-reference/subscribers/cards">
    `GET /api/v1/subscribers/{id}/cards`

    List linked NFC cards
  </Card>
</CardGroup>

***

## Subscriber Object

```json theme={null}
{
  "id": "sub_abc123",
  "phone_number": "+23279123456",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "date_of_birth": "1990-05-15",
  "address": "123 Main Street, Freetown",
  "kyc_level": 2,
  "status": "ACTIVE",
  "balance": "125,000.00 SLE",
  "id_number": "SL12345678",
  "id_type": "NATIONAL_ID",
  "vult_wallet_id": "vult_xyz789",
  "cards_count": 2,
  "max_child_cards": 4,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:45:00Z"
}
```

***

## Account Status

<CardGroup cols={3}>
  <Card title="Active" icon="circle-check" color="#10b981">
    Full access to all features
  </Card>

  <Card title="Pending" icon="clock" color="#f59e0b">
    Awaiting KYC verification
  </Card>

  <Card title="Blocked" icon="ban" color="#ef4444">
    Account suspended, no transactions
  </Card>
</CardGroup>

***

## KYC Levels

| Level | Max Balance    | Daily Limit   | Monthly Limit  | Requirements    |
| ----- | -------------- | ------------- | -------------- | --------------- |
| **1** | 500,000 SLE    | 100,000 SLE   | 1,000,000 SLE  | Phone + PIN     |
| **2** | 2,000,000 SLE  | 500,000 SLE   | 5,000,000 SLE  | + ID Document   |
| **3** | 10,000,000 SLE | 2,000,000 SLE | 20,000,000 SLE | + Address Proof |

<Info>
  KYC upgrades require document verification and may take 1-2 business days.
</Info>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="Register New Subscriber" icon="user-plus">
    1. Call `POST /api/v1/subscribers` with phone, name, and PIN
    2. Subscriber receives WhatsApp welcome message
    3. Link an NFC card via `POST /api/v1/cards/link`
    4. Subscriber can now receive funds and make payments
  </Accordion>

  <Accordion title="Upgrade KYC Level" icon="arrow-up">
    1. Collect ID document and selfie from subscriber
    2. Upload documents to storage
    3. Call `PUT /api/v1/subscribers/{id}` with document URLs and KYC level
    4. System verifies documents (OCR + face match)
    5. If approved, limits are automatically increased
  </Accordion>

  <Accordion title="Handle Blocked Account" icon="shield">
    1. Check block reason in subscriber details
    2. Investigate any associated compliance alerts
    3. If resolved, call `POST /api/v1/subscribers/{id}/unblock`
    4. All cards are automatically reactivated
  </Accordion>

  <Accordion title="Password Reset (PIN Change)" icon="key">
    1. Verify subscriber identity through support channel
    2. Admin calls `POST /api/v1/subscribers/{id}/change-pin`
    3. Subscriber receives new PIN via WhatsApp
    4. Subscriber should change PIN on first use
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Cards" icon="credit-card" href="/api-reference/cards/link">
    Link and manage NFC cards
  </Card>

  <Card title="Wallet" icon="wallet" href="/api-reference/wallet/balance">
    Balance and transactions
  </Card>
</CardGroup>