Tutorial: Set Up a Family Member and Dependent Account

This guide walks through the end-to-end dependent-account setup flow for a retail primary account holder.

The tutorial starts with the required tenant and product setup, then covers the API flow to:

enable the dependent-account capability
create a savings product that allows dependent accounts
create the primary account
identify the retail primary client and eligible primary account
create a family member and create or link the family member's customer
create the dependent account
add or pull funds
issue a card for the dependent account

Before You Start

Make sure you have:

access to tenant configuration and savings-product APIs
an active retail primary client
an access token with permission to manage the primary client and primary account
a valid tenantId header

Use these placeholders in the examples below:

export BASE_URL="https://api.example.com"
export TENANT_ID="your-tenant-id"
export ACCESS_TOKEN="<access-token>"
export PRIMARY_CLIENT_ID="3"
export PRIMARY_PRODUCT_ID="1"
export PRIMARY_ACCOUNT_ID="168"
export CARD_PRODUCT_ID="1"

All API examples below use:

header tenantId: ${TENANT_ID}
header Authorization: Bearer ${ACCESS_TOKEN}
header Content-Type: application/json

Step 1: Enable Dependent-Account Global Configuration

Before using the dependent-account flow, enable the required global configuration in BackOffice.

Relevant configurations:

allow-dependent-account
dependent-min-age

Use your BackOffice global configuration setup to make sure the dependent-account feature is enabled for the tenant before continuing.

Step 2: Create or Update a Savings Product That Allows Dependent Accounts

Dependent accounts can be created only from an eligible primary savings account whose product allows dependent accounts.

Use the savings-product API to create or update the savings product and enable:

allowDependentAccount

Use the product in the primary account setup so the retail primary account holder has an active primary savings account backed by a savings product that allows dependent accounts.

POST /v1/savingsproducts

curl -sS -X POST "${BASE_URL}/v1/savingsproducts" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Dependent Account Product\",
    \"shortName\": \"DAP\",
    \"description\": \"Savings product for dependent accounts\",
    \"currencyCode\": \"USD\",
    \"digitsAfterDecimal\": 2,
    \"nominalAnnualInterestRate\": 0,
    \"interestCompoundingPeriodType\": 1,
    \"interestPostingPeriodType\": 4,
    \"interestCalculationType\": 1,
    \"interestCalculationDaysInYearType\": 365,
    \"allowDependentAccount\": true,
    \"locale\": \"en\"
  }"

PUT /v1/savingsproducts/{productId}

curl -sS -X PUT "${BASE_URL}/v1/savingsproducts/{productId}" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"allowDependentAccount\": true,
    \"locale\": \"en\"
  }"

Step 3: Create the Primary Account

Create the primary savings account for the retail primary client.

POST /v1/savingsaccounts?command=submit,approve,activate

curl -sS -X POST "${BASE_URL}/v1/savingsaccounts?command=submit,approve,activate" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"clientId\": ${PRIMARY_CLIENT_ID},
    \"productId\": ${PRIMARY_PRODUCT_ID},
    \"accountSubType\": \"PRIMARY_ACCOUNT\",
    \"locale\": \"en\",
    \"dateFormat\": \"dd MMMM yyyy\",
    \"submittedOnDate\": \"22 July 2026\"
  }"

Step 4: Confirm the Primary Client and Eligible Primary Account

Before creating a family member or dependent account, confirm that:

the primary client is an active retail person client
the primary savings account is active
the primary savings account is eligible to create dependent accounts

You will use:

primaryClientId when creating and listing family members
primaryAccountId when creating and listing dependent accounts

Example values used in this tutorial:

primaryClientId: 3
primaryAccountId: 168

Step 5: Get Relationship Options

Use the person customer template API to retrieve relationshipIdOptions.

GET /v1/clients/template

curl -sS -X GET "${BASE_URL}/v1/clients/template" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Example response excerpt:

{
  "relationshipIdOptions": [
    {
      "id": 299,
      "name": "Spouse",
      "position": 0,
      "active": true,
      "mandatory": false,
      "systemDefined": false,
      "parentId": 0,
      "codeName": "RELATIONSHIP",
      "isMasked": false
    },
    {
      "id": 300,
      "name": "Grandfather or Grandmother",
      "position": 0,
      "active": true,
      "mandatory": false,
      "systemDefined": false,
      "parentId": 0,
      "codeName": "RELATIONSHIP",
      "isMasked": false
    }
  ]
}

Save one option ID as RELATIONSHIP_ID.

export RELATIONSHIP_ID="299"

Step 6: Create a Family Member

Use Create Family Member to add the family member under the primary client.

POST /v1/clients/{primaryClientId}/familymembers

This API supports two paths:

create a new linked customer
link an existing active person customer

Option A: Create a New Linked Customer

Set isCreateCustomer to true.

curl -sS -X POST "${BASE_URL}/v1/clients/${PRIMARY_CLIENT_ID}/familymembers" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"firstName\": \"Alex\",
    \"lastName\": \"Dependent\",
    \"emailAddress\": \"[email protected]\",
    \"mobileNumber\": \"+85512000001\",
    \"relationshipId\": ${RELATIONSHIP_ID},
    \"dateOfBirth\": \"2013-07-22\",
    \"isCreateCustomer\": true,
    \"dateFormat\": \"yyyy-MM-dd\",
    \"locale\": \"en\"
  }"

Notes:

mobileNumber and emailAddress are individually optional, but at least one must be provided
isCreateCustomer must be true to create a linked customer

Example response:

{
  "id": "5",
  "clientId": 3,
  "resourceId": 5,
  "data": {
    "familyMemberId": 5,
    "clientId": 3,
    "linkedCustomerId": 8
  }
}

Save:

export FAMILY_MEMBER_ID="5"
export LINKED_CUSTOMER_ID="8"

Option B: Link an Existing Customer

Use this path when the family member already has an active person customer record.

curl -sS -X POST "${BASE_URL}/v1/clients/${PRIMARY_CLIENT_ID}/familymembers" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"linkCustomerId\": 8,
    \"relationshipId\": ${RELATIONSHIP_ID}
  }"

Example response:

{
  "id": "5",
  "clientId": 3,
  "resourceId": 5,
  "data": {
    "familyMemberId": 5,
    "clientId": 3,
    "linkedCustomerId": 8
  }
}

Step 7: Review the Family Member Record

Use List Family Members to confirm the family member and retrieve the linked-customer reference.

GET /v1/clients/{primaryClientId}/familymembers

curl -sS -X GET "${BASE_URL}/v1/clients/${PRIMARY_CLIENT_ID}/familymembers" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Example response:

[
  {
    "id": 1,
    "clientId": 1,
    "linkedCustomerId": 2,
    "firstName": "Minor",
    "middleName": "",
    "lastName": "1230733164498741",
    "qualification": "",
    "relationshipId": 1,
    "relationship": "Son",
    "maritalStatusId": 0,
    "genderId": 0,
    "dateOfBirth": "2012-01-01",
    "professionId": 0,
    "mobileNumber": "+5511111113",
    "age": 14,
    "isCreateCustomer": true,
    "createdById": 1,
    "createdByUsername": "admin",
    "createdAt": "2026-07-09 14:56:19",
    "updatedById": 1,
    "updatedByUsername": "admin",
    "updatedAt": "2026-07-09 14:56:19"
  }
]

Step 8: Complete the Linked Customer Lifecycle if Needed

The linked customer lifecycle depends on age and onboarding path.

For a newly created linked customer:

under 18: the linked customer may be activated automatically
18 and above: the linked customer remains pending until standard retail verification and activation are completed

If the linked customer is 18 or older, complete the standard lifecycle before creating the dependent account:

POST /v1/clients/{clientId}?command=verify
POST /v1/clients/{clientId}?command=activate

Do not continue to dependent-account creation until the linked customer is active.

Verify Linked Customer

curl -sS -X POST "${BASE_URL}/v1/clients/${LINKED_CUSTOMER_ID}?command=verify" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{}"

Activate Linked Customer

curl -sS -X POST "${BASE_URL}/v1/clients/${LINKED_CUSTOMER_ID}?command=activate" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"locale\": \"en\",
    \"dateFormat\": \"yyyy-MM-dd\",
    \"activationDate\": \"2026-07-22\"
  }"

Step 9: Create the Dependent Account

Use Create Dependent Account to create the dependent account from the eligible primary account.

POST /v1/savingsaccounts/{primaryAccountId}/dependentaccounts

The selected family member must already have a linkedCustomerId, which is created or linked through Create Family Member.

curl -sS -X POST "${BASE_URL}/v1/savingsaccounts/${PRIMARY_ACCOUNT_ID}/dependentaccounts" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"familyMemberId\": ${FAMILY_MEMBER_ID}
  }"

Example response:

{
  "id": "2",
  "clientId": 5,
  "savingsId": 9,
  "resourceId": 2,
  "subResourceId": 9,
  "data": {
    "primaryAccountId": 2,
    "dependentAccountId": 9,
    "dependentClientId": 5,
    "dependentUserId": 21,
    "displayName": "Minor Dependent",
    "mobileNumber": "+85512955064",
    "accountSubType": "DEPENDENT_ACCOUNT",
    "status": "ACTIVE"
  }
}

Save:

export DEPENDENT_ACCOUNT_ID="9"
export DEPENDENT_USER_ID="21"

Step 10: List Dependent Accounts

Use GET /v1/savingsaccounts/{primaryAccountId}/dependentaccounts to retrieve all dependent accounts linked under the primary account.

curl -sS -X GET "${BASE_URL}/v1/savingsaccounts/${PRIMARY_ACCOUNT_ID}/dependentaccounts" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Example response:

[
  {
    "id": 3,
    "accountNo": "000000003",
    "clientId": 5,
    "clientName": "Minor Dependent",
    "savingsProductId": 2,
    "savingsProductName": "Dependent Account",
    "status": {
      "id": 300,
      "value": "Active"
    },
    "summary": {
      "availableBalance": 45.00
    },
    "parentAccount": {
      "id": 2
    },
    "accountSubType": "DEPENDENT_ACCOUNT"
  }
]

Step 11: Add Funds

Use the funding API to add funds from the primary account to the dependent account.

POST /v1/savingsaccounts/{primaryAccountId}/dependentaccounts/{dependentAccountId}/fund?command=allocate

curl -sS -X POST "${BASE_URL}/v1/savingsaccounts/${PRIMARY_ACCOUNT_ID}/dependentaccounts/${DEPENDENT_ACCOUNT_ID}/fund?command=allocate" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"amount\": 100,
    \"reference\": \"Allowance\"
  }"

Step 12: Pull Funds

Use the funding API to pull funds from the dependent account back to the primary account.

POST /v1/savingsaccounts/{primaryAccountId}/dependentaccounts/{dependentAccountId}/fund?command=deallocate

curl -sS -X POST "${BASE_URL}/v1/savingsaccounts/${PRIMARY_ACCOUNT_ID}/dependentaccounts/${DEPENDENT_ACCOUNT_ID}/fund?command=deallocate" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"amount\": 25,
    \"reference\": \"Unused allowance\"
  }"

Example add-funds or pull-funds response:

{
  "id": "2",
  "clientId": 255,
  "resourceId": 2,
  "resourceIdentifier": "17822982487033z",
  "data": {
    "reference": "ALLOWANCE",
    "amount": 100,
    "creditorAccountId": 268,
    "debtorAccountId": 264,
    "creditorAccountNumber": "000000268",
    "debtorAccountNumber": "000000264",
    "id": 2
  }
}

Step 13: Issue a Card for the Dependent Account

After the dependent account is created, use the standard card API to issue a card for the dependent account.

POST /v1/cards

curl -sS -X POST "${BASE_URL}/v1/cards" \
  -H "tenantId: ${TENANT_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"productId\": ${CARD_PRODUCT_ID},
    \"savingsAccountId\": ${DEPENDENT_ACCOUNT_ID},
    \"userId\": ${DEPENDENT_USER_ID}
  }"

Summary

The dependent-account setup flow is:

Enable dependent-account global configuration in BackOffice.
Create or update a savings product with allowDependentAccount.
Create the primary account.
Confirm the retail primary client and eligible primary account.
Get relationshipIdOptions.
Create a family member and create or link the linked customer.
Complete verification and activation if required.
Create the dependent account from the primary account.
Add or pull funds.
Issue a card for the dependent account.