# Quantum Partner API — Full Documentation

> Generated 2026-06-24 from the partner documentation guides and the OpenAPI spec (https://docs.quantumlends.com/merged-api.json).
> For the compact index version see https://docs.quantumlends.com/llms.txt.

## Table of Contents
- Quantum Partner API Documentation
- Getting Started
- Prefill Applications
- Embedded Contract Signing
- Sandbox Environment
- Submit Application API Migration Guide
- Mutual TLS Channel Authentication
- Webhook Notifications Overview
- Webhook Integration Guide
- API Reference (structured summary)

---

# Quantum Partner API Documentation

The Quantum Partner API is a RESTful API that enables you to integrate lending capabilities into your platform. The API provides:

- **Application Lifecycle Management** — Submit loan applications, upload supporting documents, retrieve and accept offers, and track applications through underwriting to funding
- **Account Management** — Manage booked accounts including requesting draws from lines of credit, processing payments, and viewing transaction history
- **Webhooks** — Receive real-time notifications when application status changes, documents are processed, offers are created, and more


- **[Getting Started](/getting-started.html)** — Learn how to integrate with the Quantum API, from authentication to your first application
- **[Sandbox Environment](/sandbox-environment.html)** — Use magic values to trigger specific outcomes and test your integration end-to-end
- **[Prefill Applications](/prefill-applications.html)** — Pre-populate loan applications with known data to streamline the applicant experience
- **[Webhooks Overview](/webhooks-overview.html)** — Understand webhook concepts, event types, and the application lifecycle
- **[Webhooks Integration Guide](/webhooks-guide.html)** — Technical guide for implementing webhooks with code examples and API reference
- **[Migration Guide](/migration-guide.html)** — Upgrade from v2 to v3 of the Quantum Partner API with minimal disruption

---

# Getting Started

Follow these steps to integrate with the Quantum Partner API:

## Authentication

Authentication is handled by a Bearer token. The token is passed in the `Authorization` header as a Bearer token.

```bash
Authorization: Bearer <token>
```

### Obtain API Credentials

1. Contact your Quantum representative
2. You'll receive a unique Bearer token for your organization
3. Include this token in all API requests

> **Warning:** Keep your API token secure! Never expose it in client-side code or public repositories.

Enterprise partners with mutual-authentication requirements can additionally enroll in [mutual TLS](/mtls.html) for transport-layer authentication on top of the Bearer token. This is optional and most integrations do not need it.

## Submit an Application

Use the `POST /api/v3/applications/submit` endpoint to submit a loan application on behalf of your customer.

### Required Fields

**Business Information (`business`)**
- `legal_name` - The legal business name
- `address` - Business address (street, city, state, zip_code)
- `phone_number` - Business phone number
- `entity_type` - Business structure (e.g., `sole_proprietorship`, `partnership`, `corporation`, `limited_liability_company`)
- `start_date` - When the business was established (YYYY-MM-DD)
- `naics_code` - Industry classification code
- `doing_business_as` (optional) - DBA name if different from legal name

**Loan Request (`loan_request`)**
- `amount` - Requested loan amount in dollars
- `purpose` - Loan purpose (e.g., `working_capital`, `equipment`, `inventory`, `expansion`)
- `authorization` - Must be `true` to authorize the credit check

**Owner Information (`owners`)**
At least one owner is required. Total ownership must equal 100%.
- `first_name`, `last_name` - Owner's legal name
- `email`, `phone_number` - Contact information
- `date_of_birth` - Date of birth (YYYY-MM-DD)
- `ssn` - Social Security Number
- `ownership_percent` - Percentage of business owned
- `is_applicant` - Set to `true` for the primary applicant
- `address` - Owner's home address

**Additional Questions (`additional_questions`)**
- `annual_sales` - Business annual revenue in dollars

### Example Request

```javascript
const response = await fetch('https://api.quantum.com/api/v3/applications/submit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    business: {
      legal_name: "Acme Inc LLC",
      doing_business_as: "Widgets Are Us",
      address: {
        street: "22 Acacia Ave",
        city: "Los Angeles",
        state: "CA",
        zip_code: "90025"
      },
      phone_number: "650-555-6124",
      entity_type: "limited_liability_company",
      naics_code: "312234",
      start_date: "2008-03-27"
    },
    loan_request: {
      amount: 50000,
      purpose: "working_capital",
      authorization: true
    },
    owners: [{
      first_name: "John",
      last_name: "Doe",
      email: "john@acmeinc.com",
      phone_number: "650-555-2134",
      date_of_birth: "1981-03-17",
      is_applicant: true,
      ownership_percent: 100,
      ssn: "123-45-6789",
      address: {
        street: "123 Main St",
        city: "Los Angeles",
        state: "CA",
        zip_code: "90025"
      }
    }],
    additional_questions: {
      annual_sales: 250000
    }
  })
});

const application = await response.json();
console.log('Application ID:', application.id);
```

> **Note:** Save the `application.id` from the response — you'll need it for uploading documents, checking status, and all subsequent operations.

For the complete schema and all available fields, see the [API Reference](/api-reference.html).

## Upload Documents
After submitting an application, upload supporting documents using `POST /api/v3/applications/{app_id}/documents`.

### Example Request

```javascript
const applicationId = 'your-application-id';

// File objects from an <input type="file"> element or other source
const bankStatementFile1 = fileInput.files[0];
const bankStatementFile2 = fileInput.files[1];
const driversLicenseFile = photoIdInput.files[0];

// Create FormData with documents
const formData = new FormData();
formData.append('bank_statements', bankStatementFile1);
formData.append('bank_statements', bankStatementFile2); // Multiple files supported
formData.append('photo_id', driversLicenseFile);

const uploadResponse = await fetch(`https://api.quantum.com/api/v3/applications/${applicationId}/documents`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
    // Note: Don't set Content-Type header - browser sets it automatically with boundary
  },
  body: formData
});

const documents = await uploadResponse.json();
console.log('Uploaded documents:', documents);
```

> **Note:** You can upload multiple files of the same type by appending them with the same field name. At least one file must be provided.

> **Warning:** **File size limits:** Individual files must be under 20MB, and the total request size must not exceed 40MB.

**Document Types:**

| Type | Description |
|------|-------------|
| `bank_statements` | Bank statements for the primary business operating account |
| `business_tax_return` | Business tax returns (typically last 2 years) |
| `personal_tax_return` | Personal tax returns for business owners |
| `ytd_financials` | Year-to-date financial statements |
| `ye_financials` | Year-end financial statements |
| `debt_schedule` | Schedule of existing business debts and obligations |
| `photo_id` | Government-issued photo identification (driver's license, passport, etc.) |
| `utility_bill` | Utility bill for address verification |
| `lease_agreement` | Commercial lease or rental agreement |
| `business_license` | Business license or permit |
| `sos_record` | Secretary of State registration documents |
| `lien_release` | Lien release documentation |
| `ssn_card` | Social Security card |
| `void_check` | Voided check for bank account verification |
| `insurance_document` | Business insurance documentation |
| `mortgage_document` | Mortgage or property documentation |
| `personal_document` | Other personal documentation |
| `formation_documents` | Business formation documents (articles of incorporation, operating agreement, etc.) |
| `unknown` | Other/miscellaneous documents |

## Add Bank Accounts

Bank accounts can be provided during the initial application submission (in the `bank_accounts` field of the `/submit` payload) or added afterward using the dedicated endpoint.

There are two types of bank accounts:

- **Aggregator accounts** (Plaid/MX) — Used for bank statement analysis. Connected via a bank aggregation provider.
- **Direct-from-customer accounts** — Used for loan disbursement. The customer provides their account and routing numbers directly.

### Add Bank Accounts After Submission

Use `POST /api/v3/applications/{app_id}/bank-accounts` to add bank accounts to an existing application.

#### Example: Aggregator Account (Plaid)

```javascript
const applicationId = 'your-application-id';

const response = await fetch(`https://api.quantum.com/api/v3/applications/${applicationId}/bank-accounts`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      source: "plaid_link",
      aggregator: {
        provider: "plaid",
        access_token: "access-sandbox-xxx",
        primary_account_id: "account-123",
        transactions: true,
        balances: true,
        identities: true
      }
    }
  ])
});
```

#### Example: Direct-from-Customer Account

```javascript
const response = await fetch(`https://api.quantum.com/api/v3/applications/${applicationId}/bank-accounts`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      source: "direct_from_customer",
      direct_from_customer: {
        account_number: "1234567890",
        routing_number: "021000021"
      }
    }
  ])
});
```

> **Note:** You can include both account types in a single request. Aggregator accounts are used for bank statement analysis, while direct-from-customer accounts are used for loan disbursement.

> **Warning:** Only one `direct_from_customer` account is allowed per request. The `account_number` must be 4–17 digits and the `routing_number` must be exactly 9 digits.

### Include Bank Accounts at Submission

You can also include bank accounts in the initial `POST /api/v3/applications/submit` request by adding a `bank_accounts` array to the payload. The format is the same as shown above.

For the complete schema and all available fields, see the [API Reference](/api-reference.html).

## Monitor Application Status
Use `GET /api/v3/applications/{app_id}/status` to check the application status as it moves through underwriting. This lightweight endpoint returns only the status, timestamps, and reference ID — ideal for polling without fetching the full application payload.

### Example Request

```javascript
const applicationId = 'your-application-id';

const statusResponse = await fetch(`https://api.quantum.com/api/v3/applications/${applicationId}/status`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const status = await statusResponse.json();
console.log('Status:', status.status);
console.log('Last modified:', status.modified);
```

### Example Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "Under Credit Review",
  "reference_id": "your-internal-id-12345",
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-16T14:45:00Z"
}
```

> **Note:** Instead of polling, you can receive real-time status updates via webhooks. See the [Webhooks Overview](/webhooks-overview.html) to get started.

> **Note:** Need the full application details including decision data? Use `GET /api/v3/applications/{app_id}` instead.

### Application Lifecycle

Understanding the application status flow:

1. **submitted** → Application received
2. **In Processing** → Initial processing
3. **Under Credit Review** → Underwriting review
4. **Approved** → Credit decision made
5. **Awaiting Offer Acceptance** → Customer needs to accept offer
6. **Preparing Loan Documents** → Documents being prepared
7. **Awaiting Document Execution** → Customer needs to sign
8. **Awaiting Funding** → Funding in progress
9. **Booked** → Loan is active

**Alternative outcomes:**
- **Declined** - Application did not meet credit criteria
- **Offer Declined** - Customer declined the offer
- **Withdrawn** - Application withdrawn

## Review and Accept Offers
When approved, retrieve offers using `GET /api/v3/applications/{app_id}/offers` and accept the best offer with `POST /api/v3/applications/{app_id}/offer/{offer_id}/accept`.

## Service the Account
Once booked, use the Accounts API to manage draws and payments.

---

## Common Workflows

### Requesting a Draw from a Line of Credit

Once a line of credit account is active, you can request draws:

```javascript
const drawResponse = await fetch(`https://api.quantum.com/api/v3/accounts/${accountId}/draw-requests`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    draw_amount_in_cents: 1000000, // $10,000
    reference_id: "partner-draw-12345"
  })
});

const drawRequest = await drawResponse.json();
// Draw is processed asynchronously - check status or wait for webhook
```

> **Note:** Draw and payment requests are processed asynchronously. You'll receive webhook notifications when the status changes.

### Making a Payment

Submit payments for loan repayment or payoff:

```javascript
const paymentResponse = await fetch(`https://api.quantum.com/api/v3/accounts/${accountId}/payment-requests`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_amount_in_cents: 500000, // $5,000
    request_type: "Payment Request",
    reference_id: "partner-payment-456"
  })
});
```

---

## Error Handling

The API uses standard HTTP status codes to indicate success or failure:

| Status Code | Description |
|-------------|-------------|
| 200 | OK - Request succeeded |
| 201 | Created - Resource created successfully |
| 400 | Bad Request - Invalid request parameters |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource not found |
| 422 | Unprocessable Entity - Validation error |
| 500 | Internal Server Error |
| 503 | Service Unavailable |

**Error Response Format:**

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are missing or invalid.",
    "details": [
      {
        "field": "application.business.legal_name",
        "message": "This field is required."
      }
    ]
  }
}
```

> **Warning:** Always check the `error.details` array for field-specific validation errors when you receive a 422 response.

---

## Best Practices

### Use Reference IDs
Include your own `reference_id` in applications, draw requests, and payment requests to track operations in your system:

```json
{
  "reference_id": "your-internal-id-12345"
}
```

### Handle Asynchronous Operations
Draw requests and payment requests are processed asynchronously. Implement webhook handlers to receive status updates rather than polling.

### Validate Before Submitting
Ensure all required fields are present and properly formatted before submitting applications to avoid validation errors.

### Store Application IDs
Save the `application.id` returned from the submit endpoint - you'll need it for all subsequent operations (uploading documents, checking status, etc.).

---

## Querying These Docs With AI Assistants

If you're using an AI assistant (Claude, Cursor, ChatGPT with browsing, etc.) to integrate with the Quantum Partner API, point your tool at one of these machine-readable entry points instead of crawling the HTML site:

- **`https://docs.quantumlends.com/llms.txt`** — Compact index following the [llms.txt convention](https://llmstxt.org/). Lists every doc and the canonical API spec with absolute URLs the assistant can follow.
- **`https://docs.quantumlends.com/llms-full.txt`** — Single file containing the full body of every guide plus a structured summary of the OpenAPI spec. Useful when you want one fetch to cover the whole integration surface.
- **`https://docs.quantumlends.com/merged-api.json`** — Raw OpenAPI 3.1 spec, suitable for codegen or tool definitions.

Each guide page also exposes its source markdown via `<link rel="alternate" type="text/markdown" href="/content/<page>.md">`, so an assistant that lands on a guide page can fetch the source directly. The API reference page uses an `application/json` alternate that points at the OpenAPI spec.

---

## Next Steps

- Review the [complete API Reference](/api-reference.html) for detailed endpoint documentation
- Contact your Quantum representative for API credentials and sandbox access
- Test your integration in the sandbox environment before going live

---

# Prefill Applications

The Prefill API allows you to start a loan application on behalf of an applicant by submitting partial data upfront. Rather than requiring the applicant to fill out the entire application from scratch, you prefill known information — such as the applicant's name, email, and business details — and provide them with a link to complete the rest.

## Table of Contents

- [How It Works](#how-it-works)
- [Creating a Prefilled Application](#creating-a-prefilled-application)
- [The Prefill URL](#the-prefill-url)
- [Token Expiration](#token-expiration)
- [Retrieving a New Prefill Token](#retrieving-a-new-prefill-token)
- [Webhook Events](#webhook-events)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)

---

## How It Works

The prefill flow has four main steps:

![Diagram showing the four-step prefill API flow](/images/prefill-flow-diagram.jpg)



```
1. YOU CALL THE PREFILL API
   └─→ POST /api/v3/applications/prefill
   └─→ Response includes prefill_url and prefill_token

2. APPLICANT RECEIVES LINK
   ├─→ You send the prefill_url to the applicant directly
   └─→ OR an email is automatically sent (if email communication is not suppressed)

3. APPLICANT COMPLETES APPLICATION
   └─→ Applicant opens the prefill_url
   └─→ Pre-populated fields are already filled in
   └─→ Applicant completes remaining fields and submits

4. IF TOKEN EXPIRES (applicant didn't complete in time)
   └─→ prefill_application.token_expired webhook fires
   └─→ GET /api/v3/applications/{app_id}/prefill to get a new token and deliver the new prefill_url to the applicant
   └─→ OR an email is automatically sent (if email communication is not suppressed)
```



> **Note:** Whether the applicant receives the link via an automatic email or directly from you depends on your affiliate configuration. If your affiliate is configured to suppress email communication, you are responsible for delivering the `prefill_url` to the applicant.

---

## Creating a Prefilled Application

**POST /api/v3/applications/prefill**

Send a `POST` request with the applicant and (optionally) business and loan details. Only the owner's `first_name`, `last_name`, and `email` are required — everything else is optional.

### Request Body

**Owner Information (`owners`)** — Required, at least one owner.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `first_name` | string | Yes | Owner's first name (max 100 chars) |
| `last_name` | string | Yes | Owner's last name (max 100 chars) |
| `email` | string | Yes | Owner's email address |
| `middle_name` | string | No | Owner's middle name |
| `name_suffix` | string | No | Name suffix (e.g., "III") |
| `job_title` | string | No | Owner's job title |
| `phone_number` | string | No | Phone number (format: `XXX-XXX-XXXX`) |
| `date_of_birth` | string | No | Date of birth (format: `YYYY-MM-DD`, must be in the past) |
| `is_applicant` | boolean | No | Whether this owner is the primary applicant |
| `ownership_percent` | integer | No | Ownership percentage (1–100) |
| `ssn` | string | No | Social Security Number (`XXXXXXXXX` or `XXX-XX-XXXX`) |
| `address` | object | No | Owner's home address |

**Business Information (`business`)** — Optional.

| Field | Type | Description |
|-------|------|-------------|
| `legal_name` | string | Legal business name (max 100 chars) |
| `doing_business_as` | string | DBA name (max 100 chars) |
| `entity_type` | string | Business structure (e.g., `limited_liability_company`, `sole_proprietor`, `partnership`, `s_corporation`, `c_corporation`, `other`) |
| `phone_number` | string | Business phone (format: `XXX-XXX-XXXX`) |
| `naics_code` | string | NAICS industry code (exactly 6 digits) |
| `start_date` | string | Business start date (format: `YYYY-MM-DD`) |
| `non_profit` | boolean | Whether the business is a non-profit |
| `tax_identification` | string | Business TIN/EIN |
| `address` | object | Business address |

**Loan Request (`loan_request`)** — Optional.

| Field | Type | Description |
|-------|------|-------------|
| `amount` | integer | Requested loan amount ($10,000–$500,000) |
| `purpose` | string | Loan purpose (e.g., `working_capital`, `equipment_purchase`, `business_expansion`, `debt_refinancing`, `inventory_purchase`) |
| `authorization` | boolean | Credit check authorization |

**Other Fields**

| Field | Type | Description |
|-------|------|-------------|
| `reference_id` | string | Your internal reference ID for this application (max 100 chars) |

### Example Request

```javascript
const response = await fetch('https://api.quantum.com/api/v3/applications/prefill', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    owners: [{
      first_name: "Jane",
      last_name: "Smith",
      email: "jane@smithenterprises.com",
      phone_number: "415-555-0198",
      date_of_birth: "1985-06-15",
      is_applicant: true,
      ownership_percent: 100
    }],
    business: {
      legal_name: "Smith Enterprises LLC",
      entity_type: "limited_liability_company",
      phone_number: "415-555-0100",
      naics_code: "541511",
      start_date: "2018-01-15"
    },
    loan_request: {
      amount: 75000,
      purpose: "working_capital"
    },
    reference_id: "PARTNER-REF-20250001"
  })
});

const prefillApp = await response.json();
console.log('Prefill URL:', prefillApp.prefill_url);
```

### Example Response (201 Created)

```json
{
  "id": "c9cefb5c-447b-433f-a4b7-16ce14a80eac",
  "prefill_url": "https://quantumlends.com/ui/apply/sp/c9cefb5c-447b-433f-a4b7-16ce14a80eac?token=nHzIm8OvrkAD6Lt9NLwHjcxn4jIfUFWFJ52bXKaEwB0",
  "prefill_token": "nHzIm8OvrkAD6Lt9NLwHjcxn4jIfUFWFJ52bXKaEwB0",
  "owners": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@smithenterprises.com",
      "phone_number": "415-555-0198",
      "date_of_birth": "1985-06-15",
      "is_applicant": true,
      "ownership_percent": 100
    }
  ],
  "business": {
    "legal_name": "Smith Enterprises LLC",
    "entity_type": "limited_liability_company",
    "phone_number": "415-555-0100",
    "naics_code": "541511",
    "start_date": "2018-01-15"
  },
  "loan_request": {
    "amount": 75000,
    "purpose": "working_capital"
  },
  "created": "2025-06-15 14:30:00",
  "modified": "2025-06-15 14:30:01",
  "reference_id": "PARTNER-REF-20250001"
}
```

> **Note:** Save the `prefill_url` from the response — this is the link the applicant will use to continue their application. If your affiliate suppresses email communication, you are responsible for delivering this URL to the applicant.

> **Note:** The response only includes fields that have values. Null or empty fields are omitted.

### Minimal Request Example

Only the owner's name and email are strictly required:

```javascript
const response = await fetch('https://api.quantum.com/api/v3/applications/prefill', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    owners: [{
      first_name: "Jane",
      last_name: "Smith",
      email: "jane@smithenterprises.com"
    }]
  })
});
```

---

## The Prefill URL

The `prefill_url` returned in the response is a one-time-use link that takes the applicant directly to a pre-populated application form. The URL contains an authentication token so the applicant does not need to log in.

```
https://quantumlends.com/ui/apply/sp/{application_id}?token={prefill_token}
```

### How the Link Reaches the Applicant

The delivery method depends on your affiliate configuration:

| Configuration | Behavior |
|---------------|----------|
| **Emails not suppressed** (default) | An email is automatically sent to the applicant's email address with the prefill URL. |
| **Emails suppressed** | No email is sent. You are responsible for delivering the `prefill_url` to the applicant through your own channels (email, SMS, in-app notification, etc.). |

> **Warning:** If your affiliate configuration suppresses emails, make sure your integration delivers the `prefill_url` to the applicant promptly. The token embedded in the URL will expire after a period of time.

---

## Token Expiration

The `prefill_token` embedded in the prefill URL has an expiration time. If the applicant attempts to open the link after the token has expired, they will not be able to access the prefilled application.

When an expired token is used, a `prefill_application.token_expired` webhook event is fired regardless of your email configuration. Additionally, the system handles link renewal based on your email settings:

| Configuration | What Happens on Expiration |
|---------------|---------------------------|
| **Emails not suppressed** | A new email is automatically sent to the applicant with a fresh link containing a new token. The `prefill_application.token_expired` webhook is also fired. |
| **Emails suppressed** | The `prefill_application.token_expired` webhook is fired. No email is sent — you must retrieve a new token and deliver the updated link to the applicant. |

> **Note:** The `prefill_application.token_expired` webhook is particularly important if your affiliate suppresses emails, since it is the only way to know when the applicant needs a new link. However, you can subscribe to this event for visibility into token expirations.

---

## Retrieving a New Prefill Token

**GET /api/v3/applications/{app_id}/prefill**

When you receive a `prefill_application.token_expired` webhook event, use this endpoint to retrieve a new `prefill_token` and `prefill_url` for the application. This is the recommended way to get a fresh link after token expiration, especially if your affiliate configuration suppresses emails.

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `app_id` | string (UUID) | Yes | The application ID from the original prefill response or the webhook event payload |

### Example Request

```javascript
const appId = 'c9cefb5c-447b-433f-a4b7-16ce14a80eac';

const response = await fetch(`https://api.quantum.com/api/v3/applications/${appId}/prefill`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const prefillData = await response.json();
console.log('New Prefill URL:', prefillData.prefill_url);
```

### Example Response (200 OK)

```json
{
  "id": "c9cefb5c-447b-433f-a4b7-16ce14a80eac",
  "prefill_url": "https://quantumlends.com/ui/apply/sp/c9cefb5c-447b-433f-a4b7-16ce14a80eac?token=xR7kP2mQvL9wN3jYhT6sA1cBfD4eG8iK0oU5rW2xZ9q",
  "prefill_token": "xR7kP2mQvL9wN3jYhT6sA1cBfD4eG8iK0oU5rW2xZ9q"
}
```

> **Note:** Each call to this endpoint generates a new token — any previously issued tokens for the application are invalidated. Make sure to deliver the latest `prefill_url` to the applicant.

### Handling Token Expiration Flow

Here's the recommended flow for handling token expiration:

```
1. WEBHOOK RECEIVED
   └─→ prefill_application.token_expired event fires

2. RETRIEVE NEW TOKEN
   └─→ GET /api/v3/applications/{app_id}/prefill
   └─→ Response includes new prefill_url and prefill_token

3. DELIVER NEW LINK
   └─→ Send the updated prefill_url to the applicant
```

---

## Webhook Events

The Prefill API introduces two webhook event types. Subscribe to these events to track prefilled application activity.

> **Note:** To subscribe to these events, see the [Webhooks Integration Guide](/webhooks-guide.html). Add `prefill_application.created` and `prefill_application.token_expired` to your subscription's event list.

### `prefill_application.created`

Fired when a prefilled application is successfully created.

**Payload:**

| Field | Description |
|-------|-------------|
| `id` | The UUID of the created application |
| `affiliate_id` | The affiliate ID associated with your account |
| `partner_reference_id` | The `reference_id` provided in your prefill request (if any) |

### `prefill_application.token_expired`

Fired when an applicant attempts to access a prefill link with an expired token. This is especially useful if your affiliate suppresses emails, since you need to know when to resend the link.

**Payload:**

| Field | Description |
|-------|-------------|
| `id` | The UUID of the application |
| `affiliate_id` | The affiliate ID associated with your account |
| `partner_reference_id` | The `reference_id` provided in your prefill request (if any) |

> **Note:** This webhook is deduplicated — you will receive at most one notification per token within a 24-hour window, even if the applicant clicks the expired link multiple times.


---

## Error Handling

### POST /api/v3/applications/prefill

| Status Code | Cause | Description |
|-------------|-------|-------------|
| **201** | Success | Application created. Response contains `prefill_url` and application data. |
| **400** | Not configured | Your account does not have an affiliate configured for prefill. Contact your Quantum representative. |
| **403** | Unauthorized | Your API credentials do not have permission for this operation. |
| **422** | Validation error | One or more fields are missing or invalid. Check the `error.details` array for specifics. |

### GET /api/v3/applications/{app_id}/prefill

| Status Code | Cause | Description |
|-------------|-------|-------------|
| **200** | Success | New token generated. Response contains `prefill_url` and `prefill_token`. |
| **403** | Unauthorized | Your API credentials do not have permission for this operation. |
| **404** | Not found | The application ID does not exist or does not belong to your account. |

### Example: Validation Error Response

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are missing or invalid",
    "details": [
      {
        "field": "body.owners.0.email",
        "message": "value is not a valid email address"
      }
    ]
  }
}
```

> **Warning:** If you receive a `400` error indicating that prefill is not configured, contact your Quantum representative to enable it for your account.

---

## Best Practices

### Provide As Much Data As Possible

While only `first_name`, `last_name`, and `email` are required, prefilling additional fields reduces friction for the applicant and increases the likelihood of application completion. At minimum, consider including:

- Owner's phone number and date of birth
- Business legal name and entity type
- Loan request amount and purpose

### Use Reference IDs

Include a `reference_id` to correlate prefilled applications with records in your system. This ID is returned in webhook payloads and API responses, making it easy to track applications across systems.

```json
{
  "reference_id": "YOUR-INTERNAL-ID-12345"
}
```

### Handle Token Expiration

If your affiliate suppresses emails, implement a handler for the `prefill_application.token_expired` webhook event. When received, call `GET /api/v3/applications/{app_id}/prefill` to retrieve a fresh token and deliver the new prefill link to the applicant promptly to avoid drop-off.

### Monitor Webhook Events

Subscribe to both `prefill_application.created` and `prefill_application.token_expired` events to maintain visibility into the prefill pipeline.

---

## Next Steps

- Review the [API Reference](/api-reference.html) for the complete prefill endpoint schema
- Set up [Webhook Subscriptions](/webhooks-guide.html) for prefill events
- Contact your Quantum representative to enable prefill for your account

---

# Embedded Contract Signing

The Embedded Contract Signing SDK lets you render a loan agreement for signature directly inside your own web application, so applicants never leave your experience. You load a small JavaScript SDK, hand it a signing token from the Quantum API, and subscribe to a handful of Quantum-shaped events to track progress.

The SDK is a thin, vendor-neutral wrapper. Your integration is written against the Quantum API surface described here — not against whichever document provider Quantum uses under the hood — so the contract you build to stays stable even if the underlying provider changes.

## Table of Contents

- [How It Works](#how-it-works)
- [Get a Signing Token](#get-a-signing-token)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Events](#events)
- [Error Handling](#error-handling)
- [Lifecycle Methods](#lifecycle-methods)
- [Embedding & Security](#embedding-and-security)
- [Try It Live](#try-it-live)
- [Next Steps](#next-steps)

---

## How It Works

The embedded signing flow has three steps:

```
1. YOUR BACKEND REQUESTS A SIGNING TOKEN
   └─→ GET /api/v3/applications/{app_id}/contracts
   └─→ Response includes a signing_token for each signer

2. YOUR FRONTEND LOADS THE SDK
   └─→ Load the SDK from the Quantum CDN
   └─→ new QuantumContracts(container, { signingToken })
   └─→ qc.open()

3. THE APPLICANT SIGNS IN YOUR PAGE
   └─→ The SDK renders the signing experience inside your container
   └─→ You receive contract.loading / loaded / ready / completed events
   └─→ contract.completed fires once the signer finishes
```

The signing token is short-lived and scoped to a single signer on a single contract. Fetch it from your backend (where your API credentials live) and pass it to the browser only when you are ready to render the signing experience.

---

## Get a Signing Token

**GET /api/v3/applications/{app_id}/contracts**

Call this endpoint from your backend once an application has reached the document-signing stage. The response lists the contract's signers, each with a `signing_token` you hand to the SDK.

> **Note:** The `signing_token` is a credential. Request it from your backend using your API token, then deliver it to the browser over a secure channel only when you are about to render the signing experience. Treat it like a session token — never log it, and never embed it in a URL.

See the [API Reference](/api-reference.html) for the full request and response schema.

---

## Installation

### CDN (recommended): pinned version with Subresource Integrity

Pin to an exact version and verify the bundle with [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) (SRI). The integrity hash is published as a sidecar alongside each release, so you can confirm the bytes you load are the bytes Quantum published.

```html
<div id="contract-container"></div>
<script
  src="https://cdn.quantumlends.com/packages/contracts-sdk/v1.0.0/index.umd.js"
  integrity="sha384-<see-sidecar>"
  crossorigin="anonymous"
></script>
```

Look up the hash for the version you are pinning:

```bash
curl https://cdn.quantumlends.com/packages/contracts-sdk/v1.0.0/index.umd.js.integrity
# → sha384-<base64-hash>
```

The CDN bundle (UMD) exposes a single global namespace, `QuantumSDK`:

```js
const { QuantumContracts, KNOWN_ERROR_CODES, SDK_VERSION } = QuantumSDK;
```

### CDN (convenience): floating major version

If you would rather pick up patch and minor releases automatically, load the floating major-version URL. The trade-off is that you cannot use SRI with a floating tag — the hash changes whenever we publish an update, so the `integrity` attribute would reject the new bundle.

```html
<script src="https://cdn.quantumlends.com/packages/contracts-sdk/v1/index.umd.js"></script>
```

> **Warning:** Choose deliberately. Pin + SRI gives you supply-chain protection; the floating tag gives you hands-off updates. Most integrations should pin to an exact version with SRI and bump it on your own schedule.

---

## Quick Start

A complete integration is small. The example below loads the SDK from the CDN, opens a contract, and reacts to the lifecycle events.

```html
<div id="contract-container"></div>

<script
  src="https://cdn.quantumlends.com/packages/contracts-sdk/v1.0.0/index.umd.js"
  integrity="sha384-<see-sidecar>"
  crossorigin="anonymous"
></script>

<script>
  const qc = new QuantumSDK.QuantumContracts("contract-container", {
    signingToken: tokenFromYourBackend, // GET /api/v3/applications/{app_id}/contracts
    contractId: "your-internal-id",     // optional; echoed back in every event
  });

  qc.on("contract.loaded", (p) => console.log("loaded", p.contractId));
  qc.on("contract.completed", (p) => {
    // The signer finished — advance your UI / notify your backend.
    window.location.assign("/thank-you");
  });
  qc.on("contract.error", (p) => console.error(p.code, p.message));

  qc.open();
</script>
```

> **Note:** Server-side completion notification is separate from this SDK. Use the `contract.completed` event for in-page UX, but rely on Quantum webhooks for authoritative, server-confirmed completion. See the [Webhooks Integration Guide](/webhooks-guide.html).

---

## Configuration

Construct the SDK with a container and a configuration object:

```ts
new QuantumContracts(container, config);
```

**`container`** — either the `id` of an element (a string) or an `HTMLElement` reference. The SDK renders the signing experience inside this element.

**`config`** options:


The signing token for a single signer, obtained from `GET /api/v3/applications/{app_id}/contracts`.



Your own identifier for this contract. The SDK never reads or derives it from the provider — it simply echoes the value you pass back in every event payload, so you can correlate events with your own records.



Width of the signing container. A `number` is applied as pixels (`600` → `600px`); a `string` is applied verbatim (`"100%"`, `"50vw"`). Defaults to leaving your container's styling untouched.



Height of the signing container. Same handling as `width`. A typical full-page signing experience is around `965` pixels.



Enables verbose console logging for troubleshooting. The signing token is redacted in debug output. Defaults to `false`.


---

## Events

Subscribe with `on(eventName, handler)`. Every payload includes the `contractId` you supplied in the constructor (or `undefined` if you did not supply one).

| Event | When it fires | Payload |
|-------|---------------|---------|
| `contract.loading` | The signing experience is initializing | `{ contractId? }` |
| `contract.loaded` | The contract document is loaded and visible | `{ contractId? }` |
| `contract.ready` | The document has rendered all of its pages | `{ contractId? }` |
| `contract.completed` | The signer has completed all required fields and submitted | `{ contractId? }` |
| `contract.error` | An error occurred — inspect `code` | `{ contractId?, code, message? }` |

```js
qc.on("contract.loading",   (p) => updateStatus("Loading…"));
qc.on("contract.loaded",    (p) => updateStatus("Awaiting signature"));
qc.on("contract.ready",     (p) => updateStatus("Document ready"));
qc.on("contract.completed", (p) => updateStatus("Signed"));
qc.on("contract.error",     (p) => showError(p.code, p.message));
```

> **Note:** The event set is intentionally small and may grow. Additional events (for example, a future `contract.declined`) can be added in a minor release without breaking your existing handlers, since you only receive the events you subscribe to.

---

## Error Handling

All failures surface through a single `contract.error` event carrying a `code` and an optional sanitized `message`. This gives you one consistent place to handle problems.

| `code` | Meaning |
|--------|---------|
| `not_found` | The signing token is invalid or its document is no longer available |
| `verification_required` | The signer must complete an identity verification step first |
| `verification_limit_exceeded` | The signer exhausted their verification attempts; signing cannot proceed |
| `loading_error` | The signing experience failed to initialize (network, container, or provider issue) |
| `unknown` | The provider signaled a failure without a specific code |

```js
qc.on("contract.error", (p) => {
  switch (p.code) {
    case "not_found":
      // Token expired or invalid — fetch a fresh signing_token and retry.
      break;
    case "verification_required":
    case "verification_limit_exceeded":
      // Surface a verification message to the signer.
      break;
    default:
      // Future codes you don't recognize yet — log and show a generic message.
      console.error("Signing error:", p.code, p.message);
  }
});
```

> **Warning:** The `code` list is **not exhaustive** — new codes may be added in any release. Always include a `default` branch when switching on `code` so your handler stays forward-compatible. The runtime export `KNOWN_ERROR_CODES` lists the codes known to the version you loaded.

The optional `message` is a human-readable description with provider-specific identifiers and hostnames stripped out. It is safe to log, but it is intended for diagnostics — drive your UX off `code`, not off the message text.

---

## Lifecycle Methods

| Method | Description |
|--------|-------------|
| `open()` | Renders the signing experience and resolves once the session is open. Returns a `Promise<void>`. |
| `close()` | Tears down the signing experience and restores a clean container. The instance stays usable — you can `open()` again with the same or a new token. |
| `destroy()` | Permanently tears down the instance and unsubscribes all handlers. The instance cannot be reused afterward. |
| `on(event, handler)` | Subscribe to an event. Returns the instance, so calls can be chained. |
| `once(event, handler)` | Subscribe to the next occurrence of an event only. |
| `off(event, handler)` | Remove a previously registered handler. |

```js
const qc = new QuantumContracts("contract-container", { signingToken });

qc.on("contract.completed", () => qc.destroy()); // clean up when done
await qc.open();

// Later, to swap to a different contract in the same container:
qc.close();
qc.open(); // after assigning a new token, if needed
```

> **Note:** Vendor-side failures emit a `contract.error` event rather than rejecting the `open()` promise, so you have a single error channel. It is safe to call `open()` again from inside a `contract.error` handler to retry.

---

## Embedding & Security 

The SDK renders the signing experience in an `<iframe>` that it injects into the container you provide. Because that iframe is served from the signing provider's origin (not yours), there are a few things to get right when you embed it in a security-conscious application.

### Content Security Policy (CSP)

If your application sets a `Content-Security-Policy`, allow two things: loading the SDK script from the Quantum CDN, and framing the embedded signing experience.

```
Content-Security-Policy:
  script-src 'self' https://cdn.quantumlends.com;
  frame-src  https:;
```

- **`script-src`** must include `https://cdn.quantumlends.com` so the browser can load the SDK bundle (and verify it against your `integrity` hash).
- **`frame-src`** (or `child-src` on older browsers) must allow the signing experience to render in an iframe. The SDK embeds the signing iframe over HTTPS, so a `frame-src https:` directive keeps your policy working regardless of which signing provider backs the SDK.

> **Note:** Want a `frame-src` tighter than `https:`? You can allowlist the specific signing-provider origin instead — contact your Quantum representative for the current value. Note that a strict allowlist would need updating if the provider changes. We're working toward serving the signing experience from a Quantum-owned origin, after which a single `https://*.quantumlends.com` entry will be all you need.

### X-Frame-Options and frame-ancestors

`X-Frame-Options` and the CSP `frame-ancestors` directive control who is allowed to frame *your* page. They do not affect the signing iframe the SDK creates — that is governed by the provider's own headers, and the provider permits embedding by design.

You only need to think about these headers if your own page (the one hosting the SDK) is itself rendered inside another frame:

- If you serve your page with `X-Frame-Options: DENY` or `SAMEORIGIN`, it cannot be embedded cross-origin. That is fine for a top-level page that hosts the SDK directly.
- If you intend to embed your SDK-hosting page inside another site, set `Content-Security-Policy: frame-ancestors` to list the permitted parents instead of using the legacy `X-Frame-Options`.

### General notes

- Serve the page over HTTPS. The signing experience and its token exchange require a secure context.
- The signing iframe runs in the provider's origin and handles the signing token directly. Keep the token's exposure to the browser as brief as possible — fetch it from your backend at render time rather than storing it client-side.
- Give each SDK instance its own container element. If you embed two contracts on one page, each needs a distinct container `id`.

---

## Try It Live 

Want to see it before you build? The [Embedded Signing Demo](/embedded-signing-demo.html) loads the live SDK in your browser. Paste a signing token from your environment, open a contract, and watch the events stream in real time.

---

## Next Steps

- Explore the live [Embedded Signing Demo](/embedded-signing-demo.html)
- Review the [API Reference](/api-reference.html) for the `signing_token` endpoint schema
- Set up [Webhook Subscriptions](/webhooks-guide.html) for authoritative, server-confirmed completion
- Contact your Quantum representative for signing-provider release notes

---

# Sandbox Environment

This guide covers the Quantum Sandbox environment — what it is, how to use it, and how to trigger specific application outcomes for testing.

## Table of Contents

- [What Is the Sandbox?](#what-is-the-sandbox)
- [Why Use the Sandbox?](#why-use-the-sandbox)
- [Getting Started](#getting-started)
- [What Are Magic Values?](#what-are-magic-values)
- [Declining an Application](#declining-an-application)
- [Controlling Offer Generation](#controlling-offer-generation)
- [Application Lifecycle](#application-lifecycle)
- [Pre-Underwriting Document Requests](#pre-underwriting-document-requests)
- [Closing Document Verifications](#closing-document-verifications)
- [Offer Selection](#offer-selection)
- [Booking](#booking)
- [Document Upload Outcomes](#document-upload-outcomes)
- [End-to-End Test Scenarios](#end-to-end-test-scenarios)
- [Glossary](#glossary)

---

## What Is the Sandbox?

The Sandbox is a fully isolated testing environment hosted at **sandbox.quantumlends.com**. It mirrors the production API so you can develop and validate your integration without affecting real data.

**Think of it like this:** Rather than testing against the production system and hoping nothing breaks, the Sandbox gives you a controlled environment where you can trigger any application outcome on demand.

All Sandbox data is ephemeral and completely isolated from production.

---

## Why Use the Sandbox?

| Benefit | Description |
|---------|-------------|
| **Predictable outcomes** | Trigger specific application results (approvals, declines, offer types) using magic values |
| **Full lifecycle testing** | Walk through the entire application journey, from submission through contract generation |
| **Document workflow validation** | Test document upload, approval, and rejection scenarios |
| **Integration testing** | Validate your webhook integrations against repeatable behavior |
| **Safe experimentation** | No risk to production data or real applications |

---

## Getting Started

### Authentication

Authentication is handled by a Bearer token. Include the token in the `Authorization` header for all API requests.

```
Authorization: Bearer <token>
```

### Obtain API Credentials

1. Contact your Quantum representative
2. You'll receive a unique Bearer token for your organization
3. Include this token in all API requests

> **Warning:** Keep your API token secure. Never expose it in client-side code or public repositories.

### Base URL

All Sandbox API requests should be made to:

```
https://sandbox.quantumlends.com
```

The Sandbox supports the same API endpoints as production. See the [API Reference](/api-reference.html) for the complete endpoint documentation.

> **Note:** Want to see the Sandbox in action? Try the [Sandbox Test Runner](/sandbox-test.html) to walk through the full application lifecycle in your browser. You can also download the [Node.js script](/examples/e2e-sandbox-test.mjs) to run the same flow from the command line.

---

## What Are Magic Values?

Magic values are special input values that you include in your test application data to trigger specific behaviors in the Sandbox. Think of them as cheat codes — by setting a particular field to a known value, you can deterministically control the outcome of an application.

For example, setting `business.tax_identification` to `111110000` will automatically decline the application with a specific adverse action reason. Setting `business.legal_name` to `3 Loans TL` will generate exactly 3 Term Loan offers.

When you submit an application containing a magic value, the Sandbox detects it and applies the corresponding behavior automatically.

> **Note:** Magic values can be combined. For example, you can set an owner's `last_name` to `Auto Approve` and `business.legal_name` to `3 Loans Mix` in the same request to get an auto-approved application with specific offer types.

---

## Declining an Application

You can trigger an automatic decline by including specific values in your application data. There are several ways to do this.

### By Business Tax Identification

Set the `business.tax_identification` field to one of the values below. The application will be immediately declined with the corresponding adverse action reason.

**Business Reasons:**

| tax_identification | Adverse Action Reason |
|--------------------|----------------------|
| `111110000` | Adverse business credit report information |
| `111110001` | Applicant's business does not qualify for minimum approval threshold |
| `111110002` | Applicant's business exceeds aggregate exposure limits |
| `111110003` | Application ineligible due to payment history with Quantum |
| `111110004` | Borrower Risk Outside of Tolerance |
| `111111105` | Collection action, lien or judgment |
| `111111106` | Excessive recent credit inquiries |
| `111111107` | Foreclosure, repossession or bankruptcy |
| `111111108` | Limited commercial credit experience |
| `111111109` | Slow or past due in trade or loan payments |
| `111111110` | Unable to verify business banking account information |
| `111111111` | Unable to verify business identity |
| `111111112` | Unable to verify income |
| `111111113` | Unable to verify relationship between business and applicant |
| `111111114` | Use of funds ineligible for loan proceeds |
| `111111115` | Value or type of collateral not sufficient |

**Guarantor Reasons:**

| tax_identification | Adverse Action Reason |
|--------------------|----------------------|
| `111111116` | Inadequate Guarantors Reason |
| `111111117` | Credit scoring does not meet minimum lender thresholds |
| `111111118` | Guarantor Age is less than 18 years old |
| `111111119` | Guarantor does not have a credit file |
| `111111120` | Guarantor has adverse personal credit report information |
| `111111121` | Guarantor has delinquent credit obligations |
| `111111122` | Guarantor has delinquent credit obligations with others |
| `111111123` | Guarantor has excessive obligations in relation to income |
| `111111124` | Guarantor has high number of recent credit inquiries on credit file |
| `111111125` | Guarantor has high utilization of existing credit lines |
| `111111126` | Guarantor has limited credit experience |


When a decline is triggered, the application status is set to `Declined`. You can retrieve the adverse action reasons by calling `GET /api/v3/applications/{app_id}` and inspecting the `decision` object in the response. Business reasons appear in the `business_adverse_action_reasons` array, and guarantor reasons appear in the `inadequate_guarantor_reasons` array:

```json
{
  "decision": {
    "business_adverse_action_reasons": [
      "Adverse business credit report information"
    ],
    "inadequate_guarantor_reasons": [],
    "adverse_action_date": "2025-01-15",
    "adverse_action_sent_date": null,
    "adverse_action_notification_pdf_url": null
  }
}
```

### By Business Tenure

If the business was established less than 1 year ago (based on `business.start_date`), the application is declined.

| Condition | Adverse Action Reason |
|-----------|-----------------------|
| `business.start_date` is less than 1 year ago | Applicant's business tenure insufficient |

### By State

| Field | Value | Adverse Action Reason |
|-------|-------|-----------------------|
| `business.address.state` | `NV` | Lender does not offer credit in the state where applicant is located |

### By Loan Amount

| Field | Value | Adverse Action Reason |
|-------|-------|-----------------------|
| `loan_request.amount` | `199995` | Incomplete Application |
| `loan_request.amount` | `199996` | Insufficient data submitted to render a credit decision |
| `loan_request.amount` | `199997` | Lack of established earnings record with reasonable expectation of continuity |

### By Loan Purpose

| Field | Value | Adverse Action Reason |
|-------|-------|-----------------------|
| `loan_request.purpose` | `other` | Request for personal, family or household use rather than business use |

> **Note:** The `loan_request.purpose` value is case-insensitive — `other`, `Other`, and `OTHER` all work. All other decline triggers are case-sensitive and must match exactly as shown.

### By Document Filename

When a document is uploaded, the Sandbox checks the filename for magic values.

| Filename | Adverse Action Reason |
|----------|----------------------|
| `Insufficient_cash_flow.pdf` | Insufficient cash flow from business bank account |

> **Note:** Filename matching is case-insensitive.

### By Bank Connection (Plaid)

When an applicant connects a bank account via Plaid (instead of uploading documents), the Sandbox runs cash flow analysis and then advances the application automatically — by default the application **advances** to the offer stage. To exercise the decline path on a bank connection, submit with the magic loan amount below:

| Field | Value | Adverse Action Reason |
|-------|-------|-----------------------|
| `loan_request.amount` | `199998` | Insufficient cash flow from business bank account |

> **Note:** `199998` is distinct from the decline amounts above (`199995`–`199997`): those decline immediately at submission, whereas `199998` lets the application reach Pre-Underwriting and then declines once the bank connection's cash flow analysis completes.

---

## Controlling Offer Generation

By default, applications that aren't declined receive **1 Term Loan + 1 Fee Based LOC**. You can control the number and type of offers by setting the `business.legal_name` field:

| legal_name | Offers Generated |
|------------|------------------|
| `3 Loans TL` | 3 Term Loans |
| `3 Loans LOC` | 3 Fee Based Lines of Credit |
| `3 Loans Mix` | 2 Term Loans + 1 Fee Based LOC |
| `2 Loans TL` | 2 Term Loans |
| `2 Loans LOC` | 2 Fee Based Lines of Credit |
| `2 Loans Mix` | 1 Term Loan + 1 Fee Based LOC |
| `1 Loan TL` | 1 Term Loan |
| `1 Loan LOC` | 1 Fee Based LOC |
| `3 Loans TLOC` | 3 Term LOCs |
| `2 Loans TLOC` | 2 Term LOCs |
| `1 Loan TLOC` | 1 Term LOC |
| `3 Loans RBA` | 3 Revenue Based Advances |
| `2 Loans RBA` | 2 Revenue Based Advances |
| `1 Loan RBA` | 1 Revenue Based Advance |
| *(no magic value)* | 1 Term Loan + 1 Fee Based LOC |

> **Note:** Matching is case-insensitive. Both `Loan` and `Loans` are accepted. The maximum number of offers is 3.

### Offer Details

Each generated offer uses the following values:

**Term Loan:**

| Field | Value |
|-------|-------|
| Type | Term Loan |
| Amortization Type | Standard Full Amortization |
| Loan Amount | Requested amount x 1.05 |
| Term | 12 months |
| Rate | 1.23 |
| Payment Frequency | Monthly |

**Fee Based LOC:**

| Field | Value |
|-------|-------|
| Type | Fee Based LOC |
| Facility Size | Requested amount |
| Term | 18 months |
| Basis Fee | 1.88 |
| Draw Fee | 1.64 |
| Minimum Draw Amount | $1,000 |
| Commitment Fee | 1.46 |

**Term LOC:** A line of credit priced with an interest rate and an amortized payment (unlike the Fee Based LOC, which uses a basis fee).

| Field | Value |
|-------|-------|
| Type | Term Line of Credit |
| Facility Size | Requested amount |
| Rate | 19.99 |
| Term | 18 months |
| Amortized Payment | Facility Size / 18 |
| Draw Fee | 2 |
| Minimum Draw Amount | $1,000 |
| Commitment Fee | 3 |

**RBA (Revenue Based Advance):** Priced by a factor rate rather than an interest rate.

| Field | Value |
|-------|-------|
| Type | Revenue Based Advance |
| Loan Amount | Requested amount |
| Factor Rate | 1.25 |
| Term | 12 months |
| Amortized Payment | Loan Amount x Factor Rate / 12 |
| Payment Frequency | Monthly |

---

## Application Lifecycle

### Default Behavior

By default, non-declined applications are set to **Pre-Underwriting** status. The application waits for a document upload before progressing through the rest of the pipeline.

### Triggering the Offer Pipeline

There are two ways to move the application past Pre-Underwriting:

| Trigger | How It Works |
|---------|--------------|
| **Auto Approve magic value** | Set any owner's `last_name` to `Auto Approve`. The pipeline runs immediately when the application is submitted. |
| **Document upload** | Upload a document while the application is in Pre-Underwriting status. The pipeline runs automatically. |

> **Warning:** The `Auto Approve` value is case-sensitive and must match exactly. Decline triggers always take priority — if both a decline trigger and Auto Approve are present, the application is declined.

### Pipeline Progression

Once triggered, the application moves through these statuses automatically:

```
1. APPLICATION SUBMITTED
   └─→ Status: Pre-Underwriting

2. PIPELINE TRIGGERED (Auto Approve or document upload)
   └─→ Status: Credit Review
   └─→ Status: Approved (offers generated)
   └─→ Status: Offer Sent
```

### Additional Personal Guarantors

When any owner (including the primary applicant) has `last_name` set to `Additional PGs`, an **Additional PG/s Needed** task is added to the application. This task remains incomplete throughout the entire offer generation pipeline.

| Field | Magic Value | Description |
|-------|-------------|-------------|
| `owners[].last_name` | `Additional PGs` | Adds an incomplete "Additional PG/s Needed" task |

> **Warning:** This value is case-sensitive and must match exactly as `Additional PGs`.

---

## Pre-Underwriting Document Requests

The requested loan amount (`loan_request.amount`) determines which financial documents Underwriting requests for the application. Larger loans require a more complete documentation package. The Sandbox adds the corresponding document-request tasks when the application is submitted.

There are three tiers:

| Tier | Requested Amount |
|------|------------------|
| Micro | less than $150,000 |
| Mid | $150,000 to $249,999 |
| Big | $250,000 or more |

The documents requested for each tier:

| Document | Micro | Mid | Big |
|----------|:-----:|:---:|:---:|
| 3 months of bank statements | ✓ | ✓ | ✓ |
| Most recent business tax return | | ✓ | ✓ |
| Business tax returns (2 years) | | | ✓ |
| Year-to-date financials | | | ✓ |
| Debt schedule | | ✓ | ✓ |
| Most recent personal tax return | | | ✓ |

These document-request tasks start **incomplete** and are automatically completed when the offer pipeline runs (via the `Auto Approve` magic value or a document upload) — the same lifecycle as the other Pre-Underwriting tasks.

> **Note:** Tier boundaries are exact: $150,000 and $249,999 are **Mid**; $250,000 is **Big**. Bank statements are always requested. Decline triggers take priority — a declined application receives no document-request tasks.

---

## Closing Document Verifications

These magic values control which closing document verifications remain **incomplete** after offer generation. When present, the corresponding verification is not auto-completed during the pipeline. This determines which offer selection flow the application follows (see [Offer Selection](#offer-selection)).

| Magic Value | Field | Verification |
|-------------|-------|--------------|
| `No-Name` | `business.doing_business_as` | Business Name Verification |
| `Fraudville` | `business.address.city` | Business Address Verification |
| `111002102` | `business.tax_identification` | Linkage Verification |
| `1 License Lane` | `business.address.street` | Driving License (PG Name Verification) |
| `Bounced Check Suite` | `business.address.apt_suite_number` | Voided Check |

---

## Offer Selection

When a customer selects an offer (via `POST /api/v3/applications/{app_id}/offer/{offer_id}/accept`), the next steps depend on whether any closing document verifications are still incomplete.

### Flow A: Incomplete Verifications Present

If any of the closing document magic values above were used, the application goes through an additional document collection step before contract generation:

```
1. OFFER ACCEPTED
   └─→ Status: Loan Closing Review

2. PENDING DOCUMENTS
   └─→ Status: Pending Closing Info (waiting for customer)

3. DOCUMENTS UPLOADED
   └─→ Closing verifications completed
   └─→ Contract generated and sent
   └─→ Status: Documents Sent
```

### Flow B: No Incomplete Verifications

If no closing document magic values were used, the contract is generated immediately after offer acceptance:

```
1. OFFER ACCEPTED
   └─→ Status: Loan Closing Review

2. CONTRACT
   └─→ Contract generated and sent
   └─→ Status: Documents Sent
```

### Contract Void

By default, the contract remains open for the applicant to sign. To test the void scenario, set `loan_request.amount` to `10099` — the contract will be automatically voided after a 10-second delay.

| Field | Magic Value | What Happens |
|-------|-------------|--------------|
| `loan_request.amount` | `10099` | Contract is voided after a 10-second delay |

---

## Booking

Once the contract is sent (**Documents Sent**), the applicant signs it — see [Embedded Signing](/embedded-signing.html) for how contract signing works in the Sandbox. After signing, the application moves into **Funding & Boarding**, the final stage before the loan is booked. (The partner API surfaces this status as `Awaiting Funding`.)

In production, booking is handled by a downstream system and typically takes **a day or more** to finalize, after which the application advances to **Booked**. The Sandbox compresses that wait: once an application enters **Funding & Boarding**, it advances to **Booked** automatically after about **15 seconds** — with no further action required, so you can exercise the full happy path without waiting a day.

```
1. CONTRACT SIGNED
   └─→ Status: Funding & Boarding

2. BOOKING (automatic, ~15s later)
   └─→ Status: Booked
```

> **Note:** **Booked** is the terminal status of the Sandbox happy path. In production this final transition typically takes **a day or more**; the Sandbox shortens it to ~15 seconds so you can test end-to-end quickly. No action is required on your end.

---

## Document Upload Outcomes

When a document is uploaded via `POST /api/v3/applications/{app_id}/documents`, the Sandbox checks the filename and automatically approves or rejects the document.

| Filename | Outcome | Rejection Reason |
|----------|---------|------------------|
| `good_doc.pdf` | Approved | — |
| `illegible.pdf` | Rejected | ILLEGIBLE_OR_BLURRY |
| `wrong_time_period.pdf` | Rejected | OTHER (wrong time period) |
| `missing_pages.pdf` | Rejected | INCOMPLETE |
| `wrong_doc.pdf` | Rejected | WRONG_TYPE_UPLOADED |
| `redacted_info.pdf` | Rejected | MISSING_INFORMATION |

> **Note:** Filename matching is case-insensitive. Documents with filenames that don't match any magic value are not automatically processed.

---

## End-to-End Test Scenarios

These scenarios walk you through common integration test cases. Each one combines magic values to exercise a specific path through the application lifecycle.

### Scenario 1: Quick Approval with Default Offers

Submit an application with any owner's `last_name` set to `Auto Approve`. The application will automatically progress through Pre-Underwriting, Credit Review, Approved, and Offer Sent — generating a default set of offers (1 Term Loan + 1 Fee Based LOC).

```
Submit → Pre-Underwriting → Credit Review → Approved → Offer Sent
```

### Scenario 2: Decline by Tax ID

Submit an application with `business.tax_identification` set to `111110000`. The application will be immediately declined with the adverse action reason "Adverse business credit report information."

```
Submit → Declined
```

### Scenario 3: Custom Offer Types

Submit an application with:
- Any owner's `last_name` set to `Auto Approve`
- `business.legal_name` set to `3 Loans Mix`

The application will be approved with 2 Term Loan offers and 1 Fee Based LOC offer.

```
Submit → Pre-Underwriting → Credit Review → Approved (3 offers) → Offer Sent
```

### Scenario 4: Closing Document Collection Flow

Submit an application with:
- Any owner's `last_name` set to `Auto Approve`
- `business.doing_business_as` set to `No-Name`

After the application reaches Offer Sent, accept an offer. The application will enter Pending Closing Info status. Then upload a document to complete the closing verifications and trigger contract generation. Once the contract is sent, sign it (see [Embedded Signing](/embedded-signing.html)) — the application then moves to **Funding & Boarding** and, about 15 seconds later, automatically advances to the terminal **Booked** status (see [Booking](#booking)).

```
Submit → ... → Offer Sent → Offer Accepted → Loan Closing Review
  └─→ Pending Closing Info → (document upload) → Documents Sent
  └─→ (contract signed) → Funding & Boarding → (~15s) → Booked
```

### Scenario 5: Document Rejection

After triggering the offer pipeline, upload a document with the filename `illegible.pdf`. The Sandbox will automatically reject the document with the reason `ILLEGIBLE_OR_BLURRY`.

### Scenario 6: Contract Void

Submit an application with:
- Any owner's `last_name` set to `Auto Approve`
- `loan_request.amount` set to `10099`

After the application reaches Offer Sent and an offer is accepted, the contract will be generated, sent, and then voided after a 10-second delay.

```
Submit → ... → Offer Sent → Offer Accepted → Loan Closing Review
  └─→ Contract generated → Contract sent → Contract voided (10s delay)
```

---

## Glossary

| Term | Definition |
|------|------------|
| **Magic Value** | A special input value that triggers a specific behavior in the Sandbox |
| **Adverse Action** | A decline decision with a specific regulatory reason |
| **Pre-Underwriting** | The initial status where the application waits for document uploads before progressing |
| **Offer Pipeline** | The automated sequence that generates offers and moves the application through Credit Review, Approved, and Offer Sent |
| **Funding & Boarding** | The final stage before a loan is booked; surfaced as `Awaiting Funding` in the partner API |
| **Booked** | Terminal status of the happy path — the loan has been booked |

---

## Questions?

For the complete API endpoint documentation, see the [API Reference](/api-reference.html).

For assistance with Sandbox setup or questions about your integration, contact your Quantum partner representative.

---

# Submit Application API Migration Guide

## Overview

This document provides guidance for developers migrating from the legacy endpoint `/linear/api/submit` to the new endpoint `/api/v3/applications/submit`.

> **Note:** **Both endpoints are currently available.** The legacy endpoint (`/linear/api/submit`) remains operational in QA and production environments. While we encourage you to migrate to the new v3 endpoint at your earliest convenience, you can make the switch whenever your team is ready. The legacy endpoint is considered deprecated and will eventually be phased out. Additionally, the new v3 endpoint is required to access additional API capabilities, such as document uploads.

## Authentication

The authentication is the same as it is for `www.quantumfintech.com/linear/api/submit` / `quantumlends.com/linear/api/submit`. You should use the same authentication token as before. If migrating from the `secure.fundation.com` endpoint, Bearer token authentication replaces the API Key or Client Certificate (mutual TLS).

**Example:**

```
Authorization: Bearer <token>
```

## Request Payload Comparison

### Owner Information

| Legacy Field | New API Field |
|-------------|---------------|
| `owner_first_name` | `owners[0].first_name` |
| `owner_middle` | `owners[0].middle_name` |
| `owner_last_name` | `owners[0].last_name` |
| `owner_suffix` | `owners[0].name_suffix` |
| `owner_job_title` | `owners[0].job_title` |
| `owner_email` | `owners[0].email` |
| `owner_mobile_phone` | `owners[0].phone_number` |
| `owner_DOB` | `owners[0].date_of_birth` |
| `owner_ownership_percentage` | `owners[0].ownership_percent` |
| `owner_ssn` | `owners[0].ssn` |

### Owner Address

| Legacy Field | New API Field |
|-------------|---------------|
| `owner_street_address` | `owners[0].address.street` |
| `owner_street_address_line_2` | `owners[0].address.street_2` |
| `owner_apt_suite_number` | `owners[0].address.apt_suite_number` |
| `owner_city` | `owners[0].address.city` |
| `owner_state` | `owners[0].address.state` |
| `owner_zip_code` | `owners[0].address.zip_code` |

### Business Information

| Legacy Field | New API Field |
|-------------|---------------|
| `business_name` | `business.legal_name` |
| `business_dba` | `business.doing_business_as` |
| `business_street_address` | `business.address.street` |
| `business_street_address_line_2` | `business.address.street_2` |
| `business_apt_suite_number` | `business.address.apt_suite_number` |
| `business_city` | `business.address.city` |
| `business_state` | `business.address.state` |
| `business_zip_code` | `business.address.zip_code` |
| `business_phone` | `business.phone_number` |
| `business_phone_ext_num` | `business.phone_extension` |
| `industry_id` | `business.naics_code` |
| `business_entity_type` | `business.entity_type` |
| `business_tenure_value` | `business.start_date` |
| `business_tax_id` | `business.tax_identification` |

### Additional Questions

| Legacy Field | New API Field |
|-------------|---------------|
| `outstanding_debt` | `additional_questions.outstanding_debt` |
| `business_annual_sales` | `additional_questions.annual_sales` |
| `business_number_of_employees_value` | `additional_questions.number_of_employees` |
| `business_number_of_customers_value` | `additional_questions.number_of_customers` |

### Loan Request

| Legacy Field | New API Field |
|-------------|---------------|
| `loan_amount` | `loan_request.amount` |
| `loan_purpose` | `loan_request.purpose` |
| `owner_permission_to_pull_credit` | `loan_request.authorization` |

## Important Notes

### Owners Array
- `owners` is an array in the new API, but we currently only allow one owner
- `is_applicant` must be `true` for this owner

### Middle Name
- While the legacy API `owner_middle` was a single character for middle initial, the `middle_name` in the new API allows for 100 characters for the middle name

### Phone Number Format
- Phone numbers should now be in the format `"212-555-1234"`

### Loan Purpose Values
`loan_purpose` is now `loan_request.purpose` and supports the following string values:
- `business_expansion`
- `cash_crunch`
- `debt_refinancing`
- `equipment_purchase`
- `inventory_purchase`
- `marketing_campaign`
- `meet_payroll`
- `renovations_or_capital_improvements`
- `working_capital`
- `other`

### Business Entity Type
The `business_entity_type` now uses string values instead of numeric codes:
- `limited_liability_company`
- `partnership`
- `sole_proprietor`
- `s_corporation`
- `c_corporation`
- `other`

### Reference ID
The legacy field `your_customer_id` is now `reference_id` in the new API. This optional field allows you to associate your internal identifier with applications:

```json
{
  "reference_id": "your-internal-id-12345"
}
```

## Fields Not in New API

The following legacy fields are **not supported** in the new API:

**Owner Information:**
- `owner_home_phone`
- `owner_home_own_rent`
- `owner_total_investments_value`
- `owner_household_income`
- `owner_yrs_current_address`
- `owner_months_current_address`
- `owner_prev_*` (all previous address fields)

**Business Information:**
- `business_owns_property`
- `business_annual_pretaxprofit`
- `business_monthly_rent_expense`
- `business_employee_benefits`

**Loan Information:**
- `loan_term`
- `product_type`
- `outstanding_debt_*` (breakdown by type)
- `loan_use_of_proceeds`
- `receivables_*` (all receivables fields)

**Bank Information:**
- All `bank_*` fields (balance, deposits, withdrawals, NSF transactions, etc.)

## Response Differences

### Legacy API Success Response

The Legacy API returns **HTTP Status 200 (OK)** when an application is submitted:

```json
{
  "application_id": "426e224f-1cee-4355-9b76-bf88a67eb2fb",
  "application_status": "204",
  "customer_call_required": "0",
  "doc_requ_bank_statements_3mos": "1",
  "doc_requ_bank_statements_1mos": "1",
  "doc_requ_bus_tax_return_most_recent_year": "0",
  "doc_requ_bus_tax_return_prior_year": "0",
  "doc_requ_bus_debt_schedule": "0",
  "doc_requ_bus_fncl_statements": "0",
  "doc_requ_audited_fncl_statements": "0",
  "doc_requ_pers_tax_return_most_recent_year": "0",
  "doc_requ_pers_tax_return_prior_year": "0",
  "offer_type": "0"
}
```

### New API Success Response

The New API returns **HTTP Status 201 (Created)**. The payload includes the application data that was submitted plus the following fields:

```json
{
  "id": "31c3fa8f-07bc-4b6d-8678-44eb51e4e140",
  "status": "in-review",
  "created": "2024-04-11 17:51:42",
  "modified": "2024-06-02 11:23:10"
}
```

> **Note:** For complete details on the new API endpoint, including request schemas, validation rules, and error responses, see the [API Reference](/api-reference.html#tag/Applications/operation/applications_api_submit_application).

---

# Mutual TLS Channel Authentication

> **Warning:** Mutual TLS (mTLS) is optional.  The Quantum Partner API works without mTLS — JWT authentication on every request is sufficient for most integrations. Enable mTLS when you want an additional, transport-level layer of authentication on top of the request-level identity that JWT already provides.

## What mTLS adds

mTLS authenticates the **connection**, not the request. Specifically, it gives you and us cryptographic assurance that:

- The TCP connection terminating at Quantum's partner API came from a system holding your specific TLS private key — not just from anyone who happens to have one of your JWTs in hand.
- A leaked JWT alone is no longer sufficient for an attacker to call our API as you. They would also need to compromise the private key associated with your enrolled client certificate.

JWT continues to do what it always did: identify which partner the request belongs to and what scopes it is authorized for. mTLS layers on top — it does not replace JWT, and you do not get to drop the `Authorization` header by enabling mTLS.

**When to enable it:**

- You operate under a compliance regime that requires mutual authentication between systems (FFIEC, FedRAMP-adjacent, internal banking standards, etc.).
- You want defense-in-depth against JWT exfiltration (logs, MITM upstream of Quantum, sub-vendor compromise, employee laptop theft).
- Your security team has a "no bearer tokens without a proven channel" policy.

**When you can skip it:**

- You are a smaller integrator without these requirements.
- You are still in initial development and want to ship the integration first; mTLS can be added later without breaking changes.

## How it works at a high level

1. Your client opens a TLS connection to `api.quantumlends.com` (or the sandbox equivalent — see below).
2. As part of the TLS handshake, your client presents a client certificate issued from a Certificate Authority (CA) you and we have pre-arranged.
3. Our infrastructure forwards the certificate to our application layer.
4. We validate three things:
   - The certificate chains to a CA we trust (the one you told us about during onboarding).
   - The certificate is not expired.
   - The certificate's SHA-256 thumbprint matches the thumbprint pinned to your partner account.
5. If any check fails and your account is configured to require mTLS, the request is rejected with HTTP `401`.
6. If the certificate checks out, the request proceeds to normal JWT authentication and routing.

## Endpoints

mTLS is offered on dedicated subdomains. The existing partner endpoints continue to work without mTLS for partners who are not enrolled.

| Environment | Standard hostname | mTLS-enabled hostname |
|---|---|---|
| Production | `quantumlends.com` | `api.quantumlends.com` |
| Sandbox | `sandbox.quantumlends.com` | `api.sandbox.quantumlends.com` |

**If your account is configured to require mTLS:** you must use the `api.*` hostname, and you must present your enrolled client certificate. The standard hostnames do not negotiate client certificates during the TLS handshake, so requests sent there — or requests sent to `api.*` without a client certificate — will be rejected with `401`.

**If you are not using mTLS:** you can use either hostname. The `api.*` hostnames also accept connections without a client certificate, so they are safe to use even if you have no intention of enabling mTLS now or later. Both hostnames route to the same backend services and accept the same JWTs.

## Certificate requirements

Your client certificate must meet these requirements:

| Requirement | Detail |
|---|---|
| Key type | RSA (2048-bit or stronger) or ECDSA (P-256 or stronger) |
| Signature algorithm | SHA-256 or stronger |
| TLS version | Negotiated as TLS 1.2 or TLS 1.3 |
| Issuer | A CA you have pre-coordinated with Quantum. Public CAs (DigiCert, Sectigo, Entrust, etc.) are accepted on request; private/enterprise CAs are accepted case-by-case. |
| Validity | Standard. We do not enforce a maximum lifetime, but we recommend ≤ 397 days to align with common CA/B baseline practice. |
| Subject | Must include a SubjectAlternativeName (SAN) extension. The SAN's contents are not validated or pinned — identity binding is by SHA-256 thumbprint, not by certificate subject — but the extension itself must be present. Any standard SAN type (RFC822 email, DNS name, URI) is acceptable. |

You generate the keypair on your side. The private key never leaves your infrastructure — Quantum will never ask for it, and you should never send it to us.

## Onboarding flow

Once you have decided to enable mTLS, the workflow is:

1. **Tell your Quantum integration contact** that you would like to enable mTLS. Provide:
   - The CA chain that issues your client certificate (root + any intermediates), in PEM format. You can attach this directly to your support ticket or email — these are public materials.
   - The leaf client certificate (PEM) **or** its SHA-256 thumbprint (lowercase hex, 64 characters).
   - The email address or distribution list that should receive rotation reminders and expiry alerts from us.
2. **We confirm trust of your CA.** If it is a common public CA we already trust, no action is needed. If it is a private/enterprise CA, we add it to our trust store.
3. **We put your account into a verification phase.** During this phase, every request is evaluated against your pinned thumbprint and the result is logged, but **no requests are denied** on mTLS grounds. You can deploy your client with the certificate and exercise the integration end-to-end without risk of breaking traffic.
4. **You verify behavior in your environment** by inspecting your client and our log signals (we will share what we are seeing). Once both sides agree the certificate is being presented and validated correctly, we activate the mTLS requirement on your account.
5. **The mTLS requirement is activated.** From this point forward, requests without a valid, chain-trusted, thumbprint-matching certificate are rejected with `401`.

You can stay in the verification phase as long as you like — it is not a time-boxed test window. We will not activate the mTLS requirement without explicit confirmation from your team.

## Certificate rotation

Certificates expire. When you need to rotate yours (planned renewal, key rotation, suspected compromise), the process is:

1. **At least 7 days before the new certificate goes live**, send us the new SHA-256 thumbprint via your normal Quantum integration contact.
2. We add the new thumbprint as the **current** thumbprint and move your existing one to **previous** status with a 7-day expiry. During this overlap window, requests presenting either certificate are accepted.
3. Cut over to the new certificate on your side at any point in the overlap window.
4. After the overlap window closes, only the new certificate is accepted.

The same flow applies in emergencies (suspected key compromise), but you should also ask us to immediately drop the old thumbprint rather than waiting out the overlap window. Reach out to your Quantum integration contact and to api.support@quantumlends.com.

## Error responses

When your account is configured to require mTLS and a request fails the mTLS check, you receive:

```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing credentials."
  }
}
```

The response body is intentionally generic and does **not** tell you which specific check failed. This is deliberate — we do not leak certificate-validation detail over the wire. The specific failure category is recorded on our side, so if you need to diagnose a failing request, reach out to your Quantum contact (or api.support@quantumlends.com) with the approximate request timestamp, and we can correlate against our logs.

For reference, these are the failure categories we record in our logs. You will not see them in the response body, but knowing them helps you self-diagnose the most common cases:

| Category | What it means | Likely cause |
|---|---|---|
| `no_cert_presented` | The TLS handshake completed without a client certificate. | Your client is not configured to present a cert, or is pointing at the wrong endpoint. |
| `malformed_pem` | We received a certificate but could not parse it. | Wrong format, corrupted upload, or a non-X.509 artifact. |
| `untrusted_ca` | The certificate chain does not validate against any CA we trust for your partner account. | Wrong cert presented, or your CA was rotated and not communicated to us. |
| `expired_cert` | The certificate is past its `notAfter` date (or before `notBefore`). | Overdue rotation. |
| `thumbprint_mismatch` | The certificate validated but its thumbprint does not match the one pinned for your partner. | Wrong cert presented, or a rotation completed on your side without notifying us. |

## Client configuration examples

These show only the mTLS-relevant configuration; you still need to include your `Authorization: Bearer <jwt>` header on every request.

**Python (`httpx`):**

```python
import httpx

client = httpx.Client(
    cert=("/path/to/client.crt", "/path/to/client.key"),
    base_url="https://api.quantumlends.com",
)
response = client.get("/api/v3/...", headers={"Authorization": f"Bearer {jwt}"})
```

**Python (`requests`):**

```python
import requests

response = requests.get(
    "https://api.quantumlends.com/api/v3/...",
    cert=("/path/to/client.crt", "/path/to/client.key"),
    headers={"Authorization": f"Bearer {jwt}"},
)
```

**Node.js (`https`/`axios` via agent):**

```javascript
const https = require("https");
const fs = require("fs");
const axios = require("axios");

const agent = new https.Agent({
  cert: fs.readFileSync("/path/to/client.crt"),
  key: fs.readFileSync("/path/to/client.key"),
});

(async () => {
  const response = await axios.get(
    "https://api.quantumlends.com/api/v3/...",
    { httpsAgent: agent, headers: { Authorization: `Bearer ${jwt}` } }
  );
})();
```

**curl (for testing):**

```bash
curl --cert /path/to/client.crt \
     --key /path/to/client.key \
     -H "Authorization: Bearer $JWT" \
     https://api.quantumlends.com/api/v3/...
```

## Frequently asked questions

**Can I use a self-signed certificate?**
For sandbox experimentation, yes — let us know and we will add your self-signed cert to your account's CA list. For production, we recommend a certificate from a real CA (public or private) so that rotation and chain hygiene follow established processes.

**Can I roll back to non-mTLS if something goes wrong?**
Yes. We can return your account to the verification phase (validation logged but requests not denied) or remove the mTLS requirement entirely at any time. Reach out to your Quantum contact — we can do this without a deployment on our side.

**What about the webhook direction (Quantum → you)?**
This document covers inbound mTLS only (you → Quantum). Outbound webhook authentication (Quantum → your endpoint) uses request signing — see the webhook integration documentation for details.

**What happens if a CA we both rely on is compromised?**
We monitor CA security incidents and will remove a compromised CA from our trust store. We will notify you in advance where possible. If you are not affected (your cert is not issued under the impacted CA), no action is needed. If you are affected, we will coordinate an expedited rotation onto a different CA.

**Do you support certificate transparency / CT log checks?**
We do not currently consult CT logs as part of the mTLS validation path. If this is a requirement for your environment, let us know — it is a feasible addition.

## Glossary

- **Client certificate** — The X.509 certificate that *you* present *to us* during the TLS handshake to prove who you are at the connection layer.
- **Chain validation** — Verifying that your client certificate was ultimately issued by a CA whose root we trust, through any number of intermediate CAs.
- **SHA-256 thumbprint** — The SHA-256 hash of the DER-encoded certificate bytes. Acts as a unique fingerprint for a specific certificate.
- **Pinning** — Recording your specific certificate's thumbprint in our system so that even within an otherwise-trusted CA, only *your* certificate is accepted.
- **Verification phase** — A staged onboarding state in which we evaluate every request against your pinned certificate and log the result, but do not deny any traffic. Used to confirm that your client is presenting the correct certificate before we activate the requirement.

## Getting help

For all mTLS-related questions, including initial onboarding and rotation, contact your Quantum integration manager or open a ticket via your usual support channel. For suspected key/cert compromise, also reach out to api.support@quantumlends.com so we can expedite the response.

---

# Webhook Notifications Overview

This guide provides a business-friendly overview of Quantum webhook notifications — what they are, what events you'll receive, and how they map to the loan application lifecycle.

## Table of Contents

- [What Are Webhooks?](#what-are-webhooks)
- [Why Use Webhooks?](#why-use-webhooks)
- [Event Notifications](#event-notifications)
- [Application Lifecycle](#application-lifecycle)
- [Understanding Event Data](#understanding-event-data)
- [Subscription Management](#subscription-management)
- [Glossary](#glossary)

---

## What Are Webhooks?

Webhooks are automatic notifications sent to your systems whenever something important happens with a loan application. Instead of repeatedly checking for updates (polling), Quantum proactively sends you real-time notifications.

**Think of it like this:** Rather than calling to check if your package has shipped, the delivery company sends you a text message the moment it's on its way.

---

## Why Use Webhooks?

| Benefit | Description |
|---------|-------------|
| **Real-time updates** | Know immediately when application status changes, offers are created, or documents are signed |
| **Operational efficiency** | Automate your workflows based on application events |
| **Better customer experience** | Update your customers faster with accurate status information |
| **Reduced manual work** | No need to manually check application statuses |
| **Audit trail** | Complete history of all events for compliance and reporting |

---

## Event Notifications

When you subscribe to webhooks, you choose which events you want to receive. Here's what each event means in business terms:

### Application Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Application Created** | A new loan application has been submitted | Customer completes and submits their application |
| **Application Updated** | Application information has been modified | Customer or system updates application details |
| **Status Updated** | The application has moved to a new stage | Application progresses through the pipeline |

### Offer Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Offer Created** | A loan offer has been generated for the applicant | Underwriting approves the application and generates terms |
| **Offer Selected** | The customer has accepted a loan offer | Customer reviews and accepts the proposed terms |
| **Offer Declined** | The customer has declined the loan offer | Customer chooses not to proceed with the offered terms |

### Document Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Document Uploaded** | A document has been submitted | Customer uploads required documents (bank statements, etc.) |
| **Document Status Updated** | A document has been reviewed | Document is approved, rejected, or requires resubmission |

### Contract Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Contract Sent** | Loan documents have been sent for signature | After offer acceptance, final documents are prepared |
| **Contract Signed** | All parties have signed the loan agreement | Customer completes document signing |

### Task Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Tasks Updated** | Action items for the application have changed | New tasks created or existing tasks completed |

### Prefill Application Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Prefill Application Created** | A prefilled application has been created via the Prefill API | Partner submits a prefill request on behalf of an applicant |
| **Prefill Application Token Expired** | An applicant tried to use an expired prefill link | Applicant clicks a prefill URL after the token has expired |

> **Note:** Learn more about the prefill workflow in the [Prefill Applications](/prefill-applications.html) guide.

### Other Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Funding Started** | The loan funding process has begun | After all documents are signed and verified |
| **Adverse Action Sent** | An adverse action notice has been sent to the applicant | Adverse action notices are sent for declined applications once a day at 9 pm ET |
| **Additional Owner Profile Completed** | A business co-owner has completed their profile | Multi-owner applications where additional owners submit info |

---

## Application Lifecycle

### The Happy Path: Approved Application

Here's the typical journey of a successful loan application and the notifications you'll receive:

```
1. APPLICATION SUBMITTED
   └─→ Event: Application Created
   └─→ Event: Status Updated → "In Processing"

2. DOCUMENT COLLECTION
   └─→ Event: Tasks Updated (new task: upload bank statements)
   └─→ Event: Document Uploaded (customer submits documents)
   └─→ Event: Document Status Updated (documents approved)
   └─→ Event: Tasks Updated (task completed)

3. CREDIT REVIEW
   └─→ Event: Status Updated → "Under Credit Review"
   └─→ Event: Status Updated → "Approved"

4. OFFER STAGE
   └─→ Event: Offer Created
   └─→ Event: Status Updated → "Awaiting Offer Acceptance"
   └─→ Event: Offer Selected (customer accepts)

5. DOCUMENT PREPARATION
   └─→ Event: Status Updated → "Preparing Loan Documents"
   └─→ Event: Status Updated → "Pending Closing Information"
   └─→ Event: Tasks Updated (additional documents needed)
   └─→ Event: Document Uploaded (customer submits)
   └─→ Event: Document Status Updated (documents approved)
   └─→ Event: Tasks Updated (tasks completed)

6. CONTRACT SIGNING
   └─→ Event: Contract Sent
   └─→ Event: Status Updated → "Awaiting Document Execution"
   └─→ Event: Contract Signed

7. FUNDING
   └─→ Event: Status Updated → "Awaiting Funding"
   └─→ Event: Funding Started
   └─→ Event: Status Updated → "Booked"
```

### When Customer Declines the Offer

```
1-4. Same as happy path through Offer Created...

5. CUSTOMER DECISION
   └─→ Event: Offer Declined (customer declines)
   └─→ Event: Status Updated → "Offer Declined"
```

### When Application Is Declined

```
1-2. Same as happy path through Document Collection...

3. CREDIT REVIEW
   └─→ Event: Status Updated → "Under Credit Review"
   └─→ Event: Status Updated → "Declined"
   └─→ Event: Adverse Action Sent (notice sent in the daily 9 pm ET batch)
```

---

## Application Statuses

| Status | Meaning |
|--------|---------|
| **Submitted** | Application received, initial processing beginning |
| **In Processing** | Application is being prepared for review |
| **Under Credit Review** | Underwriting team is evaluating the application |
| **Approved** | Application approved, offer being prepared |
| **Awaiting Offer Acceptance** | Offer sent, waiting for customer decision |
| **Preparing Loan Documents** | Customer accepted, documents being prepared |
| **Pending Closing Information** | Additional information needed from customer |
| **Awaiting Document Execution** | Loan documents sent for signature |
| **Awaiting Funding** | Documents signed, funding being processed |
| **Booked** | Loan funded and complete |
| **Declined** | Application not approved |
| **Offer Declined** | Customer chose not to accept the offer |
| **Withdrawn** | Application withdrawn by customer or partner |

---

## Understanding Event Data

Each webhook notification includes key information:

| Field | Description | Example |
|-------|-------------|---------|
| **Event ID** | Unique identifier for this event | `f47ac10b-58cc-4372-a567-0e02b2c3d479` |
| **Event Type** | What happened | `application.offer.created` |
| **Resource ID** | Which application this relates to | `88c911f7-1a59-4860-b786-825c9b45bc1b` |
| **Occurred At** | When the event happened | `2025-01-12T20:36:24Z` |
| **Resource URL** | Link to get more details | `https://qa.quantumlends.com/api/v3/applications/...` |

---

## Subscription Management

### What You Can Control

| Setting | Options | Description |
|---------|---------|-------------|
| **Events** | Select specific events | Only receive notifications you care about |
| **Filters** | Per-event conditions | Narrow which notifications you receive based on event data (e.g. only declined status updates) |
| **Status** | Active / Paused / Disabled | Control when you receive notifications |
| **Retries** | 0-6 attempts | How many times we retry if your system is unavailable |

> **Note:** Filters let you receive only the events that matter — for example, getting a notification only when an application is declined, instead of for every status change. The initial release supports filtering **status updates** by status value. For configuration details, see [Filtering Events](/webhooks-guide.html#filtering-events) in the integration guide.

### Subscription Statuses

| Status | Meaning |
|--------|---------|
| **Active** | Receiving notifications normally |
| **Paused** | Temporarily stopped (useful during maintenance) |
| **Disabled** | Permanently stopped |

### Viewing Delivery History

You can review all webhook deliveries through the API or dashboard:
- See which events were sent
- Check delivery success/failure
- View retry attempts
- Manually retry failed deliveries

---

## Glossary

| Term | Definition |
|------|------------|
| **Webhook** | An automatic HTTP notification sent when an event occurs |
| **Event** | Something that happened (e.g., status change, document upload) |
| **Subscription** | Your configuration for receiving webhooks (URL, events, settings) |
| **Delivery** | An attempt to send an event notification to your system |
| **Payload** | The data included in a webhook notification |
| **Adverse Action** | A decline decision with required regulatory notifications |
| **Underwriting** | The process of evaluating a loan application |

---

## Questions?

For technical implementation details, see the [Webhooks Integration Guide](/webhooks-guide.html).

For assistance with webhook setup or questions about your integration, please contact your Quantum partner representative.

---

# Webhook Integration Guide

This guide covers everything you need to integrate with the Quantum Webhook API, from creating subscriptions to verifying webhook signatures and handling application lifecycle events.

## Table of Contents

- [Overview](#overview)
- [Key Concepts](#key-concepts)
- [API Authentication](#api-authentication)
- [Webhook Delivery Authentication](#webhook-delivery-authentication)
- [Creating a Subscription](#creating-a-subscription)
- [Managing Subscriptions](#managing-subscriptions)
- [Event Types](#event-types)
- [Filtering Events](#filtering-events)
- [Application Lifecycle](#application-lifecycle)
- [Receiving Webhooks](#receiving-webhooks)
- [Signature Verification](#signature-verification)
- [Retry Mechanism](#retry-mechanism)
- [Events](#events)
- [Best Practices](#best-practices)

---

## Overview

The Quantum Webhook API allows you to receive real-time notifications about application events. Instead of polling for updates, you register a webhook endpoint and we'll send HTTP POST requests to your server whenever relevant events occur.

**Base URL:** `https://qa.quantumlends.com/api/v3/webhooks`

---

## Key Concepts

Understanding these core entities will help you work effectively with the webhook system.

> **Note:** All resource identifiers (events, subscriptions, deliveries, applications) use UUID format (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`).

### Events

An **Event** represents something that happened in the Quantum system (e.g., an application was created, an offer was accepted). When an event occurs, the system generates deliveries to all subscriptions that are listening for that event type.

- Each event has a unique UUID (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`)
- Source events are immutable records of what happened
- One event can trigger multiple deliveries (one per matching subscription)

### Event Deliveries

An **Event Delivery** represents an attempt to deliver an event to a specific subscription endpoint. Each delivery tracks:

- The HTTP response from your endpoint
- Success/failure status
- Retry attempts if the initial delivery failed
- Timestamps for each attempt

### Subscriptions

A **Subscription** defines where and how you want to receive webhooks:

- The HTTPS endpoint URL to receive webhooks
- Which event types to listen for
- Optional per-event [filters](#filtering-events) to narrow which events are delivered
- Retry configuration (0-6 retries)
- Status (active, paused, or disabled)

### Relationship Diagram

```
Event (what happened)
    │
    ├──► Event Delivery → Subscription A (your-server.com/webhooks)
    │
    └──► Event Delivery → Subscription B (backup-server.com/webhooks)
```

---

## API Authentication

All API requests require Bearer token authentication. Include your API key in the `Authorization` header:

```bash
# Set your API key and base URL
API_KEY="your_api_key_here"
BASE_URL="https://qa.quantumlends.com/api/v3/webhooks"

# All requests should include these headers
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer $API_KEY" \
     "$BASE_URL/subscriptions"
```

> **Note:** This section is about authenticating **your** calls to the Quantum webhooks API. For how Quantum authenticates to **your** endpoint when delivering webhooks, see [Webhook Delivery Authentication](#webhook-delivery-authentication).

---

## Webhook Delivery Authentication

When Quantum delivers a webhook to your endpoint, it authenticates itself in one of two ways. Every subscription is configured with one of these modes:

### HMAC Signature (default)

Quantum signs the payload with the subscription's `whsec_*` secret and sends the result in the `x-quantum-signature` header. Your endpoint verifies the signature (see [Signature Verification](#signature-verification)). No configuration is needed — this is the default.

### OAuth2 Client Credentials (optional)

Quantum additionally fetches a Bearer token from your OAuth2 token endpoint and sends it in `Authorization: Bearer <token>`. HMAC signatures are **still** included, so your existing signature verification continues to work unchanged.

Use OAuth2 when your infrastructure or security policies require Bearer token authentication on inbound webhooks. For most partners, HMAC alone is sufficient.

#### Token Flow

![Diagram showing the OAuth2 client credentials token acquisition and webhook delivery flow between Quantum and the partner](/images/webhook-oauth2-token-flow.jpg)



```
Quantum                              Partner
   │                                    │
   │  POST <token_url>                  │
   │  Authorization: Basic <credential> │
   │  grant_type=client_credentials     ├──► 200 { access_token, expires_in }
   │                                    │
   │  POST /your/webhook/endpoint       │
   │  Authorization: Bearer <token>     │
   │  x-quantum-signature: t=...,v1=... ├──► 2xx
```



Before each delivery, Quantum requests a Bearer token from your OAuth2 token endpoint using HTTP Basic authentication and the `client_credentials` grant. Successfully acquired tokens are cached server-side until shortly before they expire.

#### Requirements for Your Token Endpoint

- **HTTPS only** — plaintext token endpoints are rejected
- Accepts `POST` with:
  - `Authorization: Basic <credential>` header
  - `Content-Type: application/x-www-form-urlencoded`
  - body `grant_type=client_credentials`
- Returns JSON `{ "access_token": "...", "expires_in": <integer seconds> }`
- Tokens with missing, non-integer, or very short `expires_in` are used for the current delivery but not cached

#### Credential Format

The `credential` field you send to Quantum is the standard HTTP Basic credential: base64(`client_id:client_secret`). Encode it yourself before submitting. Do not include the `Basic ` prefix.

```bash
# Example: encoding a client_id and client_secret
echo -n "my_client_id:my_client_secret" | base64
# dXNlci1jbGllbnQ6c2VjcmV0LXZhbHVl
```

#### Security

- Your `credential` is stored encrypted at rest and is **never** returned by any API response.
- Cached Bearer tokens are invalidated automatically whenever you change the auth config via `PATCH`.
- If Quantum cannot acquire a token at delivery time (your token endpoint is down, returns an error, times out, etc.), it counts as a failed delivery attempt and the normal [retry policy](#retry-mechanism) applies.

See [Creating a Subscription with OAuth2 Bearer Token Auth](#creating-a-subscription-with-oauth2-bearer-token-auth) and [Updating Auth Configuration](#updating-auth-configuration) for how to enable, update, and revert this setting.

---

## Creating a Subscription

To start receiving webhooks, create a subscription by specifying your endpoint URL and the events you want to receive.

### Endpoint

```
POST /subscriptions
```

### Request

```bash
curl -X POST "$BASE_URL/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": [
      "application.created",
      "application.status.updated",
      "application.offer.created",
      "application.contract.signed",
      "application.funding.started"
    ],
    "num_retries": 3
  }'
```

> **Note:** `num_retries` is optional (0-6, defaults to 3).

### Response

```json
{
    "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": [
        "application.created",
        "application.status.updated",
        "application.offer.created",
        "application.contract.signed",
        "application.funding.started"
    ],
    "status": "active",
    "num_retries": 3,
    "secret": "whsec_xYz789AbCdEf...",
    "auth": null,
    "filter": {},
    "created": "2025-01-08T10:30:00Z"
}
```

> **Note:** `"filter": {}` means no filters are applied and all subscribed events are delivered. See [Filtering Events](#filtering-events) to narrow deliveries.

> **IMPORTANT:** The `secret` is only returned once during creation. Store it securely immediately - you will need it to verify webhook signatures. If you lose it, you'll need to refresh it (see [Refreshing Secrets](#refreshing-secrets)).

> **Note:** `"auth": null` means the subscription uses the default HMAC signature authentication. See [Webhook Delivery Authentication](#webhook-delivery-authentication).

### Requirements

- **URL must use HTTPS** - We only deliver webhooks to secure endpoints
- **Events array** - Must contain at least one valid event type
- **Retries** - Value between 0 and 6 (default: 3)
- **Filter** (optional) - Omit (or send `{}`) to deliver all subscribed events. See [Filtering Events](#filtering-events) to narrow deliveries per event type.
- **Auth** (optional) - Omit to use HMAC signature authentication (default). See [Creating a Subscription with OAuth2 Bearer Token Auth](#creating-a-subscription-with-oauth2-bearer-token-auth) to configure OAuth2 Bearer tokens.

### Creating a Subscription with OAuth2 Bearer Token Auth

To configure OAuth2 client credentials auth at creation time, include an `auth` block:

```bash
curl -X POST "$BASE_URL/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": [
      "application.created",
      "application.status.updated"
    ],
    "num_retries": 3,
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "https://auth.your-server.com/oauth2/token",
      "credential": "dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ="
    }
  }'
```

**`auth` fields:**

- `type` — one of `hmac_signature` (default) or `oauth2_client_credentials`
- `token_url` — your OAuth2 token endpoint URL (HTTPS). Required for `oauth2_client_credentials`.
- `credential` — base64-encoded `client_id:client_secret` Basic credential. Required for `oauth2_client_credentials`.

**Response:**

```json
{
    "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": ["application.created", "application.status.updated"],
    "status": "active",
    "num_retries": 3,
    "secret": "whsec_xYz789AbCdEf...",
    "auth": {
        "type": "oauth2_client_credentials",
        "token_url": "https://auth.your-server.com/oauth2/token"
    },
    "filter": {},
    "created": "2025-01-08T10:30:00Z"
}
```

> **IMPORTANT:** The `credential` you submitted is stored encrypted and **never** returned in any API response. If you lose your credential, you must issue a new one from your identity provider and update the subscription via `PATCH`.

See [Webhook Delivery Authentication](#webhook-delivery-authentication) for the full delivery flow and requirements for your token endpoint.

---

## Managing Subscriptions

### List Subscriptions

```bash
# Get all subscriptions with filters
curl -X GET "$BASE_URL/subscriptions?page=1&size=25&status=active&sort_by=created&sort_dir=desc" \
  -H "Authorization: Bearer $API_KEY"

# Returns: { results: [...], current_page, page_size, total_pages, total_items }
```

### Update a Subscription

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Update URL, events, retries, status, or filter
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks/v2/quantumlends",
    "events": [
      "application.created",
      "application.status.updated",
      "application.adverse_action.sent"
    ],
    "num_retries": 5,
    "status": "active",
    "filter": {
      "application.status.updated": { "status": "Declined" }
    }
  }'
```

> **Note:** `filter` follows replace semantics — see [Updating Filters](#updating-filters). Omit it to leave the current filters unchanged.

### Pause/Resume a Subscription

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Pause - temporarily stop receiving webhooks
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"status": "paused"}'

# Resume - start receiving webhooks again
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"status": "active"}'
```

### Updating Auth Configuration

Use `PATCH` to enable, change, or disable OAuth2 Bearer token auth for an existing subscription. The field follows three-way PATCH semantics:

- **Omit `auth`** — the current auth configuration is left unchanged
- **Send an `auth` object** — sets or replaces the auth configuration
- **Send `"auth": null`** — reverts the subscription to HMAC-only

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Add or update OAuth2 Bearer token auth
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "auth": {
      "type": "oauth2_client_credentials",
      "token_url": "https://auth.your-server.com/oauth2/token",
      "credential": "dGVzdF9jbGllbnQ6dGVzdF9zZWNyZXQ="
    }
  }'

# Revert to HMAC-only (remove OAuth2 auth)
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"auth": null}'
```

> **Note:** Any change to the `auth` configuration automatically invalidates the cached Bearer token, so new credentials or endpoint URLs take effect on the next delivery.

### Refreshing Secrets

If you lose your webhook secret or need to rotate it for security reasons:

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

curl -X POST "$BASE_URL/subscriptions/$SUBSCRIPTION_ID/refresh-secret" \
  -H "Authorization: Bearer $API_KEY"

# Response:
# {
#   "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
#   "secret": "whsec_newSecretHere...",
#   "previous_secret_valid_until": "2025-01-08T11:30:00Z"
# }
```

> **Grace Period:** After refreshing, both the old and new secrets are valid until `previous_secret_valid_until`. This allows you to update your server without missing webhooks.

---

## Event Types

Subscribe to any combination of these events:

| Event Type | Description |
|------------|-------------|
| `application.created` | A new application has been submitted |
| `application.updated` | Application data has been modified |
| `application.status.updated` | Application status has changed |
| `application.offer.created` | A loan offer has been generated |
| `application.offer.selected` | Customer has selected/accepted an offer |
| `application.offer.declined` | Customer has declined an offer |
| `application.contract.sent` | Contract documents have been sent |
| `application.contract.signed` | Contract has been signed |
| `application.funding.started` | Funding process has begun |
| `application.tasks.updated` | Application tasks have been updated |
| `application.document.status.updated` | Document status has changed |
| `application.document.uploaded` | A document has been uploaded |
| `application.additional_owner.profile.completed` | Additional owner profile completed |
| `application.adverse_action.sent` | Adverse action notice sent (decline) |
| `prefill_application.created` | A prefilled application has been created |
| `prefill_application.token_expired` | Applicant attempted to use an expired prefill link |

---

## Filtering Events

By default, a subscription delivers **every** event of each subscribed type. Filters let you narrow deliveries based on the event's data — so you only receive the events you actually care about, without adding filtering logic to your own endpoint.

A filter is an optional `filter` object on the subscription, keyed by event type. Each event type maps to a set of field conditions that an event must satisfy to be delivered.

> **Note:** **Initial release:** the only supported filter is `status` on the `application.status.updated` event. Conditions on any other field or event type are rejected. Event types you don't list in `filter` are always delivered unfiltered. The `filter` field shape is forward-compatible, so additional fields and event types can be added later without an API change.

### Example: Only Declined Status Updates

This subscription receives `application.status.updated` only when the application's new status is `Declined`. All `application.created` events are still delivered, because that event type is not present in the filter.

```bash
curl -X POST "$BASE_URL/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": [
      "application.created",
      "application.status.updated"
    ],
    "filter": {
      "application.status.updated": { "status": "Declined" }
    }
  }'
```

The `filter` is echoed back in the response:

```json
{
    "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "url": "https://your-server.com/webhooks/quantumlends",
    "events": ["application.created", "application.status.updated"],
    "status": "active",
    "num_retries": 3,
    "secret": "whsec_xYz789AbCdEf...",
    "auth": null,
    "filter": {
        "application.status.updated": { "status": "Declined" }
    },
    "created": "2025-01-08T10:30:00Z"
}
```

### Condition Semantics

- **Scalar value = equals** — `{ "status": "Declined" }` matches only when the status equals `Declined`.
- **List value = in (OR)** — `{ "status": ["Declined", "Withdrawn"] }` matches when the status is **any** of the listed values.
- **Multiple fields = AND** — when an event type maps to more than one field, an event must satisfy **all** of them.
- **Case-insensitive** — values are compared case-insensitively (`"declined"` and `"Declined"` behave identically). Examples use the Title Case form from the [Application Statuses](#application-statuses) table.
- **Absent event types pass through** — any subscribed event type not listed in `filter` is delivered unfiltered.
- **Empty filter delivers everything** — omitting `filter` or sending `{}` delivers all subscribed events.

> **Note:** With only `status` on `application.status.updated` supported in this release, the list (OR) and multi-field (AND) forms describe how filters will behave as more fields become available.

### Delivery Behavior

When an event does not match a subscription's filter, it is **silently skipped** for that subscription — no delivery is attempted and nothing appears in that subscription's [delivery history](#checking-event-delivery-status).

The underlying event is **still recorded** and remains queryable via [List Events](#events). Filtering affects *delivery*, not whether the event occurred.

### Validation

Invalid filters are rejected at create/update time with a `422` response. A filter is invalid when it contains:

- a key for an event type that is **not** in the subscription's `events` array
- a key for an event type that does **not support filtering** (anything other than `application.status.updated` in this release)
- an **unknown field** name (anything other than `status` for `application.status.updated`)
- a **non-string** condition value (values must be a string or a list of strings)

### Updating Filters

`filter` uses replace semantics on `PATCH`:

- **Omit `filter`** — the current filters are left unchanged
- **Send a `filter` object** — replaces the entire stored filter map
- **Send `"filter": {}`** — clears all filters (delivers all subscribed events again)

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Replace filters
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "filter": {
      "application.status.updated": { "status": "Declined" }
    }
  }'

# Clear all filters
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"filter": {}}'
```

> **Note:** If you change `events` and `filter` in the same request, the new filter is validated against the new event list. Removing an event type from `events` while still filtering on it returns a `422`.

---

## Application Lifecycle

### Happy Path (Approved Application)

```
application.created
        │
        ▼
application.status.updated → "In Processing"
        │
        ▼
application.tasks.updated  ◄── New task: upload bank statements
        │
        ▼
application.document.uploaded  ◄── Customer uploads bank statements
        │
        ▼
application.document.status.updated  ◄── UW team approves document
        │
        ▼
application.tasks.updated  ◄── Task completed
        │
        ▼
application.status.updated → "Under Credit Review"
        │
        ▼
application.status.updated → "Approved"
        │
        ▼
application.offer.created
        │
        ▼
application.status.updated → "Awaiting Offer Acceptance"
        │
        ▼
application.offer.selected  ◄── Customer accepts the offer
        │
        ▼
application.status.updated → "Preparing Loan Documents"
        │
        ▼
application.status.updated → "Pending Closing Information from Customer"
        │
        ▼
application.tasks.updated  ◄── New tasks: upload additional documents
        │
        ▼
application.document.uploaded  ◄── Customer uploads documents (may repeat)
        │
        ▼
application.document.status.updated  ◄── Documents accepted
        │
        ▼
application.tasks.updated  ◄── Tasks completed
        │
        ▼
application.contract.sent
        │
        ▼
application.status.updated → "Awaiting Document Execution"
        │
        ▼
application.contract.signed
        │
        ▼
application.status.updated → "Awaiting Funding"
        │
        ▼
application.funding.started
        │
        ▼
application.status.updated → "Booked"  ◄── Loan funded, process complete
```

### Offer Declined by Customer Path

```
application.created
        │
        ▼
application.status.updated → "In Processing"
        │
        ▼
application.tasks.updated  ◄── New task: upload bank statements
        │
        ▼
application.document.uploaded  ◄── Customer uploads bank statements
        │
        ▼
application.document.status.updated  ◄── UW team approves document
        │
        ▼
application.tasks.updated  ◄── Task completed
        │
        ▼
application.status.updated → "Under Credit Review"
        │
        ▼
application.status.updated → "Approved"
        │
        ▼
application.offer.created
        │
        ▼
application.status.updated → "Awaiting Offer Acceptance"
        │
        ▼
application.offer.declined  ◄── Customer declines the offer
        │
        ▼
application.status.updated → "Offer Declined"
```

### Application Declined by Lender Path

```
application.created
        │
        ▼
application.status.updated → "In Processing"
        │
        ▼
application.tasks.updated  ◄── New task: upload bank statements
        │
        ▼
application.document.uploaded  ◄── Customer uploads bank statements
        │
        ▼
application.document.status.updated  ◄── UW team approves document
        │
        ▼
application.tasks.updated  ◄── Task completed
        │
        ▼
application.status.updated → "Under Credit Review"
        │
        ▼
application.status.updated → "Declined"
        │
        ▼
application.adverse_action.sent  ◄── Adverse action notice sent (daily 9 pm ET batch)
```

### Application Statuses

| Status | Description |
|--------|-------------|
| `submitted` | Initial submission |
| `In Processing` | Being processed |
| `Under Credit Review` | Credit evaluation in progress |
| `Approved` | Approved for an offer |
| `Awaiting Offer Acceptance` | Waiting for customer to accept offer |
| `Preparing Loan Documents` | Documents being prepared |
| `Pending Closing Information from Customer` | Awaiting customer additional info |
| `Awaiting Document Execution` | Waiting for document signatures |
| `Awaiting Funding` | Ready for funding |
| `Booked` | Loan funded and complete |
| `Declined` | Application declined |
| `Offer Declined` | Customer declined the offer |
| `Withdrawn` | Application withdrawn |

---

## Receiving Webhooks

When an event occurs, we send an HTTP POST request to your subscription URL.

### Webhook Payload Structure

```json
{
    "id": "705bee34-9578-4bf9-b654-d036294f8efc",
    "type": "application.offer.created",
    "occurred_at": "2026-01-12T20:36:24.217Z",
    "resource": {
        "id": "88c911f7-1a59-4860-b786-825c9b45bc1b",
        "type": "application"
    },
    "links": {
        "event_url": "https://qa.quantumlends.com/api/v3/webhooks/event-delivery-history/705bee34-9578-4bf9-b654-d036294f8efc",
        "resource_url": "https://qa.quantumlends.com/api/v3/applications/88c911f7-1a59-4860-b786-825c9b45bc1b/offers"
    }
}
```

| Field | Description |
|-------|-------------|
| `id` | Unique UUID for this event |
| `type` | The event type (e.g., `application.offer.created`) |
| `occurred_at` | ISO 8601 timestamp when the event occurred |
| `resource.id` | UUID of the affected resource (e.g., application ID) |
| `resource.type` | Type of resource (e.g., `application`) |
| `links.event_url` | URL to fetch event delivery details |
| `links.resource_url` | URL to fetch the affected resource |

### Headers Sent with Webhooks

HMAC signature headers are present on **every** delivery. The `Authorization` header is additionally present when the subscription is configured with OAuth2 client credentials auth (see [Webhook Delivery Authentication](#webhook-delivery-authentication)).

| Header | Description |
|--------|-------------|
| `Content-Type` | `application/json` |
| `x-quantum-event-id` | Unique UUID of the event |
| `x-quantum-event-type` | The event type (e.g., `application.offer.created`) |
| `x-quantum-signature` | Signature for verification (see below) |
| `Authorization` | `Bearer <token>` — only when OAuth2 client credentials auth is configured |

---

## Signature Verification

**Always verify webhook signatures** to ensure requests are genuinely from Quantum and haven't been tampered with.

### Signature Format

The `x-quantum-signature` header contains:

```
t=1768250184, v1=ec18e1eb555bc335c447c7057467c215732edf68ee0c332c6db0bd44848b1918
```

- `t` - Unix timestamp when the webhook was sent
- `v1` - HMAC-SHA256 signature

### Verification Implementation (FastAPI)

```python
import hashlib
import hmac
import time

from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

WEBHOOK_SECRET = "whsec_your_secret_here"
MAX_TIMESTAMP_AGE_SECONDS = 300  # 5 minutes


def verify_webhook_signature(
    secret: str,
    signature_header: str,
    payload: str,
    max_timestamp_age: int = MAX_TIMESTAMP_AGE_SECONDS,
) -> bool:
    """
    Verify HMAC-SHA256 signature from a webhook request.

    Args:
        secret: Your webhook secret (e.g., whsec_abc123...)
        signature_header: Value of x-quantum-signature header
        payload: Raw request body as a string (not parsed JSON)
        max_timestamp_age: Maximum age in seconds (default: 300)

    Returns:
        True if signature is valid, False otherwise
    """
    try:
        # 1. Parse signature header
        parts = {}
        for part in signature_header.split(","):
            key, value = part.strip().split("=", 1)
            parts[key.strip()] = value.strip()

        timestamp = int(parts["t"])
        received_signature = parts["v1"]

        # 2. Validate timestamp to prevent replay attacks
        current_time = int(time.time())
        timestamp_age = current_time - timestamp

        if timestamp_age > max_timestamp_age:
            return False  # Too old
        if timestamp_age < -max_timestamp_age:
            return False  # Too far in future

        # 3. Compute expected signature
        signing_string = f"{timestamp}.{payload}"
        expected_signature = hmac.new(
            secret.encode("utf-8"),
            signing_string.encode("utf-8"),
            hashlib.sha256,
        ).hexdigest()

        # 4. Compare using constant-time comparison
        return hmac.compare_digest(expected_signature, received_signature)

    except (KeyError, ValueError, TypeError):
        return False


@app.post("/webhook")
async def receive_webhook(request: Request):
    """Receive and verify webhook from Quantum."""
    # Get signature header
    signature_header = request.headers.get("x-quantum-signature", "")
    if not signature_header:
        raise HTTPException(status_code=401, detail="Missing signature")

    # Get raw payload as string for signature verification
    payload = (await request.body()).decode("utf-8")

    # Verify signature
    if not verify_webhook_signature(WEBHOOK_SECRET, signature_header, payload):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Parse the event
    event = await request.json()
    event_type = event.get("type")
    resource_id = event["resource"]["id"]

    # Handle different event types
    if event_type == "application.created":
        print(f"New application: {resource_id}")
    elif event_type == "application.status.updated":
        print(f"Application {resource_id} status changed")
    elif event_type == "application.offer.created":
        print(f"Offer created for application: {resource_id}")
    elif event_type == "application.offer.selected":
        print(f"Offer selected for application: {resource_id}")
    elif event_type == "application.offer.declined":
        print(f"Offer declined for application: {resource_id}")
    elif event_type == "application.adverse_action.sent":
        print(f"Adverse action notice sent for application: {resource_id}")
    elif event_type == "prefill_application.created":
        print(f"Prefill application created: {resource_id}")
    elif event_type == "prefill_application.token_expired":
        print(f"Prefill token expired for application: {resource_id}")
    # ... handle other events

    # Fetch additional details if needed using links.resource_url
    resource_url = event["links"]["resource_url"]

    return {"status": "received"}
```

---

## Retry Mechanism

If your endpoint fails to respond with a `2xx` status code, we'll retry the delivery.

### Retry Behavior

- **Retries:** Configurable from 0 to 6 attempts (default: 3)
- **Backoff:** Exponential backoff between retries
- **Timeout:** Your endpoint should respond within 30 seconds

### Checking Event Delivery Status

```bash
# List event deliveries with filters
curl -X GET "$BASE_URL/event-delivery-history?subscription_id=c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f&success=false&event_type=application.status.updated&event_id=a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b&start_date=2025-01-01&end_date=2025-01-08" \
  -H "Authorization: Bearer $API_KEY"
```

### Get Event Delivery Details with Retry History

```bash
DELIVERY_ID="b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"

curl -X GET "$BASE_URL/event-delivery-history/$DELIVERY_ID" \
  -H "Authorization: Bearer $API_KEY"

# Includes delivery_attempts array with all delivery attempts
```

### Manual Retry

If automatic retries are exhausted, you can manually retry:

```bash
DELIVERY_ID="b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"

curl -X POST "$BASE_URL/event-delivery-history/$DELIVERY_ID/retry" \
  -H "Authorization: Bearer $API_KEY"
```

---

## Events

Source events allow you to query the original events that occurred in the system, independent of how they were delivered to your subscriptions.

### List Events

```bash
# List events with filters
curl -X GET "$BASE_URL/events?page=1&size=25&event_type=application.offer.created&resource_type=application&resource_id=88c911f7-1a59-4860-b786-825c9b45bc1b&start_date=2025-01-01&end_date=2025-01-08" \
  -H "Authorization: Bearer $API_KEY"

# Returns: { results: [...], current_page, page_size, total_pages, total_items }
```

### Event Response

```json
{
    "id": "a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b",
    "event_type": "application.offer.created",
    "resource_type": "application",
    "resource_id": "88c911f7-1a59-4860-b786-825c9b45bc1b",
    "received_at": "2025-01-08T10:30:00Z",
    "delivery_count": 2,
    "links": {
        "deliveries_url": "https://qa.quantumlends.com/api/v3/webhooks/event-delivery-history?source_event_id=a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b"
    }
}
```

### Get Event Details

Retrieve detailed information about an event, including all its deliveries:

```bash
EVENT_ID="a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b"

curl -X GET "$BASE_URL/events/$EVENT_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Event Detail Response

```json
{
    "id": "a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b",
    "event_type": "application.offer.created",
    "resource_type": "application",
    "resource_id": "88c911f7-1a59-4860-b786-825c9b45bc1b",
    "received_at": "2025-01-08T10:30:00Z",
    "delivery_count": 2,
    "deliveries": [
        {
            "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
            "subscription_id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
            "attempt_number": 1,
            "http_status": 200,
            "response_time_ms": 145,
            "success": true,
            "delivered_at": "2025-01-08T10:30:01Z",
            "error_message": null
        }
    ],
    "links": {
        "deliveries_url": "https://qa.quantumlends.com/api/v3/webhooks/event-delivery-history?source_event_id=a8d4e2f1-3b5c-4a6d-9e8f-1c2d3e4f5a6b"
    }
}
```

### Use Cases for Events

1. **Debugging delivery issues** - Find the event and see all delivery attempts across subscriptions
2. **Audit trail** - Query what events occurred for a specific application
3. **Reconciliation** - Verify that all expected events were generated

---

## Best Practices

### 1. Store Your Secret Securely

```bash
# Use environment variables - NEVER hardcode secrets
export QUANTUMLENDS_WEBHOOK_SECRET="whsec_your_secret_here"

# Or use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
```

### 2. Respond Quickly

Return a `200` response immediately, then process the event asynchronously:

```python
from threading import Thread


@app.route("/webhooks/quantumlends", methods=["POST"])
def handle_webhook():
    # Verify signature first
    if not verify_signature():
        return "", 401

    event = request.get_json()

    # Process asynchronously
    Thread(target=process_event, args=(event,)).start()

    # Return immediately
    return "", 200


def process_event(event):
    # Do the actual processing here
    # Database updates, notifications, etc.
    pass
```

### 3. Handle Duplicate Events

Events may occasionally be delivered more than once. Make your handlers idempotent:

```python
def handle_application_created(event):
    event_id = event["id"]

    # Check if we've already processed this event
    if event_already_processed(event_id):
        return

    # Process the event
    create_application_record(event)

    # Mark as processed
    mark_event_processed(event_id)
```

### 4. Subscribe Only to Events You Need

Reduces noise and processing overhead:

```bash
# Good - specific events
curl -X POST "$BASE_URL/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "events": [
      "application.created",
      "application.status.updated",
      "application.funding.started"
    ]
  }'

# Avoid subscribing to all events if you don't need them
```

### 5. Monitor Webhook Health

Regularly check your event delivery success rate:

```bash
# Check for failed deliveries in the last 24 hours
curl -X GET "$BASE_URL/event-delivery-history?success=false&start_date=$(date -u -v-1d +%Y-%m-%d)" \
  -H "Authorization: Bearer $API_KEY"

# If total_items > 0, investigate the failures
```

### 6. Use Pause During Maintenance

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Before maintenance - pause the subscription
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"status": "paused"}'

# Perform maintenance...

# After maintenance - resume the subscription
curl -X PATCH "$BASE_URL/subscriptions/$SUBSCRIPTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"status": "active"}'
```

### 7. Rotate Secrets Periodically

```bash
SUBSCRIPTION_ID="c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"

# Refresh the secret
curl -X POST "$BASE_URL/subscriptions/$SUBSCRIPTION_ID/refresh-secret" \
  -H "Authorization: Bearer $API_KEY"

# Response contains:
# - secret: The new webhook secret
# - previous_secret_valid_until: Grace period expiration
#
# Update your secret store with the new secret immediately
```

---

## Quick Reference

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/subscriptions` | Create subscription |
| `GET` | `/subscriptions` | List subscriptions |
| `PATCH` | `/subscriptions/{id}` | Update subscription |
| `POST` | `/subscriptions/{id}/refresh-secret` | Rotate secret |
| `GET` | `/events` | List events |
| `GET` | `/events/{id}` | Get event details |
| `GET` | `/event-delivery-history` | List event deliveries |
| `GET` | `/event-delivery-history/{id}` | Get event delivery details |
| `POST` | `/event-delivery-history/{id}/retry` | Retry failed delivery |

### Response Codes

| Code | Meaning |
|------|---------|
| `200` | Success |
| `201` | Created |
| `400` | Bad request (invalid parameters) |
| `401` | Unauthorized (invalid/missing API key) |
| `404` | Resource not found |
| `422` | Validation error |
| `500` | Server error |
| `502` | Bad gateway — OAuth2 token fetch from your token endpoint failed (manual retry endpoint only) |

---

## Support

If you encounter issues with the webhook integration, please contact your Quantum partner representative or reach out to our technical support team.

---

# API Reference (structured summary)

> Quantum Lending Solutions Partner API · version 3.0.0
> Full machine-readable schema: https://docs.quantumlends.com/merged-api.json

## Applications

### GET /api/v3/applications
List Applications
List all applications for your account with optional filtering and pagination. Returns a paginated list of applications sorted by the submitted date.

Parameters:
- `page` (query, integer)
- `limit` (query, integer)
- `sort_direction` (query, string)
- `statuses` (query, array<string>)
- `reference_ids` (query, string | null)
- `ids` (query, string | null)

Responses:
- 200: ApplicationListResponse — OK
- 403: ForbiddenErrorSchema — Forbidden
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/applications/{app_id}
Retrieve an Application
Get a loan application that was previously created using the unique identifier that was generated. For applications with a status of 'Declined' or 'Offer Declined', the response includes a 'decision' field containing information about why the application was not approved. This includes business-rela

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: ApplicationWithDecisionOut — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found

### GET /api/v3/applications/{app_id}/adverse-action-notification
Get adverse action notification PDF
Get the adverse action notification PDF for a given application id.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: string — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found

### POST /api/v3/applications/{app_id}/bank-accounts
Add Bank Accounts
Add bank accounts to an application after initial submission. Supports both aggregator-based accounts (Plaid/MX) for transaction analysis and direct-from-customer accounts for loan disbursement. Only one direct-from-customer account is allowed per request.

Parameters:
- `app_id` (path, string) (required)

Request body (required): application/json → array<DirectFromCustomerBankAccountInput | AggregatorBankAccountInput>

Responses:
- 200: AddBankAccountsResponse — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity
- 510: MessageSchema — Not Extended

### GET /api/v3/applications/{app_id}/contracts
Get embedded contract signing tokens for an application
Returns the list of signers on the application's contract along with a `signing_token` for each. The token is an opaque value to be passed to the Quantum-wrapped embedded signing JS SDK to drive the embedded signing experience. The contract must already have been sent for signers to be available.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: ContractsResponseSchema — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 410: ErrorMessageSchema — Gone
- 510: ErrorMessageSchema — Not Extended

### POST /api/v3/applications/{app_id}/decline-offers
Decline offers
Decline offers for a given application id with a reason.

Parameters:
- `app_id` (path, string) (required)

Request body: application/json → DeclineOfferRequest | null

Responses:
- 200: MessageSchema — OK
- 400: MessageSchema — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/applications/{app_id}/documents
Get supporting documents info
Get the documents info for a given application id.  It's also useful to track the status of the documents uploaded.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: DocumentList — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found

### POST /api/v3/applications/{app_id}/documents
Upload supporting documents
Upload documents for an application. Documents can be uploaded using individual parameters for each document type: bank_statements, business_tax_return, personal_tax_return, ytd_financials, ye_financials, debt_schedule, photo_id, utility_bill, lease_agreement, business_license, sos_record, lien_rele

Parameters:
- `app_id` (path, string) (required)

Request body (required): multipart/form-data → object

Responses:
- 201: DocumentList — Created
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity
- 510: ErrorMessageSchema — Not Extended

### POST /api/v3/applications/{app_id}/offer/{offer_id}/accept
Accept an offer
Accept an offer for a given application id.

Parameters:
- `app_id` (path, string) (required)
- `offer_id` (path, string) (required)

Responses:
- 200: MessageSchema — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/applications/{app_id}/offers
Get offers
Get the offers for a given application id.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: Offers — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/applications/{app_id}/offers/{offer_id}/disclosure
Get commercial financing disclosure PDF
Get the commercial financing disclosure PDF for a given application id and offer id.

Parameters:
- `app_id` (path, string) (required)
- `offer_id` (path, string) (required)

Responses:
- 200: string — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found

### POST /api/v3/applications/{app_id}/owners
Add Additional Owners
Add additional owners to an application after initial submission. This endpoint is typically used when you initially submit an application with only the primary owner and need to add additional owners once their information is collected. Applications must not be in a terminal status (Declined, Booke

Parameters:
- `app_id` (path, string) (required)

Request body (required): application/json → array<AdditionalOwnerIn>

Responses:
- 200: AddAdditionalOwnersResponse — OK
- 400: MessageSchema — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/applications/{app_id}/prefill
Get Application Prefill Link
Returns the prefill URL and token for a previously created prefill application. Use the returned `prefill_url` to send the applicant directly to their pre-filled application form. If the original link has expired, a new one is automatically issued.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: PrefillTokenOut — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 510: ErrorMessageSchema — Not Extended

### GET /api/v3/applications/{app_id}/signed-disclosure
Get signed disclosure PDF
Get the signed disclosure PDF for a given application id.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: string — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found

### GET /api/v3/applications/{app_id}/status
Get Application Status
Get the current status of an application by its UUID.

Parameters:
- `app_id` (path, string) (required)

Responses:
- 200: ApplicationStatusOut — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 510: ErrorMessageSchema — Not Extended

### GET /api/v3/applications/{app_id}/tasks
Get application tasks
Get all tasks for an application. Use show_details=true to include actions for each task.

Parameters:
- `app_id` (path, string) (required)
- `status` (query, TaskStatus | null)
- `show_details` (query, boolean | null)

Responses:
- 200: array<TaskSchema> | array<TaskDetailSchema> — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 500: MessageSchema — Internal Server Error

### GET /api/v3/applications/{app_id}/tasks/{task_id}
Get application task details
Get detailed information about a specific task, including all available actions that can be taken to complete it.

Parameters:
- `app_id` (path, string) (required)
- `task_id` (path, string) (required)

Responses:
- 200: TaskDetailSchema — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 500: MessageSchema — Internal Server Error

### POST /api/v3/applications/{app_id}/transactions
Add transaction data
Add transaction data for an application. The request body is a discriminated-union envelope keyed on ``type``. Today supports ``plaid_asset_report``; additional source types may be added over time.

Parameters:
- `app_id` (path, string) (required)

Request body (required): application/json → PlaidAssetReportEnvelope

Responses:
- 200: IngestTransactionsResponse — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 409: MessageSchema — Conflict
- 422: ValidationErrorSchema — Unprocessable Entity
- 510: MessageSchema — Not Extended

### POST /api/v3/applications/{app_id}/withdraw
Withdraw Application
Withdraw an application by marking it as reversed.

Parameters:
- `app_id` (path, string) (required)

Request body (required): application/json → WithdrawRequest

Responses:
- 200: ApplicationWithdrawnSucessSchema — OK
- 400: ApplicationNotWithdrawnErrorSchema — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 404: applications__schemas__errors__NotFoundErrorSchema__2 — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### POST /api/v3/applications/prefill
Prefill an Application
Create a prefilled application with minimal owner data. Returns a URL for the applicant to continue the application.

Request body (required): application/json → PrefillApplication

Responses:
- 201: PrefillApplicationOut — Created
- 400: ValidationErrorSchema — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 422: ValidationErrorSchema — Unprocessable Entity
- 510: ErrorMessageSchema — Not Extended

### POST /api/v3/applications/submit
Submit an Application
Submit a loan application for review. The submit will identify any issues with the loan application such as missing fields.

Parameters:
- `X-Forwarded-For` (header, string | null)

Request body (required): application/json → Application

Responses:
- 201: ApplicationOut — Created
- 400: ValidationErrorSchema — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 422: ValidationErrorSchema — Unprocessable Entity
- 510: MessageSchema — Not Extended

## Accounts

These endpoints allow you to:
- Request draws from existing lines of credit
- Submit payment requests for loan repayment
- Manage account servicing operations

All operations are processed asynchronously with status updates sent via webhooks.

### GET /api/v3/accounts/{account_id}
Get account details by ID
Retrieve detailed information about a specific account including balances, status, and account terms.

Parameters:
- `account_id` (path, string) (required)

Responses:
- 200: FBLoan | IBLoan | TermLoan — OK
- 400: QuantumException — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/amortizations
Get account amortizations by account id
Retrieve a list of amortizations for a specific account with filtering and pagination.

Parameters:
- `account_id` (path, string) (required)
- `start_date` (query, string | null)
- `end_date` (query, string | null)
- `page` (query, integer)
- `size` (query, integer)

Responses:
- 200: PagedAmortization — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/draw-requests
List draw requests for an account
Retrieve a paginated list of draw requests for a specific account with optional status filtering and sorting.

Parameters:
- `account_id` (path, string) (required)
- `status` (query, array<DrawRequestStatus> | null)
- `page` (query, integer)
- `size` (query, integer)
- `sort_by` (query, string)
- `sort_dir` (query, string)

Responses:
- 200: PagedDrawRequest — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### POST /api/v3/accounts/{account_id}/draw-requests
Request a draw from a line of credit
Submit a draw request for a specific account. This endpoint allows you to request funds from an existing line of credit on behalf of your customers.  The request will be processed asynchronously and status updates will be sent via webhooks to the draw status endpoint.

Parameters:
- `account_id` (path, string) (required)

Request body (required): application/json → DrawRequestInput

Responses:
- 201: DrawRequestOutput — Created
- 400: QuantumException — Bad Request
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/draw-requests/{draw_request_id}
Get draw request details
Retrieve details about a specific draw request including status, amount, and fees.

Parameters:
- `account_id` (path, string) (required)
- `draw_request_id` (path, string) (required)

Responses:
- 200: DrawRequestOutput — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/payment-requests
List payment requests for an account
Retrieve a paginated list of payment requests for a specific account with optional status filtering.

Parameters:
- `account_id` (path, string) (required)
- `status` (query, array<PaymentRequestStatus> | null)
- `page` (query, integer)
- `size` (query, integer)

Responses:
- 200: PagedPaymentRequest — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### POST /api/v3/accounts/{account_id}/payment-requests
Make a payment towards an account
Submit a payment request for a specific account. This endpoint allows you to process payments on behalf of your customers for loan repayment, payoff, or past due amounts.  The payment will be processed asynchronously and status updates will be sent via webhooks to the repayment status endpoint.

Parameters:
- `account_id` (path, string) (required)

Request body (required): application/json → PaymentRequestInput

Responses:
- 201: PaymentRequestOutput — Created
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/payment-requests/{payment_request_id}
Get payment request details
Retrieve details about a specific payment request including status and amount.

Parameters:
- `account_id` (path, string) (required)
- `payment_request_id` (path, string) (required)

Responses:
- 200: PaymentRequestOutput — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

### GET /api/v3/accounts/{account_id}/transactions
Get account transactions by account ID
Retrieve a list of transactions for a specific account with filtering and pagination.

Parameters:
- `account_id` (path, string) (required)
- `start_date` (query, string | null)
- `end_date` (query, string | null)
- `transaction_type` (query, TransactionType | null)
- `page` (query, integer)
- `size` (query, integer)

Responses:
- 200: PagedTransaction — OK
- 403: ForbiddenErrorSchema — Forbidden
- 404: QuantumException — Not Found
- 422: ValidationErrorSchema — Unprocessable Entity

## Subscriptions

### GET /api/v3/webhooks/subscriptions
List webhook subscriptions
List all webhook subscriptions for the authenticated partner with pagination support. Supports filtering by status and events, and sorting by created, modified, or status.

Parameters:
- `page` (query, integer)
- `size` (query, integer)
- `status` (query, WebhookSubscriptionStatus | null)
- `events` (query, WebhookTopic | null)
- `sort_by` (query, string | null)
- `sort_dir` (query, string)

Responses:
- 200: WebhookSubscriptionListResponse — OK
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 500: InternalErrorResponse — Internal Server Error

### POST /api/v3/webhooks/subscriptions
Create a webhook subscription
Create a new webhook subscription for the authenticated partner. The secret is only shown once at creation time.

Request body (required): application/json → CreateWebhookSubscriptionRequest

Responses:
- 201: WebhookSubscriptionResponse — Created
- 400: BadRequestErrorResponse — Bad Request
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 422: ValidationErrorResponse — Unprocessable Entity
- 500: InternalErrorResponse — Internal Server Error

### PATCH /api/v3/webhooks/subscriptions/{subscription_uuid}
Update a webhook subscription
Update an existing webhook subscription. Only provided fields will be updated (partial update). The secret cannot be changed and is not returned in the response.

Parameters:
- `subscription_uuid` (path, string) (required)

Request body (required): application/json → UpdateWebhookSubscriptionRequest

Responses:
- 200: WebhookSubscriptionUpdateResponse — OK
- 400: BadRequestErrorResponse — Bad Request
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 404: NotFoundErrorResponse — Not Found
- 422: ValidationErrorResponse — Unprocessable Entity
- 500: InternalErrorResponse — Internal Server Error

### POST /api/v3/webhooks/subscriptions/{subscription_uuid}/refresh-secret
Refresh webhook subscription secret
Generate a new secret for a webhook subscription. The previous secret remains valid during the grace period to allow for seamless rotation.

Parameters:
- `subscription_uuid` (path, string) (required)

Responses:
- 200: SecretRefreshResponse — OK
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 404: NotFoundErrorResponse — Not Found
- 500: InternalErrorResponse — Internal Server Error

## Events

### GET /api/v3/webhooks/events
List events
List webhook events for the authenticated partner with filtering and pagination. Events represent the original webhook events received (deduplicated view). Events are sorted by received_at descending (newest first). Maximum retention window is 30 days.

Parameters:
- `page` (query, integer)
- `size` (query, integer)
- `event_type` (query, WebhookTopic | null)
- `resource_type` (query, string | null)
- `resource_id` (query, string | null)
- `start_date` (query, string | null)
- `end_date` (query, string | null)

Responses:
- 200: SourceEventListResponse — OK
- 400: BadRequestErrorResponse — Bad Request
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 500: InternalErrorResponse — Internal Server Error

### GET /api/v3/webhooks/events/{id}
Get event details
Get details of a specific event including all delivery attempts. Only events delivered to subscriptions owned by the authenticated partner can be accessed.

Parameters:
- `id` (path, string) (required)

Responses:
- 200: SourceEventDetailResponse — OK
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 404: NotFoundErrorResponse — Not Found
- 500: InternalErrorResponse — Internal Server Error

## Webhook delivery

### GET /api/v3/webhooks/event-delivery-history
List webhook delivery history
List webhook delivery attempts for the authenticated partner with filtering and pagination. Deliveries are sorted by delivered_at descending (newest first). Maximum retention window is 30 days.

Parameters:
- `page` (query, integer)
- `size` (query, integer)
- `subscription_id` (query, string | null)
- `event_type` (query, WebhookTopic | null)
- `status_code` (query, integer | null)
- `success` (query, boolean | null)
- `resource_type` (query, string | null)
- `resource_id` (query, string | null)
- `source_event_id` (query, string | null)
- `start_date` (query, string | null)
- `end_date` (query, string | null)

Responses:
- 200: WebhookEventListResponse — OK
- 400: BadRequestErrorResponse — Bad Request
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 500: InternalErrorResponse — Internal Server Error

### GET /api/v3/webhooks/event-delivery-history/{id}
Get webhook delivery details
Get details of a specific webhook delivery attempt. Only deliveries for subscriptions owned by the authenticated partner can be accessed. The ID corresponds to the 'id' field in the webhook payload received by partners.

Parameters:
- `id` (path, string) (required)

Responses:
- 200: WebhookEventDetailResponse — OK
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 404: NotFoundErrorResponse — Not Found
- 500: InternalErrorResponse — Internal Server Error

### POST /api/v3/webhooks/event-delivery-history/{id}/retry
Manually retry webhook delivery
Manually retry a webhook delivery. Executes synchronously and returns the partner's response. Cannot retry if subscription is paused or disabled. The ID corresponds to the 'id' field in the webhook payload received by partners.

Parameters:
- `id` (path, string) (required)

Responses:
- 200: ManualRetryResponse — OK
- 401: UnauthorizedErrorResponse — Unauthorized
- 403: ForbiddenErrorResponse — Forbidden
- 404: NotFoundErrorResponse — Not Found
- 409: ConflictErrorResponse — Conflict
- 500: InternalErrorResponse — Internal Server Error

## Security Schemes

- `QuantumAuthMiddleware`: http/bearer