{ "openapi": "3.1.0", "info": { "title": "Zeitro agency mortgage guidelines and calculators", "version": "1.0.0", "summary": "Verbatim text of US agency mortgage guidelines with citations, and debt-to-income and FHA mortgage insurance calculators.", "description": "Zeitro (www.zeitro.com) provides the text of US agency mortgage guidelines: the Fannie Mae Selling Guide and Eligibility Matrix, the Freddie Mac Single-Family Seller/Servicer Guide, HUD Handbook 4000.1 (FHA), the VA Lender's Handbook (VA Pamphlet 26-7) and USDA HB-1-3555.\n\nResults are verbatim guideline passages. Each passage has the document, version date and page, a ready-made citation (cite_as), the agency's official source link (source_url) and a citation URL on zeitro.com (url). The text is quoted as published, the latest published version governs, and nothing here is an underwriting decision.\n\nTwo calculators estimate debt-to-income ratios against the published limits of Fannie Mae, Freddie Mac, FHA, VA and USDA, and the FHA upfront and annual mortgage insurance premium. Their results list the assumptions, cite the guideline or Mortgagee Letter behind every limit and rate, and link to the matching calculator on www.zeitro.com. Calculations do not count toward the daily total.\n\nThe same five operations are available as tools of the Zeitro MCP server (https://strata-mcp.zeitro.com/mcp); each operationId is the tool's name and the answers are identical.\n\nNo API key is needed. Free use is limited per client per minute and in total per day; past a limit the answer is HTTP 429 with error.code rate_limited or daily_limit_reached and a Retry-After header. A free API key (https://www.zeitro.com/developers), sent as X-API-Key or as an Authorization bearer token, gives the same answers with limits of its own: tool calls per minute and searches plus page reads per UTC day for that key, apart from the free tier's. A credential that is not an active key gets HTTP 401 with error.code invalid_api_key, not the free tier. Lender program guides and lender overlays are not part of this free service; they are in Zeitro Strata, which has a free account at https://lo.zeitro.com/signup.\n\nEvery link in a result carries utm_source=agent&utm_medium=&utm_campaign=api. The client name comes from the client query parameter, the X-Client-Name header or the User-Agent, in that order.", "termsOfService": "https://www.zeitro.com/terms-conditions", "contact": { "name": "Zeitro support", "email": "support@zeitro.com", "url": "https://www.zeitro.com/contact" } }, "servers": [ { "url": "https://api.zeitro.com", "description": "Zeitro public API" } ], "security": [ {}, { "ApiKeyHeader": [] }, { "BearerKey": [] } ], "tags": [ { "name": "guidelines", "description": "Agency mortgage guideline text with citations." }, { "name": "calculators", "description": "Debt-to-income and FHA mortgage insurance estimates with cited limits and rates." } ], "paths": { "/public/v1/guidelines/search": { "get": { "operationId": "search_guidelines", "tags": [ "guidelines" ], "summary": "Search agency mortgage guidelines", "description": "Searches the Fannie Mae, Freddie Mac, FHA, VA and USDA mortgage guidelines and returns the most relevant verbatim passages. Each passage includes the document, version date, page, a ready-made citation (cite_as), the official source link and a citation URL on zeitro.com. A focused question per request (for example 'FHA student loan monthly payment calculation') returns the best passages. Passages may contain HTML tables. Lender overlays are not included; when the question or lenders names a lender, the result has a not_included note with a link to Zeitro Strata.", "parameters": [ { "name": "question", "in": "query", "required": true, "description": "A focused natural-language guideline question, e.g. 'maximum DTI for a manually underwritten FHA loan'.", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "example": "FHA student loan monthly payment calculation" }, { "name": "lenders", "in": "query", "required": false, "description": "Restricts the search to these agencies: 'Fannie Mae', 'Freddie Mac', 'FHA', 'VA', 'USDA'. Repeated parameters and comma-separated values are both accepted. Lender names are accepted but their guidelines are not in the free tier.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "FHA" ] }, { "name": "doc_ids", "in": "query", "required": false, "description": "Restricts the search to these documents (doc_id values from earlier results). Repeated parameters and comma-separated values are both accepted.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "top_k", "in": "query", "required": false, "description": "Number of passages, 1-10. Default 6.", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 6 } }, { "$ref": "#/components/parameters/client" } ], "responses": { "200": { "description": "Matching passages with citations.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" }, "example": { "question": "FHA student loan monthly payment calculation", "documents_searched": 1, "passages": [ { "doc_id": "example-hud-4000-1", "lender": "FHA", "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "version": "2026-08-12", "page": 312, "score": 0.87, "text": "(verbatim guideline text of the passage)", "truncated": false, "cite_as": "HUD Handbook 4000.1, version 2026-08-12, p. 312 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1" } ], "attribution": "Powered by Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=attribution", "disclaimer": "Guideline text quoted as published by the agency. The latest published version governs. This is not an underwriting decision.", "source": "Zeitro Strata guideline library: agency guides (Fannie Mae, Freddie Mac, FHA, VA, USDA) as published by each agency.", "asOf": "2026-11-10T20:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/public/v1/guidelines/documents": { "get": { "operationId": "list_documents", "tags": [ "guidelines" ], "summary": "List agency guideline documents", "description": "Lists the guideline documents of one agency (Fannie Mae, Freddie Mac, FHA, VA or USDA): doc_id, title, version date and the agency's official source link. A lender name answers an empty list with a not_included note.", "parameters": [ { "name": "lender", "in": "query", "required": true, "description": "Agency name: 'Fannie Mae', 'Freddie Mac', 'FHA', 'VA' or 'USDA'.", "schema": { "type": "string" }, "example": "Fannie Mae" }, { "$ref": "#/components/parameters/client" } ], "responses": { "200": { "description": "The agency's documents.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" }, "example": { "lender": "Fannie Mae", "documents": [ { "doc_id": "example-fnma-selling-guide", "document": "Fannie Mae Single Family Selling Guide", "file_name": "Selling-Guide.pdf", "version": "2026-09-02", "source_url": "https://selling-guide.fanniemae.com/", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=fannie-mae-selling-guide" } ], "attribution": "Powered by Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=attribution", "disclaimer": "Guideline text quoted as published by the agency. The latest published version governs. This is not an underwriting decision.", "source": "Zeitro Strata guideline library: agency guides (Fannie Mae, Freddie Mac, FHA, VA, USDA) as published by each agency.", "asOf": "2026-11-10T20:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/public/v1/guidelines/documents/{doc_id}/pages": { "get": { "operationId": "get_document_pages", "tags": [ "guidelines" ], "summary": "Read agency guideline pages", "description": "Returns the full text of up to 5 consecutive pages of one agency guideline document (Fannie Mae, Freddie Mac, FHA, VA or USDA), with the document, version date, a ready-made citation and links. Useful when a passage is cut off or a table continues onto the next page.", "parameters": [ { "name": "doc_id", "in": "path", "required": true, "description": "doc_id of an agency guideline document, from search results or the document list.", "schema": { "type": "string" } }, { "name": "start_page", "in": "query", "required": true, "description": "First page to read, 1-based.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "end_page", "in": "query", "required": false, "description": "Last page to read (inclusive). Defaults to start_page. At most 5 pages per request.", "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/client" } ], "responses": { "200": { "description": "The pages' text.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pages" }, "example": { "doc_id": "example-hud-4000-1", "lender": "FHA", "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "version": "2026-08-12", "page_count": 1872, "pages": [ { "page": 312, "text": "..." } ], "cite_as": "HUD Handbook 4000.1, version 2026-08-12, p. 312 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1", "attribution": "Powered by Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=attribution", "disclaimer": "Guideline text quoted as published by the agency. The latest published version governs. This is not an underwriting decision.", "source": "Zeitro Strata guideline library: agency guides (Fannie Mae, Freddie Mac, FHA, VA, USDA) as published by each agency.", "asOf": "2026-11-10T20:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/public/v1/calculators/dti": { "get": { "operationId": "calculate_dti", "tags": [ "calculators" ], "summary": "Calculate debt-to-income ratios", "description": "Calculates front-end (housing) and back-end (total) debt-to-income ratios from monthly income and monthly payments, and compares them with the published limits of Fannie Mae, Freddie Mac, FHA, VA and USDA, automated and manual underwriting listed separately. Each limit carries its guideline citation (document, section, version, page, cite_as). With loan_amount, state and family_size it also returns VA's minimum residual income. Pure calculation: an estimate, not an underwriting decision.", "parameters": [ { "name": "monthly_income", "in": "query", "required": true, "description": "Gross monthly qualifying income of all borrowers, in dollars.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number" }, "example": 8000 }, { "name": "housing_payment", "in": "query", "required": true, "description": "Proposed total monthly housing payment in dollars: principal and interest, property taxes, insurance, mortgage insurance and HOA dues.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number" }, "example": 2400 }, { "name": "auto_loans", "in": "query", "required": false, "description": "Monthly auto loan and lease payments. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 }, "example": 400 }, { "name": "student_loans", "in": "query", "required": false, "description": "Monthly student loan payments as the agency counts them. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 }, "example": 300 }, { "name": "credit_cards", "in": "query", "required": false, "description": "Minimum monthly payments on credit cards and other revolving accounts. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 }, "example": 150 }, { "name": "installment_loans", "in": "query", "required": false, "description": "Other monthly installment loan payments. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 } }, { "name": "alimony_child_support", "in": "query", "required": false, "description": "Monthly alimony, child support and separate maintenance payments. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 } }, { "name": "other_debts", "in": "query", "required": false, "description": "Any other monthly debt payments, such as payments on other real estate. Default 0.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number", "default": 0 } }, { "name": "loan_amount", "in": "query", "required": false, "description": "Loan amount in dollars; selects VA's residual income table (below or from $80,000).", "schema": { "maximum": 100000000, "minimum": 0, "type": "number" }, "example": 400000 }, { "name": "state", "in": "query", "required": false, "description": "Two-letter state code of the property, e.g. 'TX'; selects VA's residual income region.", "schema": { "maxLength": 2, "type": "string" }, "example": "AZ" }, { "name": "family_size", "in": "query", "required": false, "description": "Number of people in the household, for VA's residual income table.", "schema": { "maximum": 20, "minimum": 1, "type": "integer" }, "example": 3 }, { "name": "residual_income", "in": "query", "required": false, "description": "The borrower's monthly residual income by VA's method, compared with VA's minimum.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number" } }, { "$ref": "#/components/parameters/client" } ], "responses": { "200": { "description": "The estimate, with limits or rates and their sources.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DtiResult" }, "example": { "front_end_dti_percent": 30.0, "back_end_dti_percent": 40.63, "monthly": { "income": 8000.0, "housing_payment": 2400.0, "debts": { "auto_loans": 400.0, "student_loans": 300.0, "credit_cards": 150.0, "installment_loans": 0.0, "alimony_child_support": 0.0, "other_debts": 0.0 }, "debts_total": 850.0, "housing_plus_debts": 3250.0 }, "limits": [ { "agency": "FHA", "program": "FHA-insured forward mortgage", "underwriting": "automated", "decision_system": "TOTAL Mortgage Scorecard", "limit_type": "set_by_automated_underwriting", "front_end_max_percent": null, "back_end_max_percent": null, "front_end": null, "back_end": null, "applies_when": "File scored Accept by TOTAL Mortgage Scorecard. The handbook publishes no fixed ratio for an Accept; a Refer is fully (manually) underwritten to the manual ratios.", "sources": [ { "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "section": "II.A.4.a", "version": "2026-08-12", "pages": "pp. 225-226", "quote": "All transactions must be scored through TOTAL Mortgage Scorecard, except Streamline Refinance transactions, assumptions, Mortgages made to nonprofit/Governmental Entity Borrowers, and Mortgages made to Borrowers who do not have Social Security Numbers", "cite_as": "HUD Handbook 4000.1 II.A.4.a, version 2026-08-12, pp. 225-226 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1" } ] }, { "agency": "FHA", "program": "FHA-insured forward mortgage", "underwriting": "manual", "decision_system": null, "limit_type": "maximum", "front_end_max_percent": 31, "back_end_max_percent": 43, "front_end": "within", "back_end": "within", "applies_when": "Manual underwriting with no compensating factors (credit score 580 and above). Also the ceiling for a minimum decision credit score of 500-579 or no credit score.", "sources": [ { "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "section": "II.A.5.d.viii", "version": "2026-08-12", "pages": "p. 384", "quote": "The maximum Total Mortgage Payment to Effective Income Ratio (PTI) and Total Fixed Payments to Effective Income Ratio, or DTI, applicable to manually underwritten Mortgages are summarized in the matrix below.", "cite_as": "HUD Handbook 4000.1 II.A.5.d.viii, version 2026-08-12, p. 384 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1" } ] }, { "agency": "VA", "program": "VA-guaranteed loan", "underwriting": "manual_and_automated", "decision_system": null, "limit_type": "guideline", "front_end_max_percent": null, "back_end_max_percent": 41, "front_end": null, "back_end": "within", "applies_when": "VA's 41% is a guide, secondary to residual income, not a hard maximum. Above 41% the loan needs residual income at least 20% above the VA table minimum, or a written justification signed by the underwriter's supervisor. No housing-expense (front-end) ratio.", "sources": [ { "document": "VA Lender's Handbook, VA Pamphlet 26-7", "section": "Chapter 4, Topic 10.b", "version": "2026-08-12", "pages": "pp. 120-121", "quote": "It is a guide and, as an underwriting factor, it is secondary to the residual income. It should not automatically trigger approval or rejection of a loan. Instead, consider the ratio in conjunction with all other credit factors. A ratio greater than 41 percent requires close scrutiny", "cite_as": "VA Pamphlet 26-7 Chapter 4, Topic 10.b, version 2026-08-12, pp. 120-121 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=va-pamphlet-26-7)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=va-pamphlet-26-7", "source_url": "https://www.benefits.va.gov/WARMS/pam26_7.asp" } ] } ], "limit_types": { "maximum": "The agency's published maximum for that case.", "guideline": "A published guideline that can be exceeded with the documentation the source describes.", "set_by_automated_underwriting": "No fixed ratio is published; the automated underwriting finding decides." }, "va_residual_income": { "explanation": "VA weighs residual income above the debt-to-income ratio. Residual income is the net monthly income left after federal, state and local income taxes, Social Security and Medicare, the new monthly shelter expense (including maintenance and utilities at $0.14 per square foot of gross living area), job-related expenses such as child care, and all monthly debts. VA publishes a minimum by loan amount (below or from $80,000), family size and region. When the debt-to-income ratio is above 41%, residual income at least 20% above that minimum avoids the supervisor's written justification. The minimum is 5% lower for active duty or retired servicemembers and others who use military-based facilities near the property.", "sources": [ { "document": "VA Lender's Handbook, VA Pamphlet 26-7", "section": "Chapter 4, Topic 9.e", "version": "2026-08-12", "pages": "pp. 117-119", "quote": "Residual income is the amount of net income remaining (after deduction of debts and obligations and monthly shelter expenses) to cover family living expenses.", "cite_as": "VA Pamphlet 26-7 Chapter 4, Topic 9.e, version 2026-08-12, pp. 117-119 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=va-pamphlet-26-7)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=va-pamphlet-26-7", "source_url": "https://www.benefits.va.gov/WARMS/pam26_7.asp" } ], "region": "West", "loan_amount_band": "Loan amounts of $80,000 and above", "family_size_counted": 3, "minimum_residual_income": 990, "minimum_with_military_reduction": 940.5, "minimum_plus_20_percent": 1188.0, "dti_above_41": false }, "assumptions": [ "monthly_income is the gross monthly qualifying income of all borrowers (USDA uses repayment income; FHA uses effective income).", "housing_payment is the full proposed monthly housing payment: principal and interest, property taxes, homeowners and flood insurance, mortgage insurance, and HOA dues.", "The debts are the monthly payments the agency counts; which debts count (for example installment debts with ten or fewer payments left, or student loans in deferment) differs by agency.", "Ratios are rounded to two decimals and compared with the limit as published (at or below is within).", "Limits are the agencies' own; lenders often set lower ones." ], "url": "https://www.zeitro.com/mortgage-affordability-calculator?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=calculate_dti", "attribution": "Powered by Zeitro, https://www.zeitro.com/mortgage-affordability-calculator?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=attribution", "disclaimer": "Estimate from the figures provided, for illustration only. Not an underwriting decision or a loan approval. Lenders can apply lower limits (overlays), and automated underwriting findings govern for automated files.", "source": "Zeitro calculators: limits and premium rates as published by Fannie Mae, Freddie Mac, HUD (FHA), VA and USDA, each with its document, section and page.", "asOf": "2026-11-10" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/public/v1/calculators/fha-mip": { "get": { "operationId": "calculate_fha_mip", "tags": [ "calculators" ], "summary": "Calculate FHA mortgage insurance premium", "description": "Calculates the FHA upfront and annual mortgage insurance premium (rates, dollar amounts, first-year monthly premium and how long the annual premium lasts) from the base loan amount, loan-to-value ratio, term and the case number date, using the HUD rate schedule in force for that date. Cites the Mortgagee Letter and HUD Handbook 4000.1 Appendix 1.0. Pure calculation: an estimate, not a loan approval.", "parameters": [ { "name": "base_loan_amount", "in": "query", "required": true, "description": "Base loan amount in dollars, before any financed upfront premium.", "schema": { "maximum": 100000000, "minimum": 0, "type": "number" }, "example": 350000 }, { "name": "ltv", "in": "query", "required": true, "description": "Loan-to-value ratio as a percent, e.g. 96.5: base loan amount divided by the lesser of price and appraised value.", "schema": { "maximum": 200, "minimum": 0, "type": "number" }, "example": 96.5 }, { "name": "term_months", "in": "query", "required": false, "description": "Loan term in months, e.g. 360 for 30 years or 180 for 15 years. Default 360.", "schema": { "maximum": 360, "minimum": 1, "type": "integer", "default": 360 }, "example": 360 }, { "name": "case_number_date", "in": "query", "required": false, "description": "Date the FHA case number was assigned, YYYY-MM-DD. Default today (UTC).", "schema": { "maxLength": 10, "type": "string" }, "example": "2026-11-10" }, { "name": "endorsement_date", "in": "query", "required": false, "description": "Date FHA endorsed (or will endorse) the loan, YYYY-MM-DD, when known; it selects the 2023 rates for case numbers assigned before 2023-03-20.", "schema": { "maxLength": 10, "type": "string" } }, { "name": "interest_rate", "in": "query", "required": false, "description": "Note rate as an annual percent, e.g. 6.25; gives the first-year premium on the average scheduled balance.", "schema": { "maximum": 25, "minimum": 0, "type": "number" }, "example": 6.25 }, { "name": "refinances_loan_endorsed_before_june_2009", "in": "query", "required": false, "description": "True for a Streamline or Simple Refinance of an FHA loan endorsed on or before May 31, 2009. Default false.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/client" } ], "responses": { "200": { "description": "The estimate, with limits or rates and their sources.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FhaMipResult" }, "example": { "inputs": { "base_loan_amount": 350000.0, "ltv_percent": 96.5, "term_months": 360, "case_number_date": "2026-11-10", "endorsement_date": null, "interest_rate_percent": 6.25, "refinances_loan_endorsed_before_june_2009": false }, "upfront_mip": { "rate_bps": 175, "rate_percent": 1.75, "amount": 6125.0, "total_loan_amount_if_financed": 356125, "note": "Paid in cash or financed in full; a financed loan amount is rounded down to the whole dollar. Not counted for the nationwide mortgage limits or LTV limits." }, "annual_mip": { "rate_bps": 55, "rate_percent": 0.55, "duration": "mortgage term", "duration_months": 360, "first_year_amount": 1914.78, "monthly_amount_first_year": 159.57, "basis": "Average scheduled balance of the base loan amount over the first 12 months, at the given interest rate (the balance excludes the financed upfront premium)." }, "rate_schedule": { "name": "Mortgagee Letter 2023-05", "selected_because": "Mortgagee Letter 2023-05 applies to loans endorsed on or after 2023-03-20; case number date (endorsement comes on or after it) 2026-11-10.", "base_loan_threshold": 726200, "term_class": "more than 15 years" }, "notes": [], "sources": [ { "document": "FHA Mortgagee Letter 2023-05", "issued": "2023-02-22", "effective": "effective for case numbers endorsed on or after March 20, 2023", "cite_as": "FHA Mortgagee Letter 2023-05 (HUD, 2023-02-22), https://www.hud.gov/sites/dfiles/OCHCO/documents/2023-05hsgml.pdf", "url": "https://www.hud.gov/sites/dfiles/OCHCO/documents/2023-05hsgml.pdf" }, { "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "section": "Appendix 1.0", "version": "2026-08-12", "pages": "pp. 1774-1775", "quote": "All Mortgages: 175 Basis Points (bps) (1.75%) of the Base Loan Amount.", "cite_as": "HUD Handbook 4000.1 Appendix 1.0, version 2026-08-12, pp. 1774-1775 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1" }, { "document": "HUD Handbook 4000.1, FHA Single Family Housing Policy Handbook", "section": "II.A.2.e.i", "version": "2026-08-12", "pages": "p. 207", "quote": "The mortgage amount must be rounded down to the nearest whole dollar amount, regardless of whether the UFMIP is financed or paid in cash.", "cite_as": "HUD Handbook 4000.1 II.A.2.e.i, version 2026-08-12, p. 207 (via Zeitro Strata, https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1)", "url": "https://www.zeitro.com/strata?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=hud-handbook-4000-1", "source_url": "https://www.hud.gov/hud-partners/single-family-handbook-4000-1" }, { "document": "24 CFR 203.284, Calculation of up-front and annual MIP", "quote": "remaining insured principal balance means the average outstanding principal obligation of the mortgage for the first year of amortization", "url": "https://www.ecfr.gov/current/title-24/section-203.284" } ], "assumptions": [ "Title II forward mortgage (not a HECM, Title I, Section 247 Hawaiian Home Lands or Section 248 Indian Lands mortgage).", "ltv is the base loan amount, before any financed upfront premium, divided by the lesser of the purchase price and the appraised value; streamline refinances without an appraisal use the value from the previous mortgage.", "The annual premium is billed monthly and recomputed each year on the scheduled balance, so later years are lower than the first." ], "url": "https://www.zeitro.com/mortgage-insurance-calculator?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=calculate_fha_mip", "attribution": "Powered by Zeitro, https://www.zeitro.com/mortgage-insurance-calculator?utm_source=agent&utm_medium=example-client&utm_campaign=api&utm_content=attribution", "disclaimer": "Estimate from the figures provided, for illustration only. The lender's figures and HUD's premium billing govern. Not an underwriting decision or a loan approval.", "source": "Zeitro calculators: limits and premium rates as published by Fannie Mae, Freddie Mac, HUD (FHA), VA and USDA, each with its document, section and page.", "asOf": "2026-11-10" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "A free Zeitro API key (zk_ followed by 32 characters) from https://www.zeitro.com/developers. It is optional: without it the free tier's limits apply, with it the key's own." }, "BearerKey": { "type": "http", "scheme": "bearer", "description": "The same free Zeitro API key as an Authorization bearer token. It is optional." } }, "parameters": { "client": { "name": "client", "in": "query", "required": false, "description": "Name of the calling application or agent, used in usage counts and in the utm_medium of every link. Lower case letters, digits, dot, underscore and hyphen, up to 40 characters. The X-Client-Name header or the User-Agent is used when it is absent.", "schema": { "type": "string", "maxLength": 40 } } }, "headers": { "CacheControl": { "description": "Results may be cached by the client for 5 minutes.", "schema": { "type": "string", "example": "private, max-age=300" } }, "RetryAfter": { "description": "Seconds until the request can be retried.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "A parameter is missing or out of range (error.code invalid_parameter).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Missing required parameter: question.", "hint": "Parameters of this endpoint: question, lenders, doc_ids, top_k (question required)." } } } } }, "Unauthorized": { "description": "The request carries Authorization or X-API-Key and the value is not an active Zeitro API key (error.code invalid_api_key). The request was not run; a request without credentials gets the free tier.", "headers": { "WWW-Authenticate": { "description": "The authentication scheme, Bearer.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "The credential in Authorization or X-API-Key is not an active Zeitro API key. The request was not run.", "hint": "Check the key, or send the request without Authorization and X-API-Key for the free tier. A free API key: https://www.zeitro.com/developers." } } } } }, "NotFound": { "description": "The document or agency is not in the free tier (error.code not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Document 'abc' is not an agency guideline document in the free tier.", "hint": "Use a doc_id from search results or from the document list of an agency." } } } } }, "TooManyRequests": { "description": "A limit is reached: the per-minute limit of the client or of the API key (error.code rate_limited), or the daily total of the free tier or of the API key (error.code daily_limit_reached, reset at 00:00 UTC). The request was not run.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded: the free tier allows 30 tool calls per minute. The call was not run; retry in 12 seconds. This is not a server error.", "hint": "Wait 12 seconds and retry. A free API key raises the limits: https://www.zeitro.com/developers (or write to support@zeitro.com)." } } } } }, "Unavailable": { "description": "The guideline service failed to answer (error.code unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint" ], "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_api_key", "not_found", "method_not_allowed", "rate_limited", "daily_limit_reached", "requires_api_key", "unavailable" ] }, "message": { "type": "string", "description": "What went wrong." }, "hint": { "type": "string", "description": "How to change the request so it succeeds." } } } } }, "Footer": { "type": "object", "required": [ "attribution", "disclaimer", "source" ], "properties": { "attribution": { "type": "string", "description": "Powered by Zeitro Strata, with a link." }, "disclaimer": { "type": "string", "description": "The text is quoted as published; the latest published version governs; it is not an underwriting decision." }, "source": { "type": "string", "description": "Where the text comes from." }, "asOf": { "type": [ "string", "null" ], "description": "When the document index was last built (ISO 8601, UTC)." }, "not_included": { "type": "string", "description": "Present when the request named a lender: lender guidelines and overlays are in Zeitro Strata, with the signup link." } } }, "Passage": { "type": "object", "required": [ "doc_id", "lender", "document", "text", "truncated", "cite_as", "url" ], "properties": { "doc_id": { "type": "string" }, "lender": { "type": "string", "description": "The agency, e.g. 'FHA'." }, "document": { "type": "string", "description": "Title of the guideline document." }, "version": { "type": [ "string", "null" ], "description": "Version date of the document (YYYY-MM-DD)." }, "page": { "type": [ "integer", "null" ], "description": "Page of the passage; null when it is not identified." }, "score": { "type": [ "number", "null" ], "description": "Relevance score." }, "text": { "type": "string", "description": "Verbatim guideline text; may contain HTML tables." }, "truncated": { "type": "boolean", "description": "True when the text was cut; the whole page is available by doc_id and page." }, "cite_as": { "type": "string", "description": "Ready-made citation: document, version, page and the zeitro.com link." }, "url": { "type": "string", "format": "uri", "description": "Citation URL on zeitro.com." }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The agency's official page for the document." } } }, "SearchResult": { "allOf": [ { "$ref": "#/components/schemas/Footer" }, { "type": "object", "required": [ "question", "documents_searched", "passages" ], "properties": { "question": { "type": "string" }, "documents_searched": { "type": "integer" }, "passages": { "type": "array", "items": { "$ref": "#/components/schemas/Passage" } } } } ] }, "Document": { "type": "object", "required": [ "doc_id", "document", "url" ], "properties": { "doc_id": { "type": "string" }, "document": { "type": "string", "description": "Title of the guideline document." }, "file_name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ], "description": "Version date (YYYY-MM-DD)." }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The agency's official page for the document." }, "url": { "type": "string", "format": "uri", "description": "Link on zeitro.com." } } }, "DocumentList": { "allOf": [ { "$ref": "#/components/schemas/Footer" }, { "type": "object", "required": [ "lender", "documents" ], "properties": { "lender": { "type": "string" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } ] }, "Pages": { "allOf": [ { "$ref": "#/components/schemas/Footer" }, { "type": "object", "required": [ "doc_id", "lender", "document", "page_count", "pages", "cite_as", "url" ], "properties": { "doc_id": { "type": "string" }, "lender": { "type": "string" }, "document": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "page_count": { "type": "integer", "description": "Pages in the whole document." }, "pages": { "type": "array", "items": { "type": "object", "required": [ "page", "text" ], "properties": { "page": { "type": "integer" }, "text": { "type": "string" } } } }, "cite_as": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "source_url": { "type": [ "string", "null" ], "format": "uri" } } } ] }, "Citation": { "type": "object", "properties": { "document": { "type": "string" }, "section": { "type": "string" }, "version": { "type": "string" }, "pages": { "type": "string" }, "quote": { "type": "string", "description": "The guideline's own words for this limit." }, "cite_as": { "type": "string", "description": "Ready-made citation with the zeitro.com guideline link." }, "url": { "type": "string" }, "source_url": { "type": [ "string", "null" ] } } }, "CalculatorFooter": { "type": "object", "required": [ "url", "attribution", "disclaimer", "source", "asOf" ], "properties": { "url": { "type": "string", "description": "The matching calculator page on www.zeitro.com, with the source tag." }, "attribution": { "type": "string", "description": "Powered by Zeitro, with a link." }, "disclaimer": { "type": "string", "description": "An estimate from the figures provided; not an underwriting decision." }, "source": { "type": "string" }, "asOf": { "type": "string", "description": "Date the limits or rates were last checked against the agencies' documents (YYYY-MM-DD)." }, "assumptions": { "type": "array", "items": { "type": "string" } } } }, "DtiResult": { "allOf": [ { "$ref": "#/components/schemas/CalculatorFooter" }, { "type": "object", "properties": { "front_end_dti_percent": { "type": "number", "description": "Housing payment divided by income, percent, two decimals." }, "back_end_dti_percent": { "type": "number", "description": "Housing payment plus debts divided by income, percent, two decimals." }, "monthly": { "type": "object" }, "limits": { "type": "array", "items": { "type": "object", "properties": { "agency": { "type": "string" }, "program": { "type": "string" }, "underwriting": { "type": "string", "enum": [ "automated", "manual", "manual_and_automated" ] }, "decision_system": { "type": [ "string", "null" ] }, "limit_type": { "type": "string", "enum": [ "maximum", "guideline", "set_by_automated_underwriting" ] }, "front_end_max_percent": { "type": [ "number", "null" ] }, "back_end_max_percent": { "type": [ "number", "null" ] }, "front_end": { "type": [ "string", "null" ], "enum": [ "within", "above", null ] }, "back_end": { "type": [ "string", "null" ], "enum": [ "within", "above", null ] }, "applies_when": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } } } } }, "limit_types": { "type": "object" }, "va_residual_income": { "type": "object", "description": "VA's residual income method, its minimum for the given loan amount, state and family size, and the sources." } } } ] }, "FhaMipResult": { "allOf": [ { "$ref": "#/components/schemas/CalculatorFooter" }, { "type": "object", "properties": { "inputs": { "type": "object" }, "upfront_mip": { "type": "object", "description": "Rate (basis points and percent), dollar amount, and the total loan amount when financed." }, "annual_mip": { "type": "object", "description": "Rate, duration (11 years or the mortgage term), first-year amount and first-year monthly premium." }, "rate_schedule": { "type": "object", "description": "The HUD schedule used and why the loan's dates select it." }, "notes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object" } } } } ] } } } }