SMB Loan Application API
Submit and update loan applications for small and medium-sized businesses. Process applications from $25,000 to $500,000 with real-time qualification decisions.
Overview
Key Features
- Real-time pre-qualification and approval decisions
- Support for multiple business types and loan purposes
- Comprehensive validation of business and owner information
- Incremental data submission via PUT updates
- Test modes for simulating declines and errors
Authentication & Environments
All API requests require a Bearer token for authentication. Each environment has its own API key. The base URL remains the same for both.
| Environment | Description |
|---|---|
Sandbox |
For development and testing. Supports special test cases. |
Production |
Live environment. Real applications and underwriting. |
Same URL, Different Keys
Use the same base URL (https://api.embed.mkiii.ai) for both environments.
Your API key determines which environment processes the request.
Application Lifecycle
Applications progress through the following statuses:
| Status | Description | Terminal |
|---|---|---|
| prequal | Preliminary offer based on partial information. Rates are indicative only and subject to change. | No |
| approved | Rates are approved for funding and the loan can proceed at the specified terms. Lending Service Provider (LSP) must separately ensure all required information is present and verified per the specifications in the Program Manager Agreement and associated insurance policy. | No |
| ineligible | Application does not meet underwriting criteria. | No |
| declined |
Owner credit evaluation failed. This is a permanent decision—the application
cannot be modified. A new application with a new externalId must be
submitted.
|
Yes |
| funded | Loan has been funded. This status is triggered when we receive funding information via the funding report, which is typically shared as a CSV file via SFTP. Once marked as funded, the application cannot be modified. | Yes |
| withdrawn |
Application was not funded within 30 days from the initial application creation
and has been automatically withdrawn. Application cannot be modified. A new
application with a new externalId must be submitted for the same
business.
|
Yes |
Terminal vs Non-Terminal Statuses
Non-terminal statuses (prequal, approved,
ineligible) can change as you update the application with new data.
Terminal statuses (declined, funded, withdrawn)
are permanent—once an application reaches a terminal status, it cannot be modified via
PUT using the externalId or system-generated id. Any update
attempts will return a 409 Conflict error. To submit a new application for the same
business, you must use a new, unique externalId.
Quick Start
This example demonstrates a typical integration flow: create an application with minimal data to get a pre-qualification, add additional owners, then provide the remaining required fields to reach approved status.
Step 1: Create Application
Submit the initial application with basic business and owner information to receive a pre-qualification decision.
Step 2: Add Additional Owners
Use PUT to add more owners or update existing ones. You can reference the application by
either the system-generated id or your externalId. The
ownerApplicants array in the request is the full list of owners you want on
the application—any previously added owner you omit will be removed. Include all owners
who should remain, plus any new ones.
Step 3: Complete for Approved
Provide all remaining required fields to reach approved status. Once approved, rates are confirmed and the loan can proceed at the specified terms. Service Provider (LSP) must separately ensure all required information is present and verified per the specifications in the Program Manager Agreement and associated insurance policy.
Create Application
| Property | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Authorization | Bearer mk3_00000000-0000-0000-0000-000000000000 |
Removing Values
When updating an application, to explicitly remove a previously submitted value, set
it to
null. Removing required data may change the application status—for
example, removing fields required for approved status will move the
application back to prequal or ineligible.
Update Application
| Property | Value |
|---|---|
| Method | PUT |
| Content-Type | application/json |
| Authorization | Bearer mk3_00000000-0000-0000-0000-000000000000 |
The {id} path parameter accepts either:
-
The system-generated application ID (e.g.,
SMB_01JZR8WRCSRGT0X85S4Q7HN5K5) - Your provided
externalId(e.g.,your-app-123)
Data Handling
Null vs Zero/Empty String
When submitting data, the distinction between null and explicit values like
0 or "" is significant:
| Value | Meaning |
|---|---|
null |
Data has not been provided |
0 |
The actual value is zero |
"" (empty string) |
The actual value is an empty string |
Important
Do not send 0 or empty strings as placeholders for missing data. Instead,
explicitly set missing data to null. For example,
"totalDebtDollars": 0 means the business has zero debt, while
"totalDebtDollars": null means the debt amount is unknown.
Enums Reference
Loan Purpose
| Value | Description |
|---|---|
working_capital |
General working capital needs |
line_of_credit |
Establish or expand line of credit |
business_startup |
New business startup costs |
business_acquisition |
Purchase existing business |
business_expansion |
Expand current operations |
business_debt_refinancing |
Refinance existing business debt |
buyout |
Partner or shareholder buyout |
commercial_property_purchase |
Purchase commercial real estate |
commercial_property_improvements |
Improve existing commercial property |
commercial_property_new_construction |
New commercial construction |
equipment_purchase |
Purchase business equipment |
inventory_or_materials_purchase |
Purchase inventory or materials |
Use of Proceeds
Loan purposes provided in the API must match the Use of Proceeds table in the funded loan package provided to MKIII.
Purpose Ordering
The loanPurposes array is ordered by importance—the first purpose is the
primary reason for the loan. For example, if a business is merging with another
company, you might list ["business_acquisition", "buyout"] to indicate
the primary purpose is acquiring the business, with a secondary purpose of buying out
existing partners.
Business Type
| Value | Description |
|---|---|
individual |
Individual business owner |
corporation |
General corporation |
sole_proprietorship |
Sole proprietorship |
partnership |
General partnership |
limited_liability_partnership |
Limited liability partnership (LLP) |
limited_partnership |
Limited partnership (LP) |
limited_liability_company |
Limited liability company (LLC) |
c_corporation |
C Corporation |
s_corporation |
S Corporation |
b_corporation |
Benefit Corporation |
close_corporation |
Close Corporation |
nonprofit_corporation |
Nonprofit Corporation |
nonprofit |
General nonprofit |
cooperative |
Cooperative |
Business Documentation
Business type must match the tax returns and articles of incorporation provided in the funded loan package.
Owner Type
| Value | Description |
|---|---|
co_owner |
Co-owner of the business |
owner |
Primary owner |
guarantor |
Loan guarantor |
affiliate |
Business affiliate |
Request Schema
We recommend a progressive approach to submitting applications. Start with the minimum required fields to get a pre-qualification, then add fields as needed to reach approved status.
Step 1: Prequal Request
Submit these fields to receive a pre-qualification decision with indicative rates. This is the minimum viable request.
Root Fields
| Field | Type | Description |
|---|---|---|
externalId |
string | Your unique identifier for this application. Must be unique across all applications; cannot be reused after an application reaches a terminal status. |
loanAmountDollars |
integer | Loan amount in dollars ($25,000–$500,000) |
loanPurposes
|
array of enum | Purpose(s) of the loan, ordered by importance. The first item is the primary purpose. |
Business Applicant (Prequal)
| Field | Type | Description |
|---|---|---|
businessName |
string | Legal business name |
businessType
|
enum | Type of business entity |
employeeCount |
integer | Number of employees (min: 0) |
naicsCode |
string | 6-digit NAICS code (2022 standard) |
bankruptcy |
boolean | Has business filed for bankruptcy |
yearsInBusiness |
integer | Years in operation (min: 1) |
addressLineOne |
string | Business street address |
city |
string | City |
state |
string | 2-letter state code |
zip |
string | 5-digit ZIP code |
Owner Applicant (Prequal)
At least one beneficial owner (20% or more ownership) is required to receive a prequalified offer. All beneficial owners must be submitted for an approved loan to be valid.
| Field | Type | Description |
|---|---|---|
firstName |
string | Owner's first name |
lastName |
string | Owner's last name |
ownerType
|
enum | Relationship to business |
ownershipPercentage |
number | Ownership percentage (0.20–1.0) |
creditScore |
integer | Credit score (300–850) |
creditPullDate |
string | ISO 8601 date of credit pull (YYYY-MM-DD) |
addressLineOne |
string | Owner's street address |
city |
string | City |
state |
string | 2-letter state code |
zip |
string | 5-digit ZIP code |
dateOfBirth |
string | Date of birth (YYYY-MM-DD) |
ssn |
string | Social Security Number (XXX-XX-XXXX) |
Step 2: Additional Fields for Approved
Add these fields to reach approved status. Once approved, rates are
confirmed and the loan can be funded.
Approved Status in Sandbox
The sandbox automatically returns approved status when all 5 required
fields are present, unless a
special test case businessName overrides this
behavior.
Business Applicant (Additional)
| Field | Type | Description |
|---|---|---|
totalDebtDollars |
integer | Total business debt in dollars (min: 0) |
annualGrossRevenueDollars |
integer | Annual gross revenue in dollars (min: $100,000) |
netOperatingIncomeDollars |
integer | Net operating income in dollars |
annualDebtPaymentsDollars |
integer | Annual debt payments (principal + interest) |
bankruptcyCountLast5Years |
integer | Number of bankruptcies in the last 5 years |
Optional Fields
These fields are always optional and can be provided at any time.
Business Applicant (Optional)
| Field | Type | Description |
|---|---|---|
addressLineTwo |
string | Additional address info (suite, unit, etc.) |
derogatoryMarkCountLast60Days |
integer | Count of derogatory marks in the last 60 days |
businessCreditScore |
integer | Business credit score |
businessCreditPullDate |
string | ISO 8601 date of business credit pull (YYYY-MM-DD) |
Owner Applicant (Optional)
| Field | Type | Description |
|---|---|---|
addressLineTwo |
string | Additional address info (suite, unit, etc.) |
Full Schema Reference
Complete field reference with requirement levels.
View Complete Schema
Legend
Root Object
| Field | Type | Requirement | Description |
|---|---|---|---|
externalId |
string | Prequal | Your unique identifier for this application. Must be unique across all applications; cannot be reused after reaching a terminal status. |
loanAmountDollars |
integer | Prequal | Loan amount in dollars. Min: $25,000. Max: greater of $500,000 or (annualGrossRevenueDollars - totalDebtDollars) × 0.5 |
loanPurposes
|
array of enum | Prequal | Purpose(s) of the loan, ordered by importance. The first item is the primary purpose. |
businessApplicant |
object | Prequal | Business information |
ownerApplicants |
array | Prequal | Array of business owners (min: 1) |
Business Applicant Object
| Field | Type | Requirement | Description |
|---|---|---|---|
businessName |
string | Prequal | Legal business name |
businessType
|
enum | Prequal | Type of business entity |
employeeCount |
integer | Prequal | Number of employees (min: 0) |
naicsCode |
string | Prequal | 6-digit NAICS code (2022 standard) |
bankruptcy |
boolean | Prequal | Has business filed for bankruptcy |
yearsInBusiness |
integer | Prequal | Years in operation (min: 1) |
addressLineOne |
string | Prequal | Business street address |
addressLineTwo |
string | Optional | Additional address info |
city |
string | Prequal | City |
state |
string | Prequal | 2-letter state code |
zip |
string | Prequal | 5-digit ZIP code |
businessCreditScore |
integer | Optional | Business credit score |
businessCreditPullDate |
string | Optional | ISO 8601 date of business credit pull (YYYY-MM-DD) |
totalDebtDollars |
integer | Approved | Total business debt in dollars (min: 0) |
annualGrossRevenueDollars |
integer | Approved | Annual gross revenue in dollars. Min: $100,000 |
netOperatingIncomeDollars |
integer | Approved | Net operating income in dollars |
annualDebtPaymentsDollars |
integer | Approved | Annual debt payments in dollars (principal + interest) |
derogatoryMarkCountLast60Days |
integer | Optional | Count of derogatory marks in the last 60 days |
bankruptcyCountLast5Years |
integer | Approved | Number of bankruptcies in the last 5 years |
Owner Applicant Object
| Field | Type | Requirement | Description |
|---|---|---|---|
firstName |
string | Prequal | Owner's first name |
lastName |
string | Prequal | Owner's last name |
ownerType
|
enum | Prequal | Relationship to business |
ownershipPercentage |
number | Prequal | Ownership percentage (0.20-1.0 where 1.0 = 100%) |
creditScore |
integer | Prequal | Credit score (300-850) |
creditPullDate |
string | Prequal | ISO 8601 date of credit pull (YYYY-MM-DD) |
addressLineOne |
string | Prequal | Owner's street address |
addressLineTwo |
string | Optional | Additional address info |
city |
string | Prequal | City |
state |
string | Prequal | 2-letter state code |
zip |
string | Prequal | 5-digit ZIP code |
dateOfBirth |
string | Prequal | Date of birth (YYYY-MM-DD) |
ssn |
string | Prequal | Social Security Number (XXX-XX-XXXX) |
Response Schema
Success Response
| Field | Type | Description |
|---|---|---|
id |
string | System-generated application ID (format: SMB_[random]) |
externalId |
string | Your provided external ID |
status |
string |
prequal, approved, ineligible,
funded, or withdrawn
|
premiumRate |
number | null | Premium rate percentage (null if ineligible) |
deductibleRate |
number | null | Deductible percentage (null if ineligible) |
interestRate |
number | null | Interest rate percentage (null if ineligible). The interest rate displayed to the applicant should not exceed this amount, unless agreed to in the MKIII Program Manager Agreement. |
maxLoanAmountDollars |
integer | Maximum loan amount approved in dollars. This represents the most the applicant could receive and will always be at least the requested amount, but may be higher based on qualification. Set to 0 for ineligible applications. |
probabilityOfDefaultTier |
integer | null | Risk tier based on probability of default (1–5). Lower tiers indicate lower risk. See the Probability of Default Tiers table for details. |
ineligibleReasons |
array | Array of reasons for ineligibility (empty if not ineligible) |
warnings |
array | Array of warning messages |
ownerApplicants |
array | Array of owner evaluation results (see below) |
Probability of Default Tiers
The probabilityOfDefaultTier field indicates the risk tier based on the
calculated probability of default. Lower tiers represent lower risk.
| Tier | Probability of Default Range |
|---|---|
1 |
< 2% |
2 |
2.01% – 3% |
3 |
3.01% – 4% |
4 |
4.01% – 5% |
5 |
5.01%+ |
Owner Evaluations
Each owner applicant is individually evaluated. The response includes each owner's profile data along with their evaluation result.
Owner Applicant Object
| Field | Type | Description |
|---|---|---|
profile |
object | Owner's profile data (SSN is redacted in response) |
evaluationResult |
object | Evaluation outcome for this owner |
Evaluation Result Object
| Field | Type | Description |
|---|---|---|
pass |
boolean | Whether the owner passed evaluation |
SSN Redaction
For security, the ssn field in the profile is partially redacted in
responses (e.g., ***-**-3456). Only the last 4 digits are visible.
Warnings
The warnings array contains informational messages about potential issues
with the application. Warnings do not prevent an application from reaching
approved status, but indicate data that may warrant review.
Ineligible Reasons
| Reason | Description |
|---|---|
| Probability of default exceeds permitted value | Risk assessment exceeds acceptable thresholds |
| Does not qualify based on program requirements | Application does not meet credit score or other program requirements |
| Owner does not meet program criteria | One or more owners failed evaluation (see ownerApplicants for details) |
| Owner has a locked or frozen credit profile | Owner's credit file is locked or frozen and cannot be evaluated |
Error Handling
Validation Errors (400)
When request validation fails, you'll receive a 400 Bad Request response with nested error details showing which fields failed validation and why.
Application in Terminal Status (409)
Once an application reaches a terminal status (funded or
withdrawn), it can no longer be modified. Attempting to update an
application in a terminal status will return a 409 Conflict response.
Server Errors (500)
To simulate a server error in the sandbox environment, set the business name to
"error".
Testing & Go Live
Special Test Cases
To simulate different scenarios in the sandbox environment, set the
businessName field to one of the following special values:
| Business Name | Result | Description | Method |
|---|---|---|---|
"prequal-warning" |
Prequal | Returns prequal status with a warning message in the warnings array | POST/PUT |
"decline-risk" |
Ineligible | Returns "Probability of default exceeds permitted value" | POST/PUT |
"decline-qualifications" |
Ineligible | Returns "Does not qualify based on program requirements" | POST/PUT |
"decline-owner" |
Declined | Owner credit evaluation failed. Application becomes permanently unmodifiable (409 Conflict on subsequent PUT). | POST |
"owner-credit-unavailable" |
Ineligible | Owner has a locked or frozen credit profile | POST/PUT |
"decline-all" |
Ineligible | Returns all possible ineligible reasons in the array | POST/PUT |
"funded" |
409 Conflict | Simulates an already-funded application that cannot be modified | PUT |
"withdrawn" |
409 Conflict | Simulates an application that was not funded within 30 days | PUT |
"error" |
500 Error | Simulates an internal server error for retry logic testing | POST/PUT |
POST Behavior for Terminal Status Simulation Types
When creating a new application via POST, using
businessName values "funded" or
"withdrawn" will be treated as "normal" applications
instead. This is because POST creates new applications, and a new application cannot
start in a terminal (funded or withdrawn) status. To test 409 Conflict errors for
these scenarios, use PUT
with these business names.
Rate Ranges in Sandbox
| Field | Min | Max |
|---|---|---|
| Premium Rate | 2.5% | 4.75% |
| Premium Deductible | 4.0% | 6.25% |
| Interest Rate | 15.75% | 20.0% |
Go Live Checklist
While not all of these items are strictly required to go live, completing them is strongly recommended before launching in production. Some error scenarios—like 409 Conflicts from funded or withdrawn applications—won't occur until weeks after launch when loans are actually funded or the 30-day withdrawal window passes. Testing these cases in sandbox now prevents urgent production issues days or weeks later.