MFI API
MFI Suite exposes every member, loan, savings, and ledger operation through versioned APIs. Integrations can use REST (modern, OpenAPI-described), JSON-RPC (BridgeERP-native), webhooks for events, and official SDKs in Python, Node.js, Java, and Go.
API surface area
Three primary surfaces serve different integration patterns.
| Surface | Use case | Format | Auth |
|---|---|---|---|
| REST /api/v1/ | Modern third-party integrations | JSON over HTTPS | OAuth 2.0 / API key |
| JSON-RPC /jsonrpc | BridgeERP-to-BridgeERP, internal tools | JSON-RPC 2.0 | Session / API key |
| Webhooks /webhooks/ | Event push | JSON signed HMAC-SHA256 | HMAC signature verification |
| XML-RPC /xmlrpc/2/ | Legacy BridgeERP clients | XML-RPC | API key |
Authentication
Modern integrations should use OAuth 2.0 client credentials. API keys remain supported for server-to-server scripts and trusted internal automation. Avoid embedding user credentials.
# OAuth 2.0 client credentials
curl -X POST https://microfinance.mybridgeerp.com/oauth/token \
-d 'grant_type=client_credentials' \
-d 'client_id=svc_kcb_disbursement' \
-d 'client_secret=<secret>' \
-d 'scope=loans:read disbursements:write'
# Response
# {"access_token":"eyJ...","expires_in":3600,"token_type":"Bearer"}Rate limiting
Default rate limits protect tenant performance. Limits are per API key.
- 60 requests/second sustained, 120 burst
- Webhook delivery retries: 3 attempts with exponential backoff (1m, 5m, 30m)
- Bulk endpoints (e.g. /loans/bulk) counted as N requests where N = batch size
- Rate-limit response: HTTP 429 with Retry-After header
Versioning and deprecation
All REST endpoints are path-versioned (/v1/, /v2/). Two major versions are supported in parallel. Deprecation cycle: 6-month notice before sunsetting a version, with Deprecation and Sunset HTTP headers from the deprecation date.
Common objects
All surfaces expose the same data model. Names match BridgeERP model names exactly.
- mfi.member — natural persons and groups
- mfi.loan — credit facilities
- mfi.loan.schedule — repayment schedule lines
- mfi.loan.disbursement — disbursement events
- mfi.savings.account — savings accounts
- mfi.savings.transaction — savings book entries
- mfi.mobile.money.transaction — mobile money pulls/pushes
- mfi.aml.alert — AML monitoring alerts
Reference
OAuth scopes
| Scope | Description |
|---|---|
| members:read | Read member profiles and KYC |
| members:write | Create / update members |
| loans:read | Read loans and schedules |
| loans:write | Create loans, modify status |
| disbursements:write | Trigger disbursement events |
| repayments:write | Post repayments |
| savings:read | Read savings accounts and transactions |
| savings:write | Create accounts, post deposits/withdrawals |
| aml:read | Read AML alerts |
| regulatory:read | Read regulatory returns |
| webhooks:manage | Create and configure webhooks |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized despite valid token. | Token expired (default 1h). | Refresh via client credentials grant; consider caching token until 5m before expiry. |
| 429 Too Many Requests under low traffic. | Another client sharing the same API key. | Issue separate API keys per consumer; check key usage at Settings > API > Keys. |
| POST to /loans returns 500 with 'access denied'. | OAuth scope granted but user mapped to the key lacks loan officer role. | Open Settings > Users, find the technical user for the API key, add Loan Officer role. |