Skip to main content

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

    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

    POST /api/v1/insurers/{id}/contacts

    Send two calls — role primary and role escalation.

  3. Set integration settings

    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

    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.