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

# Merchant Underwriting

> Evaluates merchant risk and legitimacy for onboarding decisions using SOP-driven analysis

## Merchant Underwriting Engine Overview

The Merchant Underwriting Engine is an agentic workflow that systematically evaluates merchant risk and legitimacy for onboarding decisions. It follows Standard Operating Procedures (SOPs) to analyze every category and flag, performing web research and data gathering to make informed underwriting verdicts.

### Key Capabilities

* **SOP-Driven Analysis**: Systematically evaluates merchants against your underwriting SOP guidelines
* **Automated Evidence Collection**: Performs web research and gathers supporting documentation
* **Category-by-Category Analysis**: Evaluates red flags and green flags per SOP category
* **Structured Verdicts**: Produces underwriting results with clear verdicts from your policy dispositions

## Engine Inputs

The Merchant Underwriting Engine Configuration has the following parameters:

* **policy\_version\_id**: *optional.* The Policy version ID containing your underwriting criteria and guidelines (SOP).
* **merchant\_context**: *required.* Merchant name and any additional context or information about the merchant to underwrite.
* **images**: *optional.* Image URLs or file IDs (comma/newline/whitespace separated) for visual analysis.
* **documents**: *optional.* Document URLs or file IDs (comma/newline/whitespace separated) for document review.

See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.

## Engine Output

The output is a structured JSON object containing:

### Policy Applied

Information about the SOP policy used for underwriting:

* `name`: Name of the policy applied
* `version`: Version ID of the policy applied

### Underwriting Result

Complete underwriting analysis including:

| Field                    | Description                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `verdict`                | Final underwriting decision from policy dispositions (e.g., "APPROVED", "DENIED", "FURTHER\_REVIEW\_NEEDED") |
| `summary`                | Executive summary explaining the decision and key findings                                                   |
| `summary_evidences`      | Evidence objects with web links, screenshots, and artifacts supporting the summary                           |
| `investigation_findings` | Detailed analysis of each rule/flag from the SOP with reasoning and evidence                                 |

### Investigation Findings Structure

For each rule evaluated, the output includes:

* `rule_title`: Title of the SOP rule
* `rule_description`: Description from the policy
* `hit`: Boolean indicating if this rule was triggered
* `reasoning`: Explanation of the evaluation
* `evidence_references`: References to supporting evidence

### Evidence Structure

Each piece of evidence includes:

* `evidence_type`: "web\_link", "screenshot", or "artifact"
* `evidence_data`: URL or artifact reference
* `evidence_name`: Short descriptive name
* `evidence_description`: Why this evidence is relevant

## Creating an Underwriting Policy

The Merchant Underwriting Engine requires a policy containing your Standard Operating Procedures. You can create policies using the [Policies](/policies/introduction) feature.

### Policy Structure

Your underwriting policy should contain:

1. **Instructions**: High-level guidance on merchant evaluation approach
2. **Guidelines**: Organized as Categories > Rules
   * Each Category (e.g., "BUSINESS\_LEGITIMACY", "FINANCIAL\_STABILITY") contains multiple Rules
   * Each Rule has a `flag` type (GREEN\_FLAG or RED\_FLAG), `title`, and `description`
3. **Dispositions**: Classification options for final verdicts (e.g., "Approved", "Denied", "Further Review")

## How It Works

The Merchant Underwriting Engine autonomously:

1. **Loads the SOP** - Retrieves and parses your underwriting policy
2. **Plans investigation** - Creates a systematic plan to evaluate each SOP category
3. **Gathers information** - Performs web research, analyzes documents and images
4. **Evaluates flags** - Checks each red flag and green flag against gathered evidence
5. **Makes decision** - Produces a verdict based on SOP dispositions with full evidence trail

## Example Usage

<Steps>
  <Step title="Create an Underwriting Policy">
    First, create a Policy in the Policies section with your underwriting criteria, red/green flags, and decision dispositions.
  </Step>

  <Step title="Create an Agent">
    Click on the "Add Agent" button in the top right corner of the Agents page.

    <Frame>
      <img src="https://mintcdn.com/roeai/qeWYCF2quzHQHhsD/images/add-agent.png?fit=max&auto=format&n=qeWYCF2quzHQHhsD&q=85&s=b3e1ec9b816ed1e57cb1ecfa53ff4288" width="1920" height="1045" data-path="images/add-agent.png" />
    </Frame>

    Enter a name and an optional description of your Agent.
  </Step>

  <Step title="Select the Merchant Underwriting Engine" />

  <Step title="Configure the engine">
    <Info>\$ starts a template string</Info>

    * **policy\_version\_id**: (select your policy version)
    * **merchant\_context**: \$merchant\_context
    * **images**: \$images (optional)
    * **documents**: \$documents (optional)
  </Step>

  <Step title="Create the Agent">
    Hit the **Create** button.
  </Step>

  <Step title="Run a job">
    Create a new job and provide merchant information to evaluate. The agent will systematically analyze the merchant against your SOP and provide a structured underwriting decision.
  </Step>
</Steps>

## Use Cases

* **Merchant onboarding**: Evaluate new merchants for payment processing or marketplace approval
* **Risk assessment**: Systematically assess merchant risk factors against your criteria
* **Compliance review**: Ensure merchants meet regulatory and business requirements
* **Portfolio monitoring**: Re-evaluate existing merchants based on updated SOPs