Quickstart

Issue your first policy

In three calls you go from picking a plan to a live policy and a webhook event in your handler.

Pierflow keeps the workflow simple: quote → enroll → observe. Every response carries inline AI signals, so you don't need a second pipeline to assess risk.

1. Quote#

POST/v1/quotes

Provide the member's profile and Pierflow returns a ranked array of plans across every HMO you're permitted to distribute.

quote.ts

const quote = await pf.quotes.create({
  member: { age: 28, state: 'Lagos' },
  audience: 'individual',
  budget_ngn: 120000,
});

console.log(quote.packages[0]);
// { plan: {...}, pricing: {...}, value_score: 82, coverage_score: 78 }

2. Enroll#

POST/v1/enrollments

Pass the chosen plan_id with the member's identity document (BVN or NIN). The response includes fraud_score and identity_confidence inline.

enroll.ts

const policy = await pf.enrollments.create({
  hmo_id: 'pf_hmo_clearline',
  plan_id: quote.packages[0].plan.plan_id,
  member: {
    first_name: 'Amaka',
    last_name: 'Okeke',
    date_of_birth: '1997-09-12',
    bvn: '22********1',
  },
}, { idempotencyKey: 'enrl_2026_amaka_silver' });

// → { policy_id, fraud_score: 4, identity_confidence: 0.97, effective_date }

Always set an idempotency key

Network blips and client retries are inevitable. With an idempotency key, the second request returns the original response — no double enrollments.

3. Observe webhooks#

Configure a webhook endpoint in the developer portal. Within seconds of the enrollment succeeding, you'll receive policy.issued and premium.paid events.

webhook-handler.ts

app.post('/webhooks/pierflow', (req, res) => {
  pf.webhooks.verify(req.body, req.headers['x-pierflow-signature']);

  const event = req.body;
  switch (event.type) {
    case 'policy.issued':
      // update your DB, notify the user
      break;
    case 'claim.approved':
      // disburse, render in the app
      break;
  }
  res.sendStatus(200);
});