RatePlug Special Financing API
Programmatic access to property eligibility, special financing data, and automated valuations for residential real estate.
Authentication
All API requests require authentication via an API key. Include your key in the X-Api-Key header with every request. API keys can be managed from the Partner Portal.
Keep your API keys secure. Do not expose them in client-side code, public repositories, or browser requests. If a key is compromised, revoke it immediately from the Partner Portal and generate a new one.
Base URL
All API requests should be made to the following base URL:
All responses are returned as JSON. The API uses standard HTTP response codes to indicate success or failure.
GET Special Financing
Returns property identification, address, automated valuation, and special financing eligibility data for a given property.
Query Parameters
Full street address of the property. If omitted, returns all eligible records for the FIPS code.
Assessor's Parcel Number. Alternative to address lookup.
RatePlug internal Property ID. The most precise lookup method.
Example Request
Example Response
Assumable Mortgage DATA OPTION
Detail on a property's existing government-backed loan that a buyer may be able to take over.
An assumable mortgage allows a buyer to take over the seller's existing home loan — including its remaining balance, repayment term, and interest rate. When the existing loan carries a rate below current market rates, assumption can dramatically lower the buyer's monthly payment. The buyer must cover the gap between the loan balance and the purchase price in cash or with secondary financing; the EstimatedEquity field estimates that gap using the property's AVM value.
FHA, VA, and USDA loans are assumable (subject to lender qualification). When a property's first mortgage is one of these programs, the Standard Package field Assumable is true and this option returns the loan detail below, sourced from county-recorded public records.
Availability
The Assumable Mortgage option is enabled per API key. To add it to your key, contact your RatePlug partner representative. If your key does not include the option, the AssumableMortgage field is omitted from responses entirely. If your key includes the option but the property has no assumable first mortgage (or no reliable balance data), AssumableMortgage is null.
Example
See the Data Dictionary for the complete field reference.
FHA Condo Eligibility DATA OPTION
FHA condominium project approval detail for attached residential (condo) listings.
FHA financing on a condominium generally requires the condo project to be FHA-approved and in good standing with HUD requirements — including a minimum 35% owner-occupancy share and a cap on the share of units carrying FHA-insured mortgages (concentration). This option returns the project's approval status, HUD project identifiers, and the occupancy and concentration measurements behind the Standard Package's FHACondoEligible flag.
Units in projects that are not currently approved may still qualify through the FHA Single Unit Approval process — these return an EligibilityStatus of Eligible For Review. A CondoFax report (FHA Pros) can provide the upfront project review for that path.
Availability
The FHA Condo Eligibility option is enabled per API key. To add it to your key, contact your RatePlug partner representative. If your key does not include the option, the FHACondoEligibility field is omitted from responses entirely. If your key includes the option but the property is not an attached residential (condo) listing or no FHA project data exists, FHACondoEligibility is null. A condo that is not eligible still returns a populated object (for example EligibilityStatus: "Ineligible").
Eligibility Status Values
| Value | Meaning |
|---|---|
| Eligible | Project approved; unit eligible for FHA financing. |
| Caution | Approved, but an owner-occupancy or concentration violation may block FHA loan approval. |
| New Construction | Approved, but presale criteria must be verified with the developer before an FHA offer. |
| Ineligible | Not approved and not eligible for FHA financing. |
| Eligible For Review | Not currently approved; may qualify via FHA Single Unit Approval. |
Example
See the Data Dictionary for the complete field reference of this option.
Data Dictionary
Complete field reference for the Special Financing API response. All fields are returned in the data object. Add-on data option objects (AssumableMortgage, FHACondoEligibility) appear only when your API key includes the option.
| Field Name | Type | Size | Description |
|---|---|---|---|
| Property Identification | |||
| Fips | varchar | 5 | The FIPS county code — a five-digit Federal Information Processing Standard code that uniquely identifies counties and county equivalents in the United States. |
| RatePlugPropertyID | bigint | 11 | The RatePlug-derived ID that uniquely identifies a property in the RatePlug database. |
| APN | varchar | 45 | Assessor's Parcel Number or Parcel Identification Number. An arbitrary parcel identifier assigned by the county Assessor. |
| Property Address | |||
| CompleteStreetAddress | varchar | 100 | Full street address of the property. |
| StandardizeStreetAddress | varchar | 100 | USPS-standardized street address. |
| City | varchar | 55 | City for the property address. |
| State | varchar | 2 | Two-letter state abbreviation. |
| Zip | varchar | 5 | Five-digit ZIP code assigned by the USPS. |
| Tract | varchar | 6 | Census tract code. |
| StateFips | varchar | 2 | Two-digit state FIPS code. |
| CountyFips | varchar | 3 | Three-digit county FIPS code. |
| MSACode | varchar | 5 | Metropolitan Statistical Area code. |
| Automated Valuation Model (AVM) | |||
| FinalValue | float | 11 | Automated valuation value for the property. |
| HighValue | float | 11 | High value of the AVM model range. |
| LowValue | float | 11 | Low value of the AVM model range. |
| ConfidenceScore | int | 3 | Confidence score of the valuation model (0–100). |
| StandardDeviation | float | 6 | Standard deviation of the valuation estimate. |
| ValuationDate | datetime | 8 | Date property was valued using the valuation model. |
| Special Financing Fields | |||
| CRAEligible | varchar | 11 | Community Reinvestment Act eligibility level. Values: Low, Middle, Moderate, Upper, Not Available. |
| FHAEligible | boolean | — | true if the property is within FHA loan limits and the property type is FHA-eligible. |
| FHALoanLimit | float | — | Maximum FHA loan amount allowed for the county where the property is located. |
| FHACondoEligible | boolean? | — | true if an attached residential (condo) listing is in an FHA-approved condominium project. null if not applicable. |
| FHAOwnerOccupancyViolation | varchar | 1 | Flag indicating an FHA owner-occupancy requirement violation. |
| FHAOwnerOccupancyPercentage | varchar | 55 | Owner-occupancy percentage for FHA condo projects. |
| FHAConcentration | varchar | 55 | FHA loan concentration percentage in the condo project. |
| FHAConcentrationViolation | varchar | 1 | Flag indicating an FHA concentration limit violation. |
| FHAExpirationDate | datetime | — | Expiration date of FHA condo project approval. |
| USDAAreaEligible | boolean? | — | true if the address is in a government-approved USDA rural area. |
| VAEligible | boolean? | — | true if the address and property type are VA loan-limit eligible. |
| Assumable | boolean? | — | true if the property has an assumable loan attached to it. |
| TractIncomeLevel | varchar | 50 | Census tract income level classification. |
| TractMinorityPopulationPercent | float | 11 | Minority population percentage for the census tract. |
| Field Name | Type | Size | Description |
|---|---|---|---|
Returned in the AssumableMortgage object | |||
| LoanType | varchar | 55 | Assumable loan program for the first mortgage: FHA, VA, or USDA. |
| FinancingType | varchar | 10 | Rate structure as recorded: FIX (fixed) or ADJ (adjustable). |
| Lender | varchar | 100 | Originating lender name from the recorded mortgage. |
| OriginalLoanAmount | float | — | Original first-mortgage amount. |
| RecordingDate | date | — | Mortgage recording (closing) date. |
| TermMonths | int | — | Original loan term in months (e.g. 360). |
| LoanDueDate | date | — | Loan maturity date. |
| RemainingYears | int | — | Years remaining until loan maturity (calendar-year difference). |
| EstimatedLoanBalance | float | — | Estimated current principal balance. |
| EstimatedInterestRate | float | — | Estimated current interest rate (%). |
| EstimatedMonthlyPayment | float | — | Estimated monthly principal & interest payment. |
| EstimatedLTV | float | — | Estimated loan-to-value: balance ÷ AVM FinalValue × 100, rounded to one decimal. |
| EstimatedEquity | float | — | Estimated equity gap (AVM FinalValue − estimated balance) a buyer must cover in cash or secondary financing. Rounded to whole dollars. |
| IsRefinance | boolean | — | true if the current mortgage appears to be a refinance rather than the original purchase loan. |
| SecondMortgageBalance | float? | — | Estimated second-mortgage balance, if any. |
| SecondMortgageInterestRate | float? | — | Estimated second-mortgage interest rate (%), if any. |
| Field Name | Type | Size | Description |
|---|---|---|---|
Returned in the FHACondoEligibility object | |||
| ApprovalStatus | varchar | 15 | FHA condo project approval status. Values: Approved, Caution, Not Approved, Unknown. |
| EligibilityStatus | varchar | 25 | Unit-level eligibility. Values: Eligible, Caution, New Construction, Ineligible, Eligible For Review. See status meanings. |
| CondoName | varchar | 100 | HUD condominium project name. |
| CondoID | varchar | 20 | HUD condominium project ID. |
| TotalUnits | int | — | Total number of units in the project. |
| OwnerOccupancyPercentage | float | — | Owner-occupied share of units (%). HUD requires at least 35%. |
| OwnerOccupancyViolation | boolean | — | true if the project is below the HUD owner-occupancy requirement. |
| FHAConcentration | float | — | Share of units with FHA-insured mortgages (%). |
| FHAConcentrationViolation | boolean | — | true if the project exceeds the HUD FHA concentration limit. |
| ExpirationDate | date | — | FHA project approval decertification date; recertification is required after this date. |
| LastUpdated | date | — | Date RatePlug last refreshed this project's FHA data. |
FIPS County Code Lookup
The fips parameter uses the standard 5-digit FIPS county code. Below are sample codes. The full list contains 3,200+ counties.
| FIPS | State | County |
|---|---|---|
| 06037 | CA | Los Angeles County |
| 06073 | CA | San Diego County |
| 04013 | AZ | Maricopa County |
| 12086 | FL | Miami-Dade County |
| 36061 | NY | New York County |
| 48201 | TX | Harris County |
| 17031 | IL | Cook County |
| 53033 | WA | King County |
Error Codes
The API uses standard HTTP status codes. Errors return a JSON body with status and message fields.
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Missing or invalid query parameters. |
| 401 | Unauthorized | Invalid or missing API key. |
| 403 | Forbidden | API key does not have permission for this resource. |
| 404 | Not Found | No property found matching the given parameters. |
| 429 | Too Many Requests | Rate limit exceeded. See Rate Limits. |
| 500 | Server Error | An unexpected server error occurred. Contact support. |
Rate Limits
API requests are rate-limited per API key. Current limits are returned in the response headers.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed per window (default: 1,000/hour). |
| X-RateLimit-Remaining | Requests remaining in the current window. |
| X-RateLimit-Reset | Unix timestamp when the rate limit window resets. |
If you need higher limits, contact your RatePlug partner representative or reach out via the Partner Portal.