Score Documents
Submit a borrower's bank or M-Pesa statements and get a lending decision back in one call — an Apenia score (0–900), a monthly affordability figure, a risk band, and the signals behind them. The endpoint accepts PDFs or images, one file or many.
Password-protected statements are supported: pass the passcodes in pins, in the same order as the files. If you send customer identity, the result is attached to that person so repeat applications build a history.
Endpoint
Replace base_url with your region host and authenticate with your app key and secret.
POST[base_url]/v1/documents
Small uploads are scored synchronously and return the decision in the response. For large or multi-file statements, submit to
POST /v1/jobs and poll GET /v1/jobs/{job_id} — the result body is identical.Request Fields
A red dot marks a required field.
FieldTypeDescription
files
File[]
One or more statement files — PDF or image. Bank or M-Pesa statements both work; the extractor detects the format.
pins
String
Comma-separated passcodes for protected PDFs, in the same order as
files.subject_id
String
Attach the analysis to an existing person so applications accumulate into a history.
phone
String
Customer phone (E.164). Resolves or creates a subject when subject_id is absent.
national_id
String
Customer national ID — a second key for matching the same person across submissions.
name
String
Customer full name, stored with the record for the reviewer's context.
Sample Request
curl -X POST https://verify.apenia.com/v1/documents \ -H "X-App-Key: ak_live_8f2c…" \ -H "X-App-Secret: sk_live_…" \ -F "[email protected]"
Response Fields
FieldTypeDescription
apenia_score
Number
The credit score, 0–900. Higher is lower risk.
risk_level
String
Band derived from the score —
Poor, Fair, Good or Excellent.affordability_monthly
Number
Estimated monthly repayment capacity, in KES.
limits.recommended
Number
Suggested facility limit for this borrower, in KES.
transaction_id
String
Unique id for this scoring event, for your ledger and webhooks.
subject_id
String
The person this result is attached to — reuse it on the next application.
Sample Response
{
"transaction_id": "txn_6b4b6c613c724f15",
"subject_id": "sub_2dZ99UjsGg68",
"apenia_score": 586,
"risk_level": "Fair",
"affordability_monthly": 32400,
"limits": { "recommended": 45000 },
"analysis": {
"debt_to_income_ratio": 5.41,
"integrity": { "verdict": "Clean" }
}
}