Consumer Management Guide

This guide explains how to manage consumer identities across all insurance products. Getting this right is the single most important implementation decision — it determines whether your customers get a seamless returning-customer experience and whether your policy history is accurate.

---

What a Consumer Is

A consumer is a persistent identity record in the AIMS system that links all insurance policies across all products. One person = one consumer record = one consumer_id, forever.

When a customer buys motor insurance, health insurance, and then device warranty through your platform, all three policies link to the same consumer ID. Your dashboard shows their full history. Their next purchase skips registration entirely.

---

The Correct Integration Pattern

First Purchase

1. Call prfl entity → receive consumer_id → store in your database
2. Use consumer_id to get a quote (SR10)
3. Use consumer_id to issue the policy (SR15)
4. Poll for status (SR20)

Store the consumer_id mapped to your own customer/user identifier. This is the only value you need to retain from the registration response.

# Step 1: Register the consumer
curl -X POST https://octamile-api.azurewebsites.net \
  -H "Content-Type: application/json" \
  -d '{
    "userInfo": {
      "id": "YOUR_PARTNER_ID",
      "athrzt": { "id": "YOUR_AUTH_ID", "key": "YOUR_AUTH_KEY" }
    },
    "cmmnd": {
      "cmmnd": "prfl entity",
      "seed": {
        "class": "individual",
        "name": { "first": "Adaeze", "last": "Nwosu" },
        "dob": { "date": "1995-03-08" },
        "gender": "f",
        "phoneNo": "+2348051234567",
        "eMail": "adaeze.nwosu@email.com",
        "addrss": { "addrss": "12 Victoria Island, Lagos" }
      }
    }
  }'

Response:

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "id": "a1b2c3d4e5f67890abcdef1234567890",
  "id_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

id is a 32-character hex string (no hyphens). id_uuid is the same value in standard UUID format — both forms are accepted in the entt_ command. Store either as consumer_id. Do not call prfl entity again for this customer.

---

Returning Purchase

1. Look up consumer_id in your database (no API call needed)
2. Use consumer_id to get a quote (SR10)
3. Use consumer_id to issue the policy (SR15)
4. Poll for status (SR20)

// Pseudocode
async function issuePolicy(userId, product, policyDetails) {
  // Look up your own database first
  let consumerId = await db.getConsumerId(userId);

  if (!consumerId) {
    // First time: register the consumer
    const customer = await db.getCustomer(userId);
    const reg = await aimsApi.registerConsumer(customer);
    consumerId = reg.id;
    await db.saveConsumerId(userId, consumerId); // Save it
  }

  // Go straight to quote and issue
  const quote = await aimsApi.getQuote(product, policyDetails);
  const policy = await aimsApi.issuePolicy(consumerId, product, policyDetails);
  return policy;
}

---

What to Store

Store exactly one value from the registration response:

Value	Where to store it	Why
id (the consumer_id)	Your own database, mapped to your user/customer ID	Required for all future policy purchases

Nothing else from the registration response needs to be persisted. The AIMS system holds the consumer's KYC data — you only need the ID to reference it.

---

Idempotency Safety Net

prfl entity is idempotent by email. If you call it again with the same email address under the same partner account, the API returns the existing consumer's ID rather than creating a new record.

This is a safety net for edge cases (e.g., your database lost the consumer ID due to a bug or migration). It is not a reason to skip storing the consumer ID.

Relying on idempotency as your primary lookup strategy adds an unnecessary API call to every purchase flow and makes your code dependent on the customer always providing the same email address.

Correct use of idempotency: Recovery when your own consumer ID record is missing.

Incorrect use: Calling prfl entity on every checkout instead of checking your database first.

---

❌ The Anti-Pattern

Calling prfl entity on every checkout, even for returning customers, is the most common integration mistake.

What happens:

	Wrong pattern	Correct pattern
Customer buys motor policy	Calls prfl entity → creates consumer record A	Calls prfl entity → creates consumer record A, stores ID
Same customer buys health policy 3 months later	Calls prfl entity again → creates consumer record B	Uses stored ID for consumer record A directly
Same customer buys device warranty	Calls prfl entity again → creates consumer record C	Uses stored ID for consumer record A directly
Your dashboard	Shows 3 consumers, each with 1 policy	Shows 1 consumer with 3 policies
Policy history	Broken — policies are not linked	Complete — full lifetime history visible
Customer experience	Re-collects KYC on every purchase	Skips registration on repeat purchases

---

Cross-Product Reuse

The same consumer_id works across all insurance products. A customer registered for device warranty can buy motor insurance, health insurance, and goods-in-transit cover — all using the same consumer_id. No re-registration, no new KYC, no additional API calls.

# Device warranty — consumer registered here
curl ... "cmmnd": "entt_a1b2c3d4-...: insure", "seed": { "ctgry": "phnn", ... }

# Motor insurance 6 months later — same consumer_id, no re-registration
curl ... "cmmnd": "entt_a1b2c3d4-...: insure", "seed": { "ctgry": "vhcl", ... }

# Health insurance — same consumer_id again
curl ... "cmmnd": "entt_a1b2c3d4-...: insure", "seed": { "ctgry": "hlth", ... }

---

Example Consumer Lifecycle

Month 0  — Customer applies for a loan on your platform
           → prfl entity called → consumer_id saved to your DB

Month 0  — Loan repayment guarantee issued alongside the loan
           → entt_{consumer_id}: insure (lrgg)

Month 3  — Same customer buys a car through your platform
           → consumer_id retrieved from your DB (no API call)
           → entt_{consumer_id}: insure (vhcl-cmpr)

Month 9  — Customer renews motor policy
           → consumer_id retrieved from your DB (no API call)
           → entt_{consumer_id}: insure (vhcl-cmpr)

Month 12 — Customer opens health cover for family
           → consumer_id retrieved from your DB (no API call)
           → entt_{consumer_id}: insure (hlth-axam)

Your dashboard shows one consumer with four linked policies across three product categories. Octamile can calculate lifetime value, cross-product coverage gaps, and renewal opportunities — all from a single consumer ID that you registered once.

---

Consumer Registration Reference

Credential requirement: Use the same API credentials (userInfo.id + userInfo.athrzt) for SR05 (consumer registration) and SR15 (policy issuance). Consumer records are scoped to your partner account — an ID returned under one set of credentials is not valid under another.

Seed field	Type	Required	Description
class	string	Yes	"individual" or "organization" (also accepted: "h" for individual, "o" for organisation)
name.first	string	Yes	First name
name.last	string	Yes	Last name
name.middle	string	No	Middle name
dob.date	string	No	Date of birth — YYYY-MM-DD format
gender	string	No	"m" or "f"
phoneNo	string	Required for individuals	Phone number in international format — +2348012345678. Must start with + and country code.
eMail	string	No	Email address — used for idempotency lookup
addrss.addrss	string	No	Contact address
ntnlty	string	No	Nationality (e.g., "Nigerian")
stateOfOrigin	string	No	State of origin
mrtlStatus	string	No	Marital status: "single", "married", "divorced", "widowed"
socialID.type	string	No	ID type: "nidd" (NIN), "dlcn" (driver's licence), "ipss" (passport), "vcrd" (voter's card), "bvnn" (BVN)
socialID.id	string	No	ID number
socialID.image	string	No	Base64-encoded ID document scan

Response:

{
  "exctnFdbck": { "id": 75, "id_v4": 200 },
  "id": "a1b2c3d4e5f67890abcdef1234567890"
}

The id field is the consumer_id. Store it immediately.

---

See Also

• Quickstart Guide — full 4-step integration walkthrough
• API Overview — authentication and command structure