# Runbook — insurer onboarding

Adding a new insurance carrier to InsureLink. Owner: ZFA operations.

## Prerequisites

- IRA licence copy (PDF).
- Insurer's authorised contact + escalation contact.
- Commission schedule signed by both parties.
- Integration mode confirmed: `manual`, `email`, `sftp`, or `api`.

## Steps

1. **Create the insurer record**
   ```http
   POST /api/v1/insurers
   ```
   Body includes `name`, `tradingName`, `iraLicenceNumber`, `website`,
   `taxPin`, `physicalAddress`. Response returns the public code — share
   this with the insurer's contact when they need to be referenced.

2. **Add primary contact + escalation**
   ```http
   POST /api/v1/insurers/{id}/contacts
   ```
   Send two calls — role `primary` and role `escalation`.

3. **Set integration settings**
   ```http
   POST /api/v1/insurers/{id}/integration-settings
   ```
   `mode: api` requires `webhookUrl` + `webhookSecret` — the secret is
   HMAC-verified on every outbound quotation request. `mode: email`
   requires the destination inbox; ZFA MTA-relays outbound quotation
   requests as MIME + JSON attachment.

4. **Create products & plans**
   - For each product line: `POST /api/v1/products` with `insurerId`
     + `productCategoryId`.
   - For each plan/tier: `POST /api/v1/products/{id}/plans`.
   - Attach `productRequiredDocuments` for anything the insurer expects
     alongside a referral (e.g., DL for motor, medical questionnaire
     for life). Plans can override product-level required documents.

5. **Register commission rules**
   ```http
   POST /api/v1/commission-rules
   ```
   Rules are versioned — set `effectiveFrom` to the contract start date
   and leave `effectiveTo` null. Superseding a rule is a *new insert* with
   a later `effectiveFrom`, not an update.

6. **Verification flag flip**
   - New insurers start with `verificationRequired: true`. Set to false
     via `POST /api/v1/insurers/{id}/verify` only after: licence copy is
     archived in `Document`, integration test call succeeds, first live
     referral is E2E-tested.

7. **Communicate**
   - Send the primary contact the API-key issuance flow docs
     (if `mode: api`) — key issued via `/api/v1/api-keys` scoped to
     `referral:read`, `product:read` at minimum.

## Rollback

- If onboarding is cancelled before go-live, delete in the reverse
  order: commission rules → plans → products → integration settings →
  contacts → insurer. All are soft-deleted (`deletedAt`), never
  hard-deleted, so audit + regulator reports remain valid.