> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincode.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Loan

> Creates a new loan application request from a customer or agent.

Creates a new loan application request. Customers or agents can use this endpoint to submit loan applications with required details including loan amount, product selection, and eligibility information.

## Request Headers

<ParamField header="X-Auth-Token" type="string" required>
  The **JWT Access Token** obtained from the `/login` or `/refresh-token` endpoint.
</ParamField>

<ParamField header="x-idempotency-key" type="string" required>
  Unique idempotency key for the request to prevent duplicate processing.
</ParamField>

<ParamField header="x-fapi-auth-date" type="string" required>
  The date and time at which the request was initiated (ISO 8601 format).
</ParamField>

<ParamField header="x-fapi-customer-ip-address" type="string" required>
  The IP address of the customer making the request.
</ParamField>

<ParamField header="x-fapi-interaction-id" type="string" required>
  Unique identifier for the interaction/session.
</ParamField>

<ParamField header="Content-Type" type="string" required default="application/json">
  Must be `application/json`.
</ParamField>

## Request Body

<ParamField body="currencyCode" type="string" required>
  The currency code for the loan (e.g., "NGN").
</ParamField>

<ParamField body="dateOfBirth" type="string" required>
  Customer's date of birth (YYYY-MM-DD).
</ParamField>

<ParamField body="durationCounter" type="number" required>
  The numeric value of the duration (e.g., 12).
</ParamField>

<ParamField body="loanApplicationStatusEnum" type="string" required default="REQUESTED">
  Initial status of the application. Must be "REQUESTED".
</ParamField>

<ParamField body="employmentStatus" type="string" required>
  Customer's employment status (e.g., "EMPLOYED", "SELF\_EMPLOYED").
</ParamField>

<ParamField body="loanAmount" type="number" required>
  The requested loan amount.
</ParamField>

<ParamField body="bvn" type="string" required>
  Bank Verification Number of the customer.
</ParamField>

<ParamField body="firstName" type="string" required>
  Customer's first name.
</ParamField>

<ParamField body="lastName" type="string" required>
  Customer's last name.
</ParamField>

<ParamField body="accountNumber" type="string" required>
  Bank account number for disbursement/repayment.
</ParamField>

<ParamField body="bankCode" type="string" required>
  Code of the bank associated with the account number.
</ParamField>

<ParamField body="phoneNumber" type="string" required>
  Customer's phone number.
</ParamField>

<ParamField body="loanDuration" type="number" required>
  Duration of the loan.
</ParamField>

<ParamField body="loanProductId" type="string" required>
  The unique identifier of the loan product.
</ParamField>

<ParamField body="loanRepaymentMethodEnum" type="string" required>
  Method of repayment (e.g., "DIRECT\_DEBIT").
</ParamField>

<ParamField body="monthlyIncome" type="number" required>
  Customer's monthly income.
</ParamField>

<ParamField body="eligibilityAnswers" type="array">
  Array of answers to eligibility questions.

  <Expandable title="eligibilityAnswers array item">
    <ParamField body="eligibilityAnswers[].questionId" type="string" required>
      Unique identifier of the eligibility question.
    </ParamField>

    <ParamField body="eligibilityAnswers[].answer" type="string" required>
      Answer to the eligibility question.
    </ParamField>
  </Expandable>
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://finlend.fincode.software/api/v6/services/user/request-loan' \
  --header 'X-Auth-Token: YOUR_JWT_ACCESS_TOKEN' \
  --header 'x-idempotency-key: unique-key-12345' \
  --header 'x-fapi-auth-date: 2024-01-15T10:30:00Z' \
  --header 'x-fapi-customer-ip-address: 192.168.1.1' \
  --header 'x-fapi-interaction-id: interaction-12345' \
  --header 'Content-Type: application/json' \
  --data '{
      "currencyCode": "NGN",
      "dateOfBirth": "1990-01-01",
      "durationCounter": 12,
      "loanApplicationStatusEnum": "REQUESTED",
      "employmentStatus": "EMPLOYED",
      "loanAmount": 50000.00,
      "bvn": "12345678901",
      "firstName": "John",
      "lastName": "Doe",
      "accountNumber": "0123456789",
      "bankCode": "044",
      "phoneNumber": "08012345678",
      "loanDuration": 12,
      "loanProductId": "product-123",
      "loanRepaymentMethodEnum": "DIRECT_DEBIT",
      "monthlyIncome": 150000.00,
      "eligibilityAnswers": [
          {
              "questionId": "q1",
              "answer": "Yes"
          }
      ]
  }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const BASE_URL = 'https://finlend.fincode.software/api/v6/services/user';

  async function requestLoan(accessToken, loanRequestData) {
    try {
      const response = await axios.post(
        `${BASE_URL}/request-loan`,
        {
          customerId: loanRequestData.customerId,
          loanProductId: loanRequestData.loanProductId,
          requestedAmount: loanRequestData.requestedAmount,
          purpose: loanRequestData.purpose || 'PERSONAL',
          tenurePreference: loanRequestData.tenurePreference,
          eligibilityAnswers: loanRequestData.eligibilityAnswers || [],
          additionalNotes: loanRequestData.additionalNotes || '',
        },
        {
          headers: {
            'X-Auth-Token': accessToken,
            'x-idempotency-key': `key-${Date.now()}`,
            'x-fapi-auth-date': new Date().toISOString(),
            'x-fapi-customer-ip-address': '192.168.1.1',
            'x-fapi-interaction-id': `interaction-${Date.now()}`,
            'Content-Type': 'application/json',
          },
        }
      );

      console.log('Loan application created successfully!');
      console.log('Application ID:', response.data.data.loanApplicationId);
      console.log('Status:', response.data.data.status);
      console.log('Requested Amount:', response.data.data.requestedAmount);
      
      if (response.data.data.nextSteps && response.data.data.nextSteps.length > 0) {
        console.log('\nNext Steps:');
        response.data.data.nextSteps.forEach((step, index) => {
          console.log(`  ${index + 1}. ${step}`);
        });
      }

      return response.data.data;
    } catch (error) {
      console.error(
        'Failed to create loan application:',
        error.response?.data || error.message
      );
      throw error;
    }
  }

  ```
</CodeGroup>


## OpenAPI

````yaml POST /user/request-loan
openapi: 3.0.0
info:
  title: FinCode API
  version: v6
servers:
  - url: https://{tenant}.fincode.software/api/v6/services
    description: API v6
    variables:
      tenant:
        default: remitjunction
        description: Enter your tenant subdomain
  - url: https://{tenant}.fincode.software/api/v1/services
    description: API v1
    variables:
      tenant:
        default: finlend
        description: Enter your tenant subdomain
  - url: https://api.stag.songhaiexchange.io
    description: Songhai Exchange API
security: []
paths:
  /user/request-loan:
    post:
      tags:
        - Lending
      summary: Request Loan
      description: Creates a new loan application request.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                currencyCode:
                  type: string
                dateOfBirth:
                  type: string
                durationCounter:
                  type: number
                loanApplicationStatusEnum:
                  type: string
                  default: REQUESTED
                employmentStatus:
                  type: string
                loanAmount:
                  type: number
                bvn:
                  type: string
                firstName:
                  type: string
                lastName:
                  type: string
                accountNumber:
                  type: string
                bankCode:
                  type: string
                phoneNumber:
                  type: string
                loanDuration:
                  type: number
                loanProductId:
                  type: string
                loanRepaymentMethodEnum:
                  type: string
                monthlyIncome:
                  type: number
                eligibilityAnswers:
                  type: array
                  items:
                    type: object
                    properties:
                      questionId:
                        type: string
                      answer:
                        type: string
      responses:
        '200':
          description: Loan application created successfully

````