List published products.

When to use: Render product menus, landing pages, and assisted sales lists.

curl "https://api.capitalexpressassurance.com/v1/products?segment=personal" \
  -H "x-api-key: capex_live_YOUR_KEY"

{
  "ok": true,
  "data": [
    { "code": "TSP", "name": "Target Savings Plan", "segment": "personal", "category": "savings" },
    { "code": "CEP", "name": "Capital Endowment Plan", "segment": "personal", "category": "savings" },
    { "code": "F3P", "name": "Flexi 3 Plan", "segment": "personal", "category": "savings" },
    { "code": "3PP", "name": "3-Premium Plan", "segment": "personal", "category": "savings" }
  ],
  "error": null,
  "meta": { "source": "gateway_catalog" }
}

Fetch one product by code or slug.

When to use: Product detail pages and assisted sales walkthroughs.

Return the raw rate table for a product.

When to use: Internal tooling, underwriting review, and rate auditing.

Return available term lengths, age ranges, and premium frequencies for a product.

When to use: Populate form dropdowns before a customer enters their details.

{
  "ok": true,
  "data": {
    "productCode": "CEP",
    "minEntryAge": 1, "maxEntryAge": 60,
    "termOptions": [5, 7, 10, 15, 20],
    "frequencies": ["monthly", "quarterly", "halfyearly", "annually", "single"]
  }
}

Bidirectional premium/sum-assured calculator. Provide sumAssured to get premium, or premium to get sumAssured.

When to use: Live quotation widgets, affordability explorers, and pre-quote pricing.

curl -X POST "https://api.capitalexpressassurance.com/v1/products/CEP/estimate" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "age": 35,
    "termYears": 10,
    "frequency": "monthly",
    "sumAssured": 1000000
  }'

{
  "ok": true,
  "data": {
    "productCode": "CEP",
    "age": 35,
    "termYears": 10,
    "frequency": "monthly",
    "sumAssured": 1000000,
    "premium": 7153.49,
    "rate": 7.15348962
  }
}

Resolve a customer across Supabase and IES using client code, email, or phone.

When to use: Before loading account overview, virtual-account readiness, claims, or policy operations.

curl -X POST "https://api.capitalexpressassurance.com/v1/customers/resolve" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "email": "customer@example.com",
    "phone": "08030000000"
  }'

{
  "ok": true,
  "data": {
    "customer": {
      "client_code": "240103735",
      "email": "customer@example.com",
      "phone": "08030000000",
      "first_name": "Amina",
      "last_name": "Bello"
    }
  },
  "error": null,
  "meta": { "source": "supabase+ies" }
}

List customers matching a search query.

When to use: Internal search in Clara, staff portals, and operations tooling.

Register a new customer. Returns the existing record if the email is already known (idempotent).

When to use: When a customer has completed an onboarding form and you want to persist their record.

curl -X POST "https://api.capitalexpressassurance.com/v1/customers" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "firstName": "Amina",
    "lastName": "Bello",
    "email": "amina@example.com",
    "phone": "08030000000"
  }'

Fetch a known customer using an already-resolved unified client code.

When to use: Internal or reconciled journeys where the client code is already clean.

Fetch a customer by client code, falling back to IES if not in local storage.

When to use: Profile pages, account context, and customer support lookups.

Update one or more profile fields for a customer by client code.

When to use: Profile edit flows, address updates, and contact detail corrections.

List policies linked to this customer, fetched live from the insurance core.

When to use: Policy summary screens and customer dashboards.

List virtual accounts assigned to this customer.

List KYC and identity documents uploaded for this customer.

Generate a new quote using the product catalog and IES quote engine.

When to use: After product selection and enough customer data has been collected to price the plan.

curl -X POST "https://api.capitalexpressassurance.com/v1/quotes" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -H "x-request-id: req_01hwxyz" \
  -H "x-idempotency-key: quote_idem_001" \
  -d '{
    "productCode": "TSP",
    "dob": "1990-06-18",
    "gender": "Male",
    "amount": 15000,
    "frequency": "monthly",
    "term": "10",
    "email": "amina@example.com",
    "phone": "08030000000",
    "firstName": "Amina",
    "lastName": "Bello"
  }'

{
  "ok": true,
  "data": {
    "quoteNo": "Q260000542",
    "productCode": "TSP",
    "premium": 15000,
    "frequency": "monthly",
    "sumAssured": 2100000,
    "term": "10",
    "status": "generated",
    "provider": "IES"
  },
  "error": null,
  "meta": { "requestId": "req_01hwxyz", "source": "gateway" }
}

Retrieve one quote by quote number.

When to use: During checkout handoff, back-office review, and payment verification follow-up.

Update a quote's premium amount, term, or frequency and trigger an IES recalculation.

When to use: When a customer wants to adjust their plan details before proceeding to payment.

Mark a quote as converted to a policy (idempotent — safe to call multiple times).

When to use: After the customer has signed and payment has been confirmed.

List policies for a resolved customer.

When to use: Dashboards, account overview, and policy servicing menus.

Fetch a single policy summary.

When to use: Policy detail screens and customer support review.

Read the full policy statement from the insurance core.

When to use: Premium history, contribution records, and formal account history requests.

List gateway payment transactions recorded against this policy.

When to use: Payment history tab, premium tracking, and collections review.

Fetch beneficiaries stored on this policy from the insurance core.

Replace beneficiary data for a policy. Percentages must sum to 100.

When to use: During life events — marriage, birth, change of estate plan.

Submit a policy surrender request for review by the operations team.

When to use: Customer wishes to terminate the policy early and recover any surrender value.

Submit a policy reinstatement request for review.

When to use: Customer wants to resume a lapsed policy and continue premium payments.

Submit a policy loan request for review.

When to use: Customer wants to borrow against accumulated policy value.

Start a live payment checkout through Squad using policy or quote context.

When to use: When a customer chooses to pay online instead of by transfer or recurring authorization.

curl -X POST "https://api.capitalexpressassurance.com/v1/payments/checkout" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -H "x-idempotency-key: checkout_idem_001" \
  -d '{
    "email": "amina@example.com",
    "amount": 15000,
    "quoteNo": "Q260000542"
  }'

{
  "ok": true,
  "data": {
    "checkoutUrl": "https://pay.squadco.com/checkout/abc123",
    "transactionRef": "CAPEX-1716453623-AB12C",
    "amount": 15000,
    "currency": "NGN"
  }
}

Verify a transaction reference and update settlement state.

When to use: After customer redirection, support follow-up, or reconciliation retries.

curl -X POST "https://api.capitalexpressassurance.com/v1/payments/verify" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{ "transactionRef": "CAPEX-1716453623-AB12C" }'

Fetch one payment transaction by reference.

When to use: Exact follow-up on a single payment event during support or reconciliation.

Get a structured receipt for a completed payment.

When to use: When a customer or agent requests a formal payment confirmation.

Request a refund for a completed payment (queued for manual review).

When to use: Policy cancellation, duplicate charge, or customer dispute resolution.

List claims by customer, status, or policy.

When to use: Account history, claims dashboard, and Clara account support flows.

Create a new claim workspace.

When to use: When a claim journey begins and you want structured internal handling from the start.

curl -X POST "https://api.capitalexpressassurance.com/v1/claims" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "policyNumber": "LIF/00012345",
    "productName": "Target Savings Plan",
    "claimType": "maturity",
    "clientCode": "240103735"
  }'

Fetch a single claim with enriched IES policy data.

Edit a draft claim workspace before submission.

When to use: Customer is correcting information before formally submitting the claim.

Update claim status directly. Used for staff-level transitions during the review workflow.

When to use: Operations staff moving claims between review stages.

Submit a draft claim for review. Transitions status from draft to submitted_initial.

When to use: Customer has confirmed all details and is ready to formally file.

Assign a submitted claim to a claims handler and move it to ready_for_review.

When to use: Internal claims operations — triage and routing step.

Approve a claim and notify the customer via email.

When to use: Claims handler has completed investigation and is ready to approve.

Reject a claim and notify the customer with a reason.

When to use: Claims handler has reviewed and determined the claim cannot be paid.

Attach a document to a claim workspace.

When to use: Customer uploads supporting evidence (death certificate, medical report, etc.).

Fetch the full event timeline for a claim — creation, submission, assignment, and resolution.

When to use: Customer support review, compliance audit, and claims analytics.

{
  "ok": true,
  "data": [
    { "event": "created", "at": "2026-05-01T09:00:00Z", "actor": "customer" },
    { "event": "submitted", "at": "2026-05-01T09:15:00Z", "actor": "customer" },
    { "event": "assigned", "at": "2026-05-02T10:00:00Z", "actor": "staff:handler_01" },
    { "event": "approved", "at": "2026-05-07T14:30:00Z", "actor": "staff:handler_01" }
  ]
}

Return the KYC verification status for a customer: BVN verified, NIN verified, and document count.

When to use: Onboarding progress screens and pre-issuance readiness checks.

{
  "ok": true,
  "data": {
    "clientCode": "240103735",
    "bvnVerified": true,
    "ninVerified": false,
    "documentCount": 2,
    "readyForIssuance": true
  }
}

Start the BVN consent flow through Mono.

When to use: When a user is ready to verify identity with a real OTP challenge.

curl -X POST "https://api.capitalexpressassurance.com/v1/kyc/bvn/initiate" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "bvn": "22200000000",
    "customer_identifier": "amina@example.com"
  }'

{
  "ok": true,
  "data": {
    "sessionId": "mono_bvn_session_abc123",
    "methods": ["phone", "email"],
    "expiresAt": "2026-05-26T10:30:00Z"
  }
}

Select the OTP delivery method for the BVN consent flow.

When to use: After initiation, when the user chooses phone, email, or alternate phone.

Complete the BVN flow with the OTP and persist verified identity to the customer profile.

When to use: After the user supplies the OTP received on their chosen channel.

Look up BVN details using a previously verified session without re-initiating the flow.

When to use: When the BVN has already been verified and you need to retrieve the identity payload.

Verify NIN and optionally persist it to the matched customer profile.

When to use: When NIN is the chosen identity path or an additional trust check is needed.

Save a medical declaration for a customer.

When to use: During onboarding when product underwriting requires health disclosures.

Save beneficiary information for a customer profile. Percentages must sum to 100.

Get stored beneficiaries for a customer.

List uploaded KYC documents for a customer.

Upload a KYC document for a customer.

When to use: Government ID, passport, utility bill, or other KYC document submission.

curl -X POST "https://api.capitalexpressassurance.com/v1/kyc/documents/upload" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "clientCode": "240103735",
    "documentType": "national_id",
    "fileName": "nin_slip.jpg",
    "fileData": "BASE64_ENCODED_FILE_CONTENT"
  }'

{
  "ok": true,
  "data": {
    "documentId": "doc_01hwxyz",
    "documentType": "national_id",
    "fileName": "nin_slip.jpg",
    "storagePath": "customer-documents/240103735/nin_slip.jpg",
    "uploadedAt": "2026-05-26T09:00:00Z"
  }
}

Check virtual-account readiness or look up an existing account for a customer.

When to use: Before creating a new virtual account so the gateway can choose the best path.

Resolve an existing virtual account or attempt dedicated issuance through Squad.

When to use: Real collections journeys where the gateway should own the decision between existing, dedicated, and fallback modes.

Receive Squad payment events and trigger gateway-side reconciliation and IES autopost.

When to use: Set this as the public webhook target URL in your Squad merchant dashboard.

Receive Mono identity and BVN webhook events.

When to use: Set this as the Mono webhook receiver for your integration.

List all registered webhook endpoints for the calling API client.

{
  "ok": true,
  "data": [
    {
      "id": "ep_01hwxyz",
      "url": "https://yourserver.com/hooks/capex",
      "events": ["payment.completed", "claim.approved"],
      "is_active": true,
      "description": "Production event receiver",
      "created_at": "2026-05-01T09:00:00Z"
    }
  ]
}

Register a new HTTPS endpoint to receive gateway event deliveries.

When to use: Setting up your server to receive payment, claim, and policy lifecycle events.

curl -X POST "https://api.capitalexpressassurance.com/v1/webhooks/endpoints" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_YOUR_KEY" \
  -d '{
    "url": "https://yourserver.com/hooks/capex",
    "events": ["payment.completed", "claim.approved"],
    "description": "Production event receiver"
  }'

{
  "ok": true,
  "data": {
    "id": "ep_01hwxyz",
    "url": "https://yourserver.com/hooks/capex",
    "events": ["payment.completed", "claim.approved"],
    "is_active": true,
    "secret": "a1b2c3...",
    "secretWarning": "This signing secret is shown only once. Store it securely."
  }
}

Remove a registered webhook endpoint.

Send a test event delivery to a registered endpoint and record the result.

When to use: Verifying your server can receive and verify gateway signatures before going live.

Return gateway health status and timestamp.

When to use: Uptime checks, readiness probes, and smoke tests after deployment.

{
  "ok": true,
  "data": {
    "status": "ok",
    "timestamp": "2026-05-26T09:00:00Z",
    "version": "1.0.0"
  }
}

Ping all upstream providers (IES, Squad, Mono) and return reachability status.

When to use: Provider health dashboards and incident investigation.

{
  "ok": true,
  "data": {
    "squad": { "ok": true, "status": 200 },
    "ies": { "ok": true, "status": 200 },
    "mono": { "ok": true, "status": 200 },
    "checked_at": "2026-05-26T09:00:00Z"
  }
}

List all API clients for this account.

When to use: Audit access, review active integrations, and manage partner keys.

Create a new API client with scopes and access configuration.

When to use: Onboarding a new integration surface, partner, or internal tool.

curl -X POST "https://api.capitalexpressassurance.com/v1/admin/api-clients" \
  -H "content-type: application/json" \
  -H "x-api-key: capex_live_ADMIN_KEY" \
  -d '{
    "name": "Mobile App Production",
    "scopes": ["products:*", "customers:*", "quotes:*", "policies:*", "payments:*", "kyc:*"],
    "contactEmail": "dev@capitalexpressassurance.com",
    "rateLimitPerMinute": 120
  }'

{
  "ok": true,
  "data": {
    "id": "client_01hwxyz",
    "name": "Mobile App Production",
    "key_prefix": "capex_live_abc1",
    "api_key": "capex_live_abc1_FULL_KEY_SHOWN_ONCE",
    "scopes": ["products:*", "customers:*", "quotes:*", "policies:*", "payments:*", "kyc:*"],
    "status": "active"
  }
}

Update an API client's name, scopes, rate limits, or status.

Revoke an API client. Soft-deletes the record and immediately invalidates the key.

Explicitly revoke an API client by ID (POST alternative to DELETE).

Generate a new API key for a client. The old key is invalidated immediately. The new key is shown only once.

When to use: Scheduled rotation, suspected compromise, or staff offboarding.

{
  "ok": true,
  "data": {
    "id": "client_01hwxyz",
    "name": "Mobile App Production",
    "apiKey": "capex_live_xyz9_NEW_KEY_SHOWN_ONCE",
    "keyPrefix": "capex_live_xyz9",
    "rotatedAt": "2026-05-26T09:00:00Z",
    "warning": "This key is shown only once. Store it securely."
  }
}

List gateway API request logs with client, path, status code, and latency.

When to use: Request audit, debugging integration failures, and traffic analysis.

List provider call logs (IES, Squad, Mono) with outcome, latency, and request context.

When to use: Debugging integration failures, monitoring provider latency, and compliance review.

List idempotency keys tracked by the gateway for deduplication.

When to use: Debugging duplicate request issues and verifying retry safety.

Return reconciliation summary: record counts, orphaned records, and recent reconciliation runs.

When to use: Operations dashboards, data integrity audits, and end-of-day reconciliation checks.

{
  "ok": true,
  "data": {
    "profiles_total": 1024,
    "policies_missing_customer_profile_id": 0,
    "payments_missing_client_code": 3,
    "quote_applications_total": 248,
    "insurance_products_total": 6,
    "recent_runs": []
  }
}

Retry the IES autopost for a verified payment transaction that previously failed.

When to use: Manual reconciliation when Squad settled a payment but the IES autopost failed.