APENIA
API v1

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" }
  }
}