# Runbook — agent onboarding & approval

Handling self-registered agent applications. Owner: ZFA agency
management + compliance.

## Applicant types

| Type | IRA licence required | Sponsor required |
| --- | --- | --- |
| `licensed` | Yes (attach `AgentLicense` doc). | No. |
| `introducer` | No — but MUST be attached to a licensed sponsor. | Yes. |

Both must submit National ID (NIN + document copy) — mandatory for KYC.

## Steps

1. **Applicant self-registers** via `POST /api/v1/agents/register`. Row lands
   with `kycStatus: 'pending'` and `selfRegistered: true`. No InsureLink
   agency number is issued yet.

2. **Compliance reviews KYC documents.**
   - Fetch: `GET /api/v1/agents/{id}` — expand `documents`.
   - Verify NIN document, licence (if licensed), sponsor letter (if
     introducer).
   - Reject: `POST /api/v1/agents/{id}/reject` with a reason. Applicant is
     notified via their preferred channel (email/SMS/WhatsApp).

3. **Sponsor invariant (introducers only).**
   The sponsor UUID or public code must resolve to an ACTIVE licensed
   agent. If the sponsor is inactive/suspended, applicant is
   auto-rejected with `SPONSOR_INVALID`. Applicant may re-submit with a
   different sponsor.

4. **Approve.** `POST /api/v1/agents/{id}/approve`. This:
   - Issues an InsureLink agency number (auto-generated `AGT-XX-XXXXXXXXXX`).
   - Flips `kycStatus` to `verified` and sets `kycExpiresAt` = 12 months
     from now (IRA re-verification cadence).
   - Issues a subscription record (default `SubscriptionPlan`, prorated).
   - Fires the welcome notification with credentials.

5. **IRA registration number** (licensed only): captured on the licence
   record + mirrored to `Agent.iraRegistrationNumber` so it appears on
   the profile. Update via `POST /api/v1/agents/{id}/licenses`.

## KYC expiry

- A scheduled job flags agents with `kycExpiresAt < now + 30d` and
  notifies them. On expiry, `kycStatus` transitions to `expired` and the
  agent is blocked from creating new referrals (existing referrals /
  commissions are untouched).
- Re-verification is a fresh document submission + compliance re-review.
  Use the same `/approve` endpoint after review.

## Suspend / reinstate

- Suspend: `POST /api/v1/agents/{id}/suspend` — captures reason, revokes
  API keys, keeps historical records.
- Reinstate: `POST /api/v1/agents/{id}/reinstate`. Introducers sponsored
  by a suspended agent are NOT auto-suspended; re-verify their sponsor
  invariant manually.