Cowdidocs
API ReferenceLoan applications

Get a loan application

GET
/v1/accounts/loan/applications/{organization}/{application_id}

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.

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

Query Parameters

user_id?string

Identifies the customer to act on behalf of. Required for an organization client; ignored for a user token.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/accounts/loan/applications/ipos/650e8400-e29b-41d4-a716-446655440000?user_id=350e8400-e29b-41d4-a716-446655440000"
{  "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"}

Create a loan application POST

Returns a quote for the organization in the path. The request schema's `anyOf` lists the supported configurations by organization. Organization clients must send `user_id` with the `org:lending.loan_applications:write` scope. Select optional `loan_product` from `GET /v1/accounts/loan/products/{organization}`, or omit it for the default product. Returns the existing open quote or 409 for an active loan account, an application in progress, or a concurrent application. A credit line product opens the credit line account at the first apply. Without an approved credit-limit override, returns 400 `LOAN_NOT_ELIGIBLE` when the user has no active merchant record, and 400 `PHONE_NUMBER_REQUIRED` when the user has no phone number. Next, send `loan_amount` and optional `reference_id` to `POST /v1/accounts/loan/applications/{organization}/{application_id}/apply`. Returns 404 when the organization does not offer the product to the user, or when that check cannot complete.

Apply for a loan POST

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.