Customer onboarding (KYC)

Every wallet and loan attaches to an active customer. This is the first flow you build. It mirrors the production sequence: dedup by phone, create if new, submit documents, activate.

All calls use a Bearer token from /generate-token. On a 401, re-generate and retry once.

Flow

phone lookup ──found──▶ reuse customerId
     │ not found
     ▼
upsert customer ─▶ submit KYC docs ─▶ activate ─▶ ACTIVE

Look up by phone (dedup)

Avoid creating duplicates — check if the customer already exists.

curl -s "$BRIDGE_URL/v1/kyc/customers/phone/+255700000111" \
  -H "Authorization: Bearer $TOKEN"

If no customer matches, this returns 200 with an empty (null) body — treat that as new and continue to create. A populated 200 body is an existing record — reuse its customerId.

Create (upsert) the customer

curl -s -X POST $BRIDGE_URL/v1/kyc/customers \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "legalName": "Jane Doe",
    "type": "PERSON",
    "mobile": "+255700000111",
    "email": "jane@example.com",
    "dob": "1995-01-10"
  }'

Response

{ "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "legalName": "Jane Doe", "type": "PERSON" }

Store customerId (read customerId || id — both appear in the wild).

Submit KYC documents

curl -s -X POST $BRIDGE_URL/v1/kyc/customers/$CUSTOMER_ID/kyc \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "documents": [{ "type": "NATIONAL_ID", "url": "https://storage.example.com/id-front.jpg" }],
    "identifiers": [{ "type": "nid", "value": "TZ-NIN-19900115-001" }]
  }'

Upload documents to your own storage and pass URLs. identifiers carry structured IDs (national ID, TIN, etc.).

Activate

curl -s -X PATCH $BRIDGE_URL/v1/kyc/customers/$CUSTOMER_ID/activate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"customerId\":\"$CUSTOMER_ID\",\"status\":\"ACTIVE\",\"activatedOn\":\"$(date +%F)\"}"

Response

{ "customerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "ACTIVE" }

Activation can require manual review. If it doesn’t return ACTIVE immediately, treat the customer as submitted and re-check before opening wallets or loans — don’t block your flow on it.

Open a wallet

Now give your active customer stored value.

Originate a loan

Lend to your active customer.

Build a flow

Customer onboarding (KYC)

Flow

Next

Open a wallet

Originate a loan

​Flow

​Next

Open a wallet

Originate a loan

Flow

Next