> ## 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. # Apply for Loan > Submit a loan application for a KYC-verified customer. ## Overview Submits a loan application for a customer whose `kyc_status` is `VERIFIED`. The `reference` field is a merchant-controlled idempotency key — submitting the same reference again returns the existing application with `200 OK` instead of creating a duplicate. All amounts are in **kobo** (1 NGN = 100 kobo). ### Request **Method:** `POST`\ **URL:** `/v1/loans/apply` #### Parameters | Name | In | Type | Required | Description | | -------------- | ------ | -------- | -------- | --------------------------- | | `x-carbon-key` | Header | `string` | Yes | API key for authentication. | #### Request Body ```json theme={null} { "customer_id": "1732ca47-42b2-4990-a65d-c369e934eed3", "amount": 2000000, "repayment_period": 3, "loan_purpose": "INVENTORY_MGT", "reference": "MERCH_REF_20250115_001" } ``` | Field | Type | Required | Description | | ------------------ | ------ | -------- | --------------------------------------------------- | | `customer_id` | string | Yes | UUID of the KYC-verified customer | | `amount` | number | Yes | Loan amount in **kobo**. Minimum: `300000` (₦3,000) | | `repayment_period` | number | Yes | Repayment duration in months. Range: `1` – `6` | | `loan_purpose` | string | Yes | See enum below | | `reference` | string | Yes | Merchant idempotency key. Max 100 characters. | **`loan_purpose` values:** | Value | Description | | ---------------------- | -------------------- | | `WORKING_CAPITAL` | Working capital | | `EXPANSION_AND_GROWTH` | Business expansion | | `EQUIPMENT_PURCHASE` | Equipment purchase | | `INVENTORY_MGT` | Inventory management | | `DEBT_FINANCING` | Debt financing | | `STARTUP_CAPITAL` | Startup capital | | `OTHERS` | Other purposes | ### Response #### 201 — Application Created ```json theme={null} { "status": "success", "message": "Loan application submitted", "data": { "application_id": "aaaabbbb-cccc-dddd-eeee-ffffffffffff", "status": "PENDING", "amount": 2000000, "repayment_period": 3, "loan_purpose": "INVENTORY_MGT", "created_at": "2025-01-15T10:10:00.000Z" } } ``` #### 200 — Duplicate Reference (Idempotent) ```json theme={null} { "status": "failed", "message": "An application with this reference already exists", "data": { "application_id": "aaaabbbb-cccc-dddd-eeee-ffffffffffff", "status": "PENDING", "amount": 2000000, "repayment_period": 3, "loan_purpose": "INVENTORY_MGT", "created_at": "2025-01-15T10:10:00.000Z" } } ``` #### Error Responses | Status | Message | Cause | | ------ | ---------------------------------------------------------- | -------------------------------- | | 400 | `customer_id is required` | Field missing | | 400 | `Customer not found` | Customer not under this merchant | | 400 | `minimum loan amount is 300000 kobo` | `amount` below minimum | | 400 | `repayment_period must be between 1 and 6 months` | Out of range | | 400 | `loan_purpose must be one of: ...` | Invalid enum value | | 400 | `reference must be 100 characters or less` | `reference` too long | | 422 | `Customer KYC must be verified before applying for a loan` | `kyc_status` is not `VERIFIED` | ## OpenAPI ````yaml POST /v1/loans/apply openapi: 3.0.0 info: title: Carbon Business API description: >- ## Welcome to our API Developer Documentation Carbon aims to unlock the full potential of your business with a feature-rich account designed for growth. ## Integrations We aim to provide our APIs for developers and businesses to offer financial services to their existing customer base through REST APIs without doing the heavy lifting. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ### Authentication `Authorization : API Key` Header `x-carbon-key : value` `x-carbon-key` can be generated via developer page on Carbon Business | Environment | URL | | --- | --- | | Live | | | Sandbox | [https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api) | ### **Handling Errors** We use the conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers. | Error | Description | | --- | --- | | 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 - Unauthorized | Not a valid API key was provided. | | 402 - Request Failed | The parameters were valid but the request failed. | | 403 - Forbidden | The API key doesn't have permission to perform the request. | | 404 - Not Found | The requested resource doesn't exist. | | 429 - Too Many Requests | Too many requests hit the API | | 500, 502, 503, 504 - Server Errors | System Error | version: 1.0.0 servers: - url: https://carbonapistagingsecure.getcarbon.co/baas/api description: >- Replace {{base_url}} with your API base URL (e.g., https://api.example.com) security: - apikeyAuth: [] tags: - name: Accounts description: >- Virtual accounts are generated account details (account number and bank) that allow Carbon Business merchants to receive payments from customers via NGN bank transfer. This is currently only available in naira (NGN). Virtual accounts are either dynamic (temporary) or static (permanent). A dynamic account number expires after handling a transaction, while a static account number doesn't expire. **Static Account** Creating static accounts can be useful when receiving recurring payments through bank transfers. The process involves generating a static virtual account with customer information. Once payment is made, we will send you a webhook notification, which you can then manage. **Dynamic Account** Creating dynamic accounts can be useful when receiving one-time payments through bank transfers. The process involves generating a dynamic virtual account with a set amount for the customer during checkout. Once payment is made, we will send you a webhook notification, which you can then manage. Key things you can do with these endpoints: - Create an account - Retreive an account - Verify Transaction - Retreive a list of transactions - name: Accounts > Transactions - name: Banks description: |- - Get a list of banks and financial institutions - Verify/resolve account details - name: Customers description: >- This collection contains a set of API endpoints to manage customer-related operations for an application. The endpoints allow for creating a new customer, retrieving a list of all customers, and fetching details of a single customer. - Create Customer - Fetch Customer/Customers - name: Payout description: |- - Make Transfer - Verify Transfer - name: Status description: '- Service Health check' - name: Verification - name: Webhook description: |- ## EVENTS `account.incoming-transaction` ``` json { "event": "account.incoming-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` `account.outgoing-transaction` ``` json { "event": "account.outgoing-transaction", "data": { "id": "string", "amount": "float", "currency": "string", "transactionType": "string", "entryDate": "datetime", "uniqueRef": "string", "account": { "id": "string", "bankAccount": { "accountName": "string", "accountNumber": "string", "bank": { "code": "string", "name": "string" } }, "static": boolean, "currency": "string", "clientId": "string" } } } ``` - name: Loans description: >- Partner lending API. Enables fintech partners to originate business loans for their end-customers. - Enroll customers for lending and trigger KYC - Submit loan applications and supporting documents - Manage offer acceptance, disbursement account, and post-offer steps - Charge repayments and retrieve repayment schedules paths: /v1/loans/apply: post: tags: - Loans summary: Apply for Loan description: >- Submits a loan application for a KYC-verified customer. Idempotent on `reference`. ### Request Body - `customer_id` (string, required): UUID of the KYC-verified customer. - `amount` (number, required): Loan amount in kobo (minimum 300000). - `repayment_period` (number, required): Tenure in months (1–6). - `loan_purpose` (string, required): One of WORKING_CAPITAL | EXPANSION_AND_GROWTH | EQUIPMENT_PURCHASE | INVENTORY_MGT | DEBT_FINANCING | STARTUP_CAPITAL | OTHERS. - `reference` (string, required): Merchant-supplied idempotency key. ### Response - `status` (string): success - `data.application_id` (string): UUID for subsequent loan operations - `data.status` (string): Initial status (PENDING) parameters: - name: x-carbon-key in: header schema: type: string required: true example: '{{access_token}}' requestBody: description: Provide the required values for the request body. required: true content: application/json: schema: type: object required: - customer_id - amount - repayment_period - loan_purpose - reference properties: customer_id: type: string example: 1732ca47-42b2-4990-a65d-c369e934eed3 amount: type: number description: Loan amount in kobo example: 2000000 repayment_period: type: number description: Tenure in months (1–6) example: 3 loan_purpose: type: string example: INVENTORY_MGT reference: type: string description: Merchant idempotency key example: MERCH_REF_001 example: customer_id: 1732ca47-42b2-4990-a65d-c369e934eed3 amount: 2000000 repayment_period: 3 loan_purpose: INVENTORY_MGT reference: MERCH_REF_001 responses: '200': description: Successful response content: application/json: schema: type: object example: status: success data: application_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: PENDING components: securitySchemes: apikeyAuth: type: apiKey in: header name: apikey description: Provide your API key in the 'apikey' header. ````