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 from the auth host using HTTP Basic with your account credentials. The service signs with whichever RSA key it currently considers active — you don’t pass a kid.

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,
  "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. See Create a loan for the complete field reference.

4. Record a repayment

Two equivalent forms — by the LMS numeric id, or by the loan’s externalId you set above.

# 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}'

# Equivalent — by loan externalId
curl -sf -X POST "$BASE/v1/loans/external/$LOAN_EXT/repayments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transactionAmount": 450}'

Every repayment endpoint (waive-interest, recover, refund, credit-balance-refund, charge-off, get/adjust/reverse transaction) has both forms — see Repayments → Identifying the loan.

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