Documentation Index
Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Carbon Lending API allows fintech partners to originate business loans for their own end-customers. The full flow — from customer enrollment through repayment — is orchestrated via REST API with webhook notifications at every lifecycle event.
Flow
Customer ────► Account ────► Enroll ────► KYC ────► Apply ────► Underwriting
│
▼
Repayment ◄──── Disburse ◄──── Post-offer KYC ◄──── Offer
Step-by-step
| Step | Action | Endpoint |
|---|
| 0 | Create the customer record | POST /v1/customers |
| 1 | Create a Carbon account for the customer | POST /v1/accounts |
| 2 | Enroll customer for lending | POST /v1/loans/customers/enroll |
| 3 | Trigger KYC verification | POST /v1/loans/customers/:id/verify-kyc |
| 4 | Poll KYC until VERIFIED | GET /v1/loans/customers/:id/kyc-status |
| 5 | Submit loan application | POST /v1/loans/apply |
| 6 | Submit business profile data | POST /v1/loans/:id/submit-underwriting |
| 7 | Request bank statement | POST /v1/loans/:id/bank-statement |
| 8 | Upload supporting documents | POST /v1/loans/:id/documents |
| 9 | Start credit decisioning | POST /v1/loans/:id/start-decisioning |
| 10 | Poll until HAS_OFFER | GET /v1/loans/:id |
| 11 | Fetch offer details | GET /v1/loans/:id/offer |
| 12 | Set disbursement account | POST /v1/loans/:id/disbursement-account |
| 13 | Accept offer | POST /v1/loans/:id/offer/accept |
| 14 | Agree to terms | POST /v1/loans/:id/terms/agree |
| 15 | Upload board resolution (non-sole-prop) | POST /v1/loans/:id/board-resolution |
| 16 | Add guarantor (if required) | POST /v1/loans/:id/guarantor |
| 17 | Complete post-offer KYC | POST /v1/loans/:id/post-offer-kyc |
| — | Carbon admin disburses | (internal) |
| 18 | Charge repayments | POST /v1/loans/:loanId/repayments |
Key Concepts
Amounts
All monetary values are in kobo. Divide by 100 to get Naira.
application_id vs loan_id
application_id — UUID created when POST /v1/loans/apply succeeds. Used in all loan operation routes (:applicationId).loan_id — Populated after disbursement. Used only for repayment routes (:loanId).
Idempotency
| Endpoint | Key |
|---|
POST /v1/loans/customers/enroll | customer_id |
POST /v1/loans/apply | reference |
Board Resolution
Required for all business customers except sole proprietors.
Two-step process:
- Upload file via
POST /v1/loans/:id/documents with file_tag = BOARD_RESOLUTION_DOC — save the file_url.
- Pass
file_url to POST /v1/loans/:id/board-resolution.
Webhooks
Subscribe to real-time loan events via the webhook system. Each status change fires an event to your registered webhook URL.
| Event | Trigger |
|---|
loan.application.received | Application submitted |
loan.kyc.pending | KYC verification started |
loan.offer.generated | Offer ready |
loan.offer.accepted | Offer accepted |
loan.offer.declined | Offer declined |
loan.offer.expired | Offer expired |
loan.application.declined | Application rejected |
loan.application.approved | Approved for disbursement |
loan.disbursed | Funds disbursed |
loan.arrears | Loan in arrears |
loan.closed | Loan fully repaid |
