# Quickstart: a borrower to a first repayment

This walks one loan through its life. You authenticate, create a client, apply for a loan, approve and disburse it, then record a repayment.

## Before you start

- A tenant: Its identifier goes in the Tenant-Identifier header of every request. The examples use `default`.
- A user: With permission to create clients and loans, and to approve, disburse and post repayments. (https://developer.lokta.ai/api/roles-permissions/)
- An office id: A client is created at an office. The examples use `officeId` 1.
- A loan product: Configured on the tenant. A loan is created from a product. (https://developer.lokta.ai/api/loan-products/)
- A date format: Every date is sent with the `dateFormat` and `locale` that describe it. The examples use `dd MMMM yyyy` and `en`.

## Set your environment

Every request authenticates with HTTP Basic and names its tenant in a header. Set these once and the commands below work as written.

```bash
export LOKTA_API="https://default.lokta.tech"
export LOKTA_USER="your-username"
export LOKTA_PASS="your-password"
```

## 1. Check your credentials

This returns the roles and permissions the user holds. The call is refused when the credentials are wrong.

[POST /v1/authentication](https://developer.lokta.ai/api/authentication/authenticate.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/authentication" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'
```

## 2. Create the client

Send firstname and lastname for a person, or fullname for a business. Send active as true with an activationDate.

Every date travels with the dateFormat and locale that describe it. The response carries the new clientId.

[POST /v1/clients](https://developer.lokta.ai/api/customers/create-client.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/clients" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "officeId": 1,
    "firstname": "Asha",
    "lastname": "Rao",
    "active": true,
    "activationDate": "01 September 2026",
    "submittedOnDate": "01 September 2026",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'
```

Keep the clientId from the response. The next steps call it $CLIENT_ID.

## 3. Find the loan product

A loan is created from a product. List the products on the tenant and note the id of the one you want.

[GET /v1/loanproducts](https://developer.lokta.ai/api/loan-products/retrieve-all-loan-products.md)

```bash
curl -X GET "$LOKTA_API/lokta-lms/api/v1/loanproducts" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"
```

The next steps call the product id $PRODUCT_ID.

## 4. Get the loan template

Ask for the template with the client, the product and the template type. It returns the default terms and the option lists for the fields the application needs, so you send values your tenant accepts.

[GET /v1/loans/template](https://developer.lokta.ai/api/loan-accounts/retrieve-template-loan.md)

```bash
curl -X GET "$LOKTA_API/lokta-lms/api/v1/loans/template?clientId=$CLIENT_ID&productId=$PRODUCT_ID&templateType=individual" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"
```

## 5. Submit the application

These fields are mandatory. Take the option values from the template response.

- `clientId, productId`: The client and the product from the steps above.
- `principal`: The amount applied for.
- `loanTermFrequency, loanTermFrequencyType`: The length of the loan and the unit it is measured in.
- `numberOfRepayments, repaymentEvery, repaymentFrequencyType`: How many repayments, and how often.
- `interestRatePerPeriod, interestType, interestCalculationPeriodType, amortizationType`: The interest terms.
- `transactionProcessingStrategyCode`: How a repayment is split across the amounts due.
- `loanType`: The type of loan account.
- `expectedDisbursementDate, submittedOnDate`: Dates, sent with dateFormat and locale.

The numeric codes and the strategy code below are examples. Use the values the template returned for your product.

[POST /v1/loans](https://developer.lokta.ai/api/loan-accounts/calculate-or-submit-loan-application.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/loans" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": 1,
    "productId": 1,
    "principal": 100000,
    "loanTermFrequency": 12,
    "loanTermFrequencyType": 2,
    "numberOfRepayments": 12,
    "repaymentEvery": 1,
    "repaymentFrequencyType": 2,
    "interestRatePerPeriod": 2,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "amortizationType": 1,
    "transactionProcessingStrategyCode": "principal-interest-penalties-fees-order-strategy",
    "loanType": "individual",
    "expectedDisbursementDate": "03 September 2026",
    "submittedOnDate": "01 September 2026",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'
```

The response carries the loanId. The next steps call it $LOAN_ID.

## 6. Approve the loan

State changes are commands on the loan. Approving needs the date it was approved on.

[POST /v1/loans/{loanId}](https://developer.lokta.ai/api/loan-accounts/handle-commands-loan.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/loans/$LOAN_ID?command=approve" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "approvedOnDate": "02 September 2026",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'
```

## 7. Disburse the loan

Disbursing needs the date the money went out.

[POST /v1/loans/{loanId}](https://developer.lokta.ai/api/loan-accounts/handle-commands-loan.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/loans/$LOAN_ID?command=disburse" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "actualDisbursementDate": "03 September 2026",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'
```

## 8. Record a repayment

Repayments are transactions on the loan. The body carries the date and the amount.

[POST /v1/loans/{loanId}/transactions](https://developer.lokta.ai/api/loan-transactions/handle-commands-loan-transaction.md)

```bash
curl -X POST "$LOKTA_API/lokta-lms/api/v1/loans/$LOAN_ID/transactions?command=repayment" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionDate": "03 October 2026",
    "transactionAmount": 1000,
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'
```

## 9. Read the loan back

Retrieve the loan to see its status and balances, and list its transactions to see the repayment you just posted.

[GET /v1/loans/{loanId}](https://developer.lokta.ai/api/loan-accounts/retrieve-one-loan.md)

```bash
curl -X GET "$LOKTA_API/lokta-lms/api/v1/loans/$LOAN_ID" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"
```

## Where to go next

- [Repayments, refunds and write-offs](https://developer.lokta.ai/guides/loan-transactions/)
- [Conventions: dates, commands, errors and idempotency](https://developer.lokta.ai/conventions)