Cowdidocs
API ReferenceLoan applications

Apply for a loan

POST
/v1/accounts/loan/applications/{organization}/{application_id}/apply

Submits the quote. A term loan product disburses the loan to a new account. A credit line product keeps status ACTIVE, and a workflow approves or rejects the application. All supported organizations use the same required loan_amount and optional reference_id fields. Organization clients must send user_id with the org:lending.loan_applications:write scope. A missing loan_amount returns 400 INVALID_PARAMS. Returns 404 for an application outside the caller's scope, or status REJECTED for an existing active loan account. Returns 404 when the organization does not offer the product to the user, or when that check cannot complete. Send an optional Idempotency-Key header to replay the result after a retry.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

organization*string

The organization's slug.

Value in

  • "ipos"
  • "muthokinju"
  • "proto"
application_id*string

Unique identifier of the loan application.

Formatuuid

Header Parameters

Idempotency-Key*string

Unique key that de-duplicates retries of this request: the first call executes and its response is stored, identical retries replay it, and reusing a key with a different request body is rejected with 409 Conflict.

Lengthlength <= 255

Request Body

application/json

Required loan_amount contains value in minor currency units and the currency code. Organization clients must also send user_id. User tokens identify the signed-in customer. Optional reference_id stores the partner's reference, such as an iPOS invoice ID. The quote supplies the amount limits, currency, product, tenure, interest, and penalty terms.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/accounts/loan/applications/ipos/650e8400-e29b-41d4-a716-446655440000/apply" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "user_id": "350e8400-e29b-41d4-a716-446655440000",    "loan_amount": {      "value": 1000000,      "currency": "KES"    },    "reference_id": "INV-4821"  }'
{  "id": "650e8400-e29b-41d4-a716-446655440000",  "resource_id": "lapp_351t201rmv87aae5j4csam8000",  "status": "APPROVED",  "account_id": "550e8400-e29b-41d4-a716-446655440000",  "reference_id": "INV-4821",  "loan_product": "ACME_FLAT_RATE",  "loan_product_type": "FLAT_RATE",  "loan_amount": 500000,  "tenure": {    "duration": 7,    "unit": "DAYS"  },  "interest_rate": {    "basis_points": 100,    "period_value": 7,    "period_unit": "DAYS"  },  "standard_interest_rate": {    "basis_points": 100,    "period_value": 7,    "period_unit": "DAYS"  },  "terms_range": {    "min_loan_amount": 50000,    "max_loan_amount": 5000000  },  "penalty_terms": {    "rate_basis_points": 20,    "calculation_basis": "PRINCIPAL_AND_ARREARS",    "calculation_basis_components": [      "PRINCIPAL",      "ARREARS"    ],    "type": "RECURRING",    "period_days": 1,    "trigger": "AFTER_LOAN_END",    "grace_period_days": 0,    "max_charge_days": 7  },  "currency": "KES",  "expires_at": "2025-10-27T10:30:00Z"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "id": "650e8400-e29b-41d4-a716-446655440000",  "resource_id": "lapp_351t201rmv87aae5j4csam8000",  "status": "APPROVED",  "account_id": "550e8400-e29b-41d4-a716-446655440000",  "reference_id": "INV-4821",  "loan_product": "ACME_FLAT_RATE",  "loan_product_type": "FLAT_RATE",  "loan_amount": 500000,  "tenure": {    "duration": 7,    "unit": "DAYS"  },  "interest_rate": {    "basis_points": 100,    "period_value": 7,    "period_unit": "DAYS"  },  "standard_interest_rate": {    "basis_points": 100,    "period_value": 7,    "period_unit": "DAYS"  },  "terms_range": {    "min_loan_amount": 50000,    "max_loan_amount": 5000000  },  "penalty_terms": {    "rate_basis_points": 20,    "calculation_basis": "PRINCIPAL_AND_ARREARS",    "calculation_basis_components": [      "PRINCIPAL",      "ARREARS"    ],    "type": "RECURRING",    "period_days": 1,    "trigger": "AFTER_LOAN_END",    "grace_period_days": 0,    "max_charge_days": 7  },  "currency": "KES",  "expires_at": "2025-10-27T10:30:00Z"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Get a loan application GET

Returns one of the caller's loan applications for the organization named in the path. A user token acts as the signed-in customer; an organization client must pass `user_id` as a query parameter, and needs the `org:lending.loan_applications:read` permission. Returns 404 when the application does not exist for the caller.

List the organization's loan products GET

Returns the loan products the organization offers, default product first, with the name and description to show the customer and the standard contract terms. The customer chooses one by passing its `loan_product` when they create an application. Requires the `org:lending.loan_applications:read` permission for an organization client; a user token can always call this. The response lists only the products the organization offers to the user. A user token is that user. An organization client names the user with `user_id`. Without `user_id`, the response lists only the products offered to every customer.