Quickstart

This walks through the common end-to-end flow: authenticate, create a customer, and create a loan. A single POST /v1/loans call returns an already-active loan — there is no separate approve or disburse step.

1. Obtain a token

The API lives on two hosts:

Purpose	Host
Token issuance, authenticate, authorize	`https://auth-api.bsa.ai`
All other endpoints (customers, loans, repayments, credit, etc.)	`https://api-staging.bsa.ai`

Get a token by calling GET /v1/auth/token on the auth host with your partner email and password. This endpoint is the only place a token comes from. Your email and password go to it and nowhere else — the API host never accepts them; every other call carries the token as Authorization: Bearer <token>.

TOKEN=$(curl -sf --user "<email>:<password>" \
  https://auth-api.bsa.ai/v1/auth/token | jq -r .token)

The response is {"token": "<JWT>"}. Tokens are valid for 365 days — see Handling expiry for the three recommended refresh patterns (proactive exp check, reactive 401 catch-and-retry, or a scheduled rotation cron). All examples below assume TOKEN is set and BASE=https://api-staging.bsa.ai.

2. Create a customer

The only field you choose is your own externalId — the identifier that ties the LMS customer record back to your system. Everything else (office, names, legal form, activation date) is filled in server-side and the customer is created Active immediately.

CUSTOMER_ID=$(curl -sf -X POST "$BASE/v1/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "ext-ada-001"}' | jq -r .id)
echo "customerId: $CUSTOMER_ID"

Response

{
  "id": "42",
  "accountNo": "000000042",
  "externalId": "ext-ada-001",
  "status": "Active",
  "active": true,
  "officeId": "1",
  "officeName": "Head Office",
  "firstname": "ext-ada-001",
  "lastname": "Customer",
  "displayName": "ext-ada-001 Customer",
  "activationDate": "2026-05-25"
}

Note the id field — "42" as a string. Pass it back exactly as received. firstname mirrors your externalId so the customer is searchable by it; lastname is a fixed placeholder LMS requires for person records.

3. Create a loan

Three required fields plus an optional externalId — your own reference for the loan (e.g. a wallet transaction id). customerId carries the customer’s externalId (the one you chose in step 2), not the numeric LMS id — you never need to store LMS ids on your side. Every loan term is inherited from the chosen product. The returned loan is already Active.

LOAN_EXT="loan-ext-$(date +%s)"

LOAN_ID=$(curl -sf -X POST "$BASE/v1/loans" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"customerId\": \"ext-ada-001\", \"productId\": 1, \"principal\": 5000, \"externalId\": \"$LOAN_EXT\"}" | jq -r .id)
echo "loanId: $LOAN_ID  loanExternalId: $LOAN_EXT"

Response (abbreviated)

{
  "id": "501",
  "externalId": "loan-ext-1779712705",
  "status": "Active",
  "principal": 5000,
  "currencyCode": "TZS",
  "totalOutstanding": 5550,
  "nextDueDate": "2026-06-04",
  "nextDueAmount": 5550,
  "overdue": false,
  "disbursedAt": "2026-05-28T10:14:07+03:00",
  "dueDateTime": "2026-06-04T10:14:07+03:00",
  "repaymentSchedule": [ /* one period per instalment */ ]
}

The response carries the full balance roll-up (principalOutstanding, interestCharged, totalOutstanding, …) plus nextDueDate / nextDueAmount and the amortisation repaymentSchedule. Partners can render “you owe X, due Y” without a follow-up GET. dueDateTime is the exact instant the loan falls due — seven days after disbursedAt to the second for this product — and the instant a 10% of principal overdue penalty is posted if the loan is still unpaid. See Create a loan for the complete field reference and the overdue penalty for the rules.

4. Record a repayment

Two equivalent forms — by the LMS numeric id, or by the loan’s externalId you set above. Always send your own idempotencyKey (your wallet transaction reference) so a timed-out call can be retried safely, and transactionAt (the instant the money moved) so a payment made before dueDateTime is never penalised for reaching us late.

# By loan externalId (recommended)
curl -sf -X POST "$BASE/v1/loans/external/$LOAN_EXT/repayments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"transactionAmount\": 450, \"idempotencyKey\": \"wallet-txn-001\", \"transactionAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

# Equivalent — by LMS id
curl -sf -X POST "$BASE/v1/loans/$LOAN_ID/repayments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transactionAmount": 450, "idempotencyKey": "wallet-txn-001"}'

The response shows how the amount was allocated plus the loan’s position afterwards (loanStatus, totalOutstanding, availableCreditLimit). Re-sending the same key returns the same transaction. To read the ledger back, use GET /v1/loans/external/$LOAN_EXT/repayments (paginated, or ?idempotencyKey= to find one payment by your reference) — see Repayments.

Next steps

Browse the full Customers API
Read Errors so you can branch on failure codes
Learn how pagination works on list endpoints

Getting Started

Concepts

Customers

Loans

Repayments

Loan Products

Credit Scoring

1. Obtain a token

2. Create a customer

3. Create a loan

4. Record a repayment

Next steps

​1. Obtain a token

​2. Create a customer

​3. Create a loan

​4. Record a repayment

​Next steps

1. Obtain a token

2. Create a customer

3. Create a loan

4. Record a repayment

Next steps