Skip to main content
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
1

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.
2

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).
3

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.).
4

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.

​
Next

Open a wallet

Now give your active customer stored value.

Originate a loan

Lend to your active customer.