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

# Applications

> Apply with the customer's data, optionally verify platform income, then accept or withdraw.

An application carries the customer's account data inline. Cr3dentials screens it and answers with an offer or a decline; the acceptance carries a fresh copy of the data, and final checks run on it.

## Application lifecycle

### Before acceptance

```mermaid actions={false} theme={null}
flowchart TD
    A[POST /v1/applications] --> S[screening]
    S -->|offer, 201| P[prequalified]
    S -->|decline, 200| D([declined])
    P -->|income verification started| AI[additional_income]
    P -->|income skipped| SEL[selection]
    AI -->|finished or skipped| SEL
```

### After acceptance

```mermaid actions={false} theme={null}
flowchart TD
    O[prequalified, additional_income or selection] -->|acceptance| F[final_checks]
    F -->|checks pass| FU[funding]
    F -->|lower offer| SEL[selection]
    F -->|checks fail| D([declined])
    FU -->|payout confirmed| FD([funded])
    FU -->|hold or payout failed| FF([funding_failed])
    FU -->|bureau check fails| D2([declined])
```

The diagrams show `step` values, plus the final `status` values `declined`, `funded` and `funding_failed`. While an application is open its `status` is `in_progress`. An application at `prequalified`, `additional_income` or `selection` can also end as `expired` (after `expires_at`) or `withdrawn`.

## Apply

`POST /v1/applications` with the customer's consent and account data. Both are required: a missing one answers 400 naming `data` or `consent`.

```json Request theme={null}
{
  "partner_account_id": "acc_83920",
  "consent": {
    "reference": "CONSENT-V1",
    "granted_at": "2026-11-18T15:00:00Z"
  },
  "data": {
    "customer": {
      "full_name": "MARIA PEREZ GOMEZ",
      "national_id": "1020304050",
      "phone": "+573001234567",
      "email": "maria@example.co",
      "country": "CO",
      "account_opened_on": "2025-06-01",
      "active": true,
      "kyc_verified": true
    },
    "balance": {
      "holdable_cents": 100000
    },
    "transactions": [
      {
        "id": "tx_1",
        "direction": "in",
        "amount_cents": 75000,
        "currency": "USD",
        "settled_at": "2026-11-01T14:00:00Z",
        "transfer_type": "bank_transfer",
        "from_outside_institution": true,
        "into_own_account": true,
        "payer_name": "ACME PAYROLL SAS",
        "intermediary": null,
        "beneficiary_name": "MARIA PEREZ GOMEZ",
        "counterparty_name": null,
        "merchant_name": null,
        "merchant_category": null,
        "balance_after_cents": 98000
      }
    ],
    "account_events": [
      { "kind": "overdraft", "on": "2026-09-14" }
    ],
    "security": {
      "credential_changes": [
        { "kind": "phone", "on": "2026-10-02" }
      ],
      "devices": [
        { "id": "dev_77a", "first_seen_on": "2026-03-10" }
      ],
      "withdrawal_destinations_added": [
        { "on": "2026-07-21" }
      ]
    }
  }
}
```

```json Response (201 offer) theme={null}
{
  "application_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "partner_account_id": "acc_83920",
  "step": "prequalified",
  "status": "in_progress",
  "is_first_loan": true,
  "expires_at": "2026-11-20T15:00:00Z",
  "offer": {
    "offer_id": "8b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "kind": "prequalified",
    "currency": "USD",
    "max_amount_cents": 10000,
    "interest_cents": 500,
    "hold_cents": 12500,
    "installment_count": 1,
    "credit_level": 1,
    "income_base_cents": 150000,
    "max_payment_cents": 30000,
    "installments": [
      {
        "seq": 1,
        "amount_due_cents": 10500,
        "principal_cents": 10000,
        "interest_cents": 500
      }
    ],
    "income_verification": {
      "platforms": ["upwork"]
    }
  },
  "decline": null,
  "loan": null
}
```

### Request fields

**partner\_account\_id** `string` *required*

Your id for the customer's account. Only invited accounts can apply; others are declined with `PRG_NOT_INVITED`.

**consent** `object` *required*

`reference` identifies the consent the customer gave, 1 to 32 characters. `granted_at` may be at most 5 minutes ahead of our clock. We store both with the decision.

**data.customer** `object` *required*

As held by your platform. `phone` in international format. `account_opened_on`, `active` and `kyc_verified` feed the account checks.

**data.balance.holdable\_cents** `integer` *required*

The balance you could hold now. It caps the loan at 80% of what can be held.

**data.transactions** `array`

At least the last 6 full calendar months, both directions. `settled_at` is null while pending, and a pending transaction never counts as income. `transfer_type` is one of `bank_transfer`, `card`, `internal`, `crypto`, `other`. Inbound rows need `payer_name` and `beneficiary_name`; card payments need the merchant fields. `intermediary` and `counterparty_name` are accepted but not used today.

**data.account\_events** `array`

The last 90 days. `kind` is one of `overdraft`, `returned_payment`, `insufficient_funds`, `negative_balance`.

**data.security** `object` *required*

Credential changes (`phone`, `email`, `password`, `two_factor`), known devices, and newly added withdrawal destinations, each with its date.

The body is limited to 1 MiB: about 2,500 transactions with every field filled, more when optional fields are left out. A larger body answers 413.

### Answers

| Answer | Meaning |
| - | - |
| 201 | An offer. The body is the application view. |
| 200 | A decline: `offer` is null and `decline.reasons` lists `code`, `borrower_message` and `how_to_improve`. Show the last two to the customer as they are. |
| 409 `APPLICATION_IN_PROGRESS` | The customer already has an open application; `details` gives its id. |
| 503 `ORIGINATION_PAUSED` | The program is paused. |

`GET /v1/applications/{id}` returns the application view at any time.

## Optional: platform income

When `offer.income_verification.platforms` is not empty, the customer can raise their offer by verifying income from that platform.

**1. Start a verification**

`POST /v1/applications/{id}/income-verification` returns `verification_id`, `token`, `expires_at` and `platforms`.

**2. Run it in your app**

Pass `token` to the Cr3dentials SDK's `Zktls.verify(token:)`. See [Mobile SDK](https://docs.cr3dentials.xyz/sdk/overview.md).

**3. Read the new offer**

When the verification finishes, the recalculated offer appears on `GET /v1/applications/{id}`, and in an `offer.updated` webhook if you take webhooks.

If the customer declines, call `POST /v1/applications/{id}/additional-income/skip`. Accepting directly also counts as a skip.

## Accept

`POST /v1/applications/{id}/acceptance` with the customer's consents and a fresh copy of the same `data` block.

```json Request theme={null}
{
  "amount_cents": 10000,
  "terms_version": "CO-2026-11",
  "autopay_authorized": true,
  "bureau_check_consent": true,
  "bureau_reporting_consent": true,
  "balance_debit_authorized": true,
  "hold_authorized": true,
  "accepted_at": "2026-11-18T15:20:00Z",
  "session": {
    "device_id": "dev_77a",
    "ip": "181.50.12.9",
    "user_agent": "ExampleBank/4.2 (iOS 18.1)",
    "device_timezone": "America/Bogota"
  },
  "data": {
    "customer": {},
    "balance": {},
    "transactions": [],
    "account_events": [],
    "security": {}
  }
}
```

`data`'s `{}` and `[]` stand for the full objects and lists from [Apply](#apply). The answer is the application view; once funding starts, its `loan` is the [loan view](https://docs.cr3dentials.xyz/lending/money-steps.md#the-loan-view).

### Rules

* All six consents must be `true`.
* `data` is the block from the application as it stands at acceptance, and it is required.
* `data.customer` must be the customer who applied: the same `national_id` (dots, dashes and spaces don't matter), or the same `full_name` when either side has no `national_id` (case, accents and punctuation don't matter). Otherwise the answer is 400 naming `data.customer`, and nothing is funded.
* `amount_cents` is any amount from the minimum up to the offer, in steps of US\$10.
* `accepted_at` is when the customer accepted: at most 5 minutes ahead of our clock and at most 24 hours old.

### Answers

| `step` and `status` | Meaning |
| - | - |
| `funding`, `in_progress` | Accepted, and funding has started. `loan` carries the loan and its money steps. |
| `selection`, `in_progress` with a lower offer | The final checks reduced the amount. Accept again for the new amount. |
| `final_checks`, `declined` | The final checks failed. |

## Withdraw

`POST /v1/applications/{id}/withdraw` withdraws an application before funding starts and answers with the application view. Once funding has started it answers 409 `INVALID_STATE`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.