Build Tiered KYC for Digital Banking

This guide shows how to onboard a customer at a minimal tier and deepen verification on the same entity record as they request higher account functionality.

1

Complete authentication and connection check

Before creating any entity, authenticate your API session and confirm connectivity. Every request carries your API secret token in the header; a failed auth check here is the most common cause of downstream 401 errors that look like data problems but aren't.

2

Add the entity at Tier 1

Tier 1 typically requires only a name and phone number. Choose the creation method that matches the data you hold.

• Add with PII (first name, last name, country, phone). The standard Tier 1 entry point.

POST {{baseUrl}}/v2/api/entities
{
  "entityType": "individual",
  "firstName": "Jane",
  "lastName": "Doe",
  "nationality": "NG",
  "phone": "[phone]",
  "isSubjectConsent": true
}

• Add with a Nigerian eIDv identifier (Phone Number / NIN-by-phone). Starts the entity with a resolved identity, useful if you want to move straight toward a higher tier.

POST {{baseUrl}}/v2/api/entities/:entityId/identity
{
  "entityType": "individual",
  "isSubjectConsent": true,
  "identity": {
    "countryCode": "NG",
    "idType": "nin_phone",
    "mobile": "[phone]"
  }
}

• Add with a South African eIDv identifier (SAID number).For South African onboarding.

POST {{baseUrl}}/v2/api/entities/:entityId/identity
{
  "entityType": "individual",
  "isSubjectConsent": true,
  "identity": {
    "countryCode": "ZA",
    "idType": "zaSAID",
    "id": "8001015009087"
  }
}

References: Create Entity, Verify Entity (KYC)

3

Upgrade tiers on the same entity

When the customer reaches a transaction limit or requests more functionality, run the next verification on the same entity ID, no new record is created.

• Tier 2 — verify with NIN and BVN:

POST {{baseUrl}}/v2/api/entities/:entityId/identity
{
  "entityType": "individual",
  "isSubjectConsent": true,
  "identity": {
    "countryCode": "NG",
    "idType": "bvn",
    "mobile": "11111111111"
  }
}

POST {{baseUrl}}/v2/api/entities/:entityId/identity
{
  "entityType": "individual",
  "isSubjectConsent": true,
  "identity": {
    "countryCode": "NG",
    "idType": "nin",
    "mobile": "11111111111"
  }
}

4

What happens in the background?

The moment the entity is created, the platform automatically runs a full AML screen — Sanctions, PEP, Watchlist, and Adverse Media — against it. This always runs, on every plan, and produces the entity's initial risk score.

At this stage the score reflects AML data only. A newly created entity has no session or behavioral history yet, so Fraud Insight — which scores device and behavioral signals — has nothing to evaluate. As the customer transacts and generates signals, Fraud Insight enriches the profile into a fuller risk score on the same entity record. This enrichment happens over the customer's lifecycle, not at creation.