{
  "openapi": "3.0.1",
  "info": {
    "title": "eHELOC Creation",
    "version": "v1.1",
    "description": "API endpoints for creating and managing electronic Home Equity Line of Credit (eHELOC) documents"
  },
  "tags": [
    {
      "name": "eHELOC Creation",
      "description": "Operations for creating and managing eHELOC documents"
    }
  ],
  "paths": {
    "/document_requests": {
      "post": {
        "summary": "Create a new eHELOC document request",
        "tags": [
          "eHELOC Creation"
        ],
        "description": "Use this endpoint to create a new eHELOC document in your eVault. The payload structure differs from traditional eNotes to accommodate HELOC-specific fields with a flatter structure.",
        "parameters": [],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "201": {
            "description": "Created a new eHELOC document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/heloc_document_request_response"
                }
              }
            }
          },
          "400": {
            "description": "Bad request: some data was missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/heloc_validation_error"
                    },
                    {
                      "$ref": "#/components/schemas/heloc_mers_min_error"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: unable to proceed with authentication"
          },
          "403": {
            "description": "Forbidden: your role does not allow to proceed"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/heloc_document_request_payload"
              },
              "examples": {
                "valid_heloc_request": {
                  "summary": "Valid eHELOC request with all required fields",
                  "value": {
                    "document_request": {
                      "data": {
                        "form": "HELOC",
                        "mers_min": "100000000000000001",
                        "form_code": "HELCADS83.cst",
                        "loan_number": "HELOC2026001",
                        "closing_date": "2026-03-06",
                        "property_address": {
                          "street_name": "123 Main Street",
                          "city": "San Francisco",
                          "state": "CA",
                          "zipcode": "94105"
                        },
                        "borrowers": [
                          {
                            "first_name": "John",
                            "last_name": "Doe",
                            "middle_name": "Allen",
                            "name_suffix": "Jr"
                          }
                        ],
                        "borrower_address": {
                          "street_name": "123 Main Street",
                          "city": "San Francisco",
                          "state": "CA",
                          "zipcode": "94105"
                        },
                        "lender_name": "Better Mortgage Corporation",
                        "lender_address": {
                          "street_name": "3 World Trade Center",
                          "city": "New York",
                          "state": "NY",
                          "zipcode": "10007"
                        },
                        "credit_limit": "250000.00",
                        "initial_advance_amount": "50000.00",
                        "minimum_advance_amount": "5000.00",
                        "payment_remittance_day": 15,
                        "scheduled_first_payment_date": "May 1, 2026",
                        "final_advance_request_date": "2036-03-06",
                        "draw_period_count": 120,
                        "hold_period_count": 0,
                        "repay_period_count": 240,
                        "loan_maturity_date": "2056-03-06",
                        "payment_billing_statement_frequency_type": "Monthly",
                        "lien_priority_type": "1ST",
                        "note_rate_percent": "6.500",
                        "margin_rate_percent": "2.500",
                        "maximum_apr_rate": "18.000",
                        "minimum_apr_rate": "3.000",
                        "initial_note_rate_percent": "4.500",
                        "initial_daily_periodic_rate_percent": "0.012",
                        "daily_periodic_interest_rate_calculation_type": 360,
                        "lifetime_floor_rate_percent": "3.000",
                        "lifetime_cap_rate_percent": "18.000",
                        "late_charge_grace_period": 15,
                        "late_charge_rate_percent": "5.000"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://demo.snapdocsevault.com/api",
      "description": "Snapdocs Evault demo environment"
    },
    {
      "url": "https://www.snapdocsevault.com/api",
      "description": "Snapdocs Evault production environment"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "JWT token authentication. Include the token in the Authorization header as 'Bearer <token>'"
      }
    },
    "schemas": {
      "heloc_document_request_payload": {
        "type": "object",
        "required": [
          "document_request"
        ],
        "properties": {
          "document_request": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "$ref": "#/components/schemas/heloc_data"
              }
            }
          }
        }
      },
      "heloc_data": {
        "type": "object",
        "description": "eHELOC document data with flatter structure than traditional eNotes",
        "required": [
          "mers_min",
          "form_code",
          "loan_number",
          "property_address",
          "borrowers",
          "lender_name"
        ],
        "properties": {
          "form_code": {
            "type": "string",
            "enum": [
              "HELOC"
            ],
            "description": "Form type - must be 'HELOC' for eHELOC documents"
          },
          "mers_min": {
            "type": "string",
            "pattern": "^[0-9]{18}$",
            "example": "100000000000000001",
            "description": "18-digit MERS Mortgage Identification Number"
          },
          "form": {
            "type": "string",
            "example": "HELCADS83.cst",
            "description": "Form code from document footer"
          },
          "loan_number": {
            "type": "string",
            "example": "HELOC2026001",
            "description": "Loan identifier assigned by the lender"
          },
          "closing_date": {
            "type": "string",
            "example": "2026-03-06",
            "description": "Date of closing. Accepts ISO 8601 (YYYY-MM-DD) or 'Month DD, YYYY' format"
          },
          "property_address": {
            "$ref": "#/components/schemas/address"
          },
          "borrowers": {
            "type": "array",
            "minItems": 1,
            "description": "Array of borrowers (at least one required)",
            "items": {
              "$ref": "#/components/schemas/borrower"
            }
          },
          "borrower_address": {
            "$ref": "#/components/schemas/address",
            "description": "Borrower's mailing address"
          },
          "lender_name": {
            "type": "string",
            "example": "Better Mortgage Corporation",
            "description": "Name of the lending institution"
          },
          "lender_address": {
            "$ref": "#/components/schemas/address",
            "description": "Lender's address"
          },
          "credit_limit": {
            "type": "string",
            "example": "250000.00",
            "description": "Maximum credit limit. Dollar amount as string (commas optional)"
          },
          "initial_advance_amount": {
            "type": "string",
            "example": "50000.00",
            "description": "Initial advance amount. Dollar amount as string (commas optional)"
          },
          "minimum_advance_amount": {
            "type": "string",
            "example": "5000.00",
            "description": "Minimum advance amount. Dollar amount as string (commas optional)"
          },
          "minimum_balance_amount": {
            "type": "string",
            "example": "1000.00",
            "description": "Minimum balance amount. Dollar amount as string (commas optional) or 'N/A'"
          },
          "payment_remittance_day": {
            "type": "integer",
            "minimum": 1,
            "maximum": 31,
            "example": 15,
            "description": "Day of month when payment is due"
          },
          "scheduled_first_payment_date": {
            "type": "string",
            "example": "May 1, 2026",
            "description": "First payment date. Accepts ISO 8601 or 'Month DD, YYYY' format"
          },
          "final_advance_request_date": {
            "type": "string",
            "example": "2036-03-06",
            "description": "Final date to request advance. Accepts ISO 8601 or 'Month DD, YYYY' format"
          },
          "draw_period_count": {
            "type": "integer",
            "minimum": 0,
            "example": 120,
            "description": "Draw period in months"
          },
          "hold_period_count": {
            "type": "integer",
            "minimum": 0,
            "example": 0,
            "description": "Hold period in months"
          },
          "repay_period_count": {
            "type": "integer",
            "minimum": 0,
            "example": 240,
            "description": "Repayment period in months"
          },
          "loan_maturity_date": {
            "type": "string",
            "example": "2056-03-06",
            "description": "Loan maturity date. Accepts ISO 8601 or 'Month DD, YYYY' format"
          },
          "payment_billing_statement_frequency_type": {
            "type": "string",
            "example": "Monthly",
            "description": "Billing cycle frequency"
          },
          "lien_priority_type": {
            "type": "string",
            "enum": [
              "1ST",
              "2ND"
            ],
            "example": "1ST",
            "description": "Lien priority: 1ST or 2ND"
          },
          "note_rate_percent": {
            "type": "string",
            "example": "6.500",
            "description": "Annual percentage rate (max 3 decimal places)"
          },
          "margin_rate_percent": {
            "type": "string",
            "example": "2.500",
            "description": "Margin rate percentage (max 3 decimal places)"
          },
          "maximum_apr_rate": {
            "type": "string",
            "example": "18.000",
            "description": "Maximum APR rate (max 3 decimal places)"
          },
          "minimum_apr_rate": {
            "type": "string",
            "example": "3.000",
            "description": "Minimum APR rate (max 3 decimal places)"
          },
          "initial_note_rate_percent": {
            "type": "string",
            "example": "4.500",
            "description": "Initial annual percentage rate (max 3 decimal places)"
          },
          "initial_daily_periodic_rate_percent": {
            "type": "string",
            "example": "0.012",
            "description": "Initial daily periodic rate (max 3 decimal places)"
          },
          "teaser_term_month_count": {
            "type": [
              "integer",
              "string"
            ],
            "example": 12,
            "description": "Discounted rate period in months, or 'N/A'"
          },
          "teaser_term_end_date": {
            "type": "string",
            "example": "2027-03-06",
            "description": "End date of teaser term. Optional. Accepts ISO 8601 or 'Month DD, YYYY' format"
          },
          "discounted_rate_percent": {
            "type": "string",
            "example": "3.500",
            "description": "Discounted initial rate (max 3 decimal places) or 'N/A'. Optional."
          },
          "discounted_daily_rate_percent": {
            "type": "string",
            "example": "0.010",
            "description": "Discount initial daily periodic rate (max 3 decimal places) or 'N/A'. Optional."
          },
          "daily_periodic_interest_rate_calculation_type": {
            "type": "integer",
            "example": 360,
            "description": "Rate computation divisor (typically 360 or 365)"
          },
          "margin_rate_percent_section_9b": {
            "type": "string",
            "example": "2.500",
            "description": "Margin from Section 9B (max 3 decimal places). Optional."
          },
          "margin_rate_percent_string": {
            "type": "string",
            "example": "two and one-half",
            "description": "Margin as text string. Optional."
          },
          "lifetime_floor_rate_percent": {
            "type": "string",
            "example": "3.000",
            "description": "Minimum APR / Lifetime floor (max 3 decimal places)"
          },
          "lifetime_cap_rate_percent": {
            "type": "string",
            "example": "18.000",
            "description": "Maximum APR / Lifetime cap (max 3 decimal places)"
          },
          "late_charge_grace_period": {
            "type": "integer",
            "minimum": 0,
            "example": 15,
            "description": "Grace period in days before late charge applies"
          },
          "late_charge_rate_percent": {
            "type": "string",
            "example": "5.000",
            "description": "Late charge rate percentage (max 3 decimal places)"
          },
          "returned_check_charge_amount": {
            "type": "string",
            "example": "35.00",
            "description": "Returned check fee. Optional. Dollar amount as string or 'N/A'"
          },
          "over_limit_charge_amount": {
            "type": "string",
            "example": "25.00",
            "description": "Over limit fee. Optional. Dollar amount as string or 'N/A'"
          },
          "stop_payment_charge_amount": {
            "type": "string",
            "example": "30.00",
            "description": "Stop payment fee. Optional. Dollar amount as string or 'N/A'"
          },
          "subtotal_estimated_fees_and_costs_amount": {
            "type": "string",
            "example": "1500.00",
            "description": "Subtotal of estimated fees and costs. Optional. Dollar amount as string"
          },
          "active_minimum_months": {
            "type": "integer",
            "minimum": 0,
            "example": 36,
            "description": "Minimum months account must remain active. Optional."
          },
          "minimum_reimbursement_fee_amount": {
            "type": "string",
            "example": "500.00",
            "description": "Minimum reimbursement fee. Optional. Dollar amount as string"
          },
          "finance_charges": {
            "type": "array",
            "description": "Finance charges line items (matches app/services/json_schema_validation/heloc_schema.json.erb)",
            "items": {
              "type": "object",
              "required": [
                "item",
                "amount"
              ],
              "properties": {
                "item": {
                  "type": "string"
                },
                "amount": {
                  "type": "string",
                  "description": "Dollar amount as string (commas optional) or 'N/A'"
                },
                "paid_outside_of_closing": {
                  "type": "string",
                  "description": "Dollar amount as string (commas optional) or 'N/A'"
                },
                "paid_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "row_number": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          },
          "other_charges": {
            "type": "array",
            "description": "Other charges line items (matches app/services/json_schema_validation/heloc_schema.json.erb)",
            "items": {
              "type": "object",
              "required": [
                "item",
                "amount"
              ],
              "properties": {
                "item": {
                  "type": "string"
                },
                "amount": {
                  "type": "string",
                  "description": "Dollar amount as string (commas optional) or 'N/A'"
                },
                "paid_outside_of_closing": {
                  "type": "string",
                  "description": "Dollar amount as string (commas optional) or 'N/A'"
                },
                "paid_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "row_number": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "address": {
        "type": "object",
        "required": [
          "street_name",
          "city",
          "state",
          "zipcode"
        ],
        "properties": {
          "street_name": {
            "type": "string",
            "example": "123 Main Street",
            "description": "Street address"
          },
          "city": {
            "type": "string",
            "example": "San Francisco"
          },
          "state": {
            "type": "string",
            "example": "CA",
            "description": "2-letter state code"
          },
          "zipcode": {
            "type": "string",
            "example": "94105",
            "pattern": "^[0-9]{5}([0-9]{4})?$",
            "description": "5 or 9 digit zipcode"
          }
        }
      },
      "borrower": {
        "type": "object",
        "required": [
          "first_name",
          "last_name"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "example": "Doe"
          },
          "middle_name": {
            "type": "string",
            "example": "Allen",
            "description": "Optional"
          },
          "name_suffix": {
            "type": "string",
            "example": "Jr",
            "description": "Optional"
          }
        }
      },
      "heloc_document_request_response": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "example": "5279e4ca-cd04-49b3-9863-d94e9acc35fe",
                "description": "The document request ID"
              },
              "type": {
                "type": "string",
                "example": "document_requests"
              },
              "attributes": {
                "type": "object",
                "properties": {
                  "evault_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of the eVault"
                  },
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of the created eHELOC document"
                  },
                  "emortgage_package_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of this version of the document"
                  },
                  "registration_status": {
                    "type": "string",
                    "enum": [
                      "initiated",
                      "active",
                      "inactive"
                    ],
                    "description": "MERS registration status"
                  },
                  "emortgage_package_status": {
                    "type": "string",
                    "enum": [
                      "initiated",
                      "sealed",
                      "canceled",
                      "edelivered",
                      "pending_seal"
                    ],
                    "description": "Status of this document version"
                  }
                }
              }
            }
          }
        }
      },
      "heloc_validation_error": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "string",
                  "example": "The property 'credit_limit' must be a valid dollar amount"
                },
                "description": "Array of validation error messages"
              }
            }
          }
        }
      },
      "heloc_mers_min_error": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "object",
            "properties": {
              "mers_min": {
                "type": "string",
                "example": "MIN number already exists but the eVault does not have controller rights"
              }
            }
          }
        }
      }
    }
  }
}