Skip to main content
GET
/
v1
/
credit-scorecard
/
{external_id}
Get credit scorecard
curl --request GET \
  --url https://api-staging.bsa.ai/v1/credit-scorecard/{external_id} \
  --header 'Authorization: Bearer <token>'
{
  "externalId": "<string>",
  "halopesaGrade": "<string>",
  "finalCreditScore": 123,
  "finalCreditLimit": 123,
  "totalOutstanding": 123,
  "totalPaid": 123,
  "availableCreditLimit": 123,
  "executionPeriod": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.lms.bsa.ai/llms.txt

Use this file to discover all available pages before exploring further.

Returns the customer’s current credit grade, score, and pre-approved loan limit as held by the HaloPesa credit scoring engine. The lookup key is the same externalId you set on the customer record — so once you’ve created a customer, scoring and lending share one identifier. This endpoint is read-only — it has no side effects (no SMS, no database write).

​
Path parameters

​
external_id
string
required
The customer’s partner-supplied externalId (the same value you sent on POST /v1/customers). 1–128 characters; URL-encode if it contains special characters.

​
Example

curl -sf "$BASE/v1/credit-scorecard/partner-key-1779709585" \
  -H "Authorization: Bearer $TOKEN"

​
Response

200 OK 
{
  "externalId": "partner-key-1779709585",
  "halopesaGrade": "C",
  "finalCreditScore": 500,
  "finalCreditLimit": 5000.0,
  "totalOutstanding": 0.0,
  "totalPaid": 0.0,
  "availableCreditLimit": 5000.0,
  "executionPeriod": "0.01 seconds"
}

​
Fields

​
externalId
string
Echoes the queried externalId.
​
halopesaGrade
string
Credit grade band. Common values: A, B, C. Unscored customers receive XX (see below).
​
finalCreditScore
integer
Numeric credit score on the HaloPesa scale.
​
finalCreditLimit
number
Pre-approved ceiling in TZS as set by the scoring engine. 0 for unscored customers. This is the raw upstream value — it doesn’t account for any current debt.
​
totalOutstanding
number
Sum of summary.totalOutstanding across every loan the customer holds in the LMS. 0 if the customer has no loans or doesn’t exist in the LMS yet. This is a best-effort join — if the LMS is momentarily unreachable, the field comes back as 0 rather than failing the whole scorecard call.
​
totalPaid
number
Sum of summary.totalRepayment across every loan the customer holds — total amount paid in over the lifetime of the customer’s loans (principal + interest + fees + penalty). Same best-effort semantics as totalOutstanding.
​
availableCreditLimit
number
Computed. What the customer can borrow right now: finalCreditLimit when totalOutstanding == 0, otherwise 0. The binary rule means any active obligation locks the customer out of new credit — partial top-ups against existing debt aren’t allowed.
​
executionPeriod
string
Upstream processing time. Diagnostic only — partners typically ignore it.

​
Unscored customers

A customer with no scoring record yet is not an error. The upstream returns 200 OK with sentinel values so the USSD layer always has something to render: 
{
  "externalId": "no-such-customer",
  "halopesaGrade": "XX",
  "finalCreditScore": 100,
  "finalCreditLimit": 0.0,
  "totalOutstanding": 0.0,
  "totalPaid": 0.0,
  "availableCreditLimit": 0.0,
  "executionPeriod": "0.00 seconds"
}
Branch on halopesaGrade == "XX" to detect “unscored”. Use availableCreditLimit > 0 to decide whether a new loan can be offered — that folds in both the scoring result and the LMS debt state in one check.

​
Errors

CodeWhen
invalid_argumentexternal_id path segment is empty
unauthenticatedToken missing/invalid
internalUpstream credit service unavailable or returned an unhandled error