{ "openapi": "3.0.1", "info": { "title": "Property Insights", "version": "2.0.0" }, "servers": [ { "url": "https://api-test.freddiemac.com/single-family/property-insights-api/v2" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Property Insights", "description": "Get access to Freddie Mac property data to help identify and overcome pain points." } ], "paths": { "/requestPropertyData": { "post": { "tags": [ "Property Insights" ], "summary": "Retrieve property and appraisal information and standardized address.", "operationId": "requestPropertyData", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIRequest" }, "examples": { "Example1": { "$ref": "#/components/examples/RequestExample1" }, "Example2": { "$ref": "#/components/examples/RequestExample2" }, "Example3": { "$ref": "#/components/examples/RequestExample3" }, "Example4": { "$ref": "#/components/examples/RequestExample4" }, "Example5": { "$ref": "#/components/examples/RequestExample5" }, "Example6": { "$ref": "#/components/examples/RequestExample6" }, "Example7": { "$ref": "#/components/examples/RequestExample7" }, "Example8": { "$ref": "#/components/examples/RequestExample8" }, "Example9": { "$ref": "#/components/examples/RequestExample9" }, "Example10": { "$ref": "#/components/examples/RequestExample10" } } } }, "required": true }, "responses": { "200": { "description": "OK \r\n\n ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIResponse" }, "examples": { "Example1": { "$ref": "#/components/examples/ResponseExample1" }, "Example2": { "$ref": "#/components/examples/ResponseExample2" }, "Example3": { "$ref": "#/components/examples/ResponseExample3" }, "Example4": { "$ref": "#/components/examples/ResponseExample4" }, "Example5": { "$ref": "#/components/examples/ResponseExample5" }, "Example6": { "$ref": "#/components/examples/ResponseExample6" }, "Example7": { "$ref": "#/components/examples/ResponseExample7" }, "Example8": { "$ref": "#/components/examples/ResponseExample8" }, "Example9": { "$ref": "#/components/examples/ResponseExample9" }, "Example10": { "$ref": "#/components/examples/ResponseExample10" } } } } }, "400": { "description": "Bad Request \r\n\n Error codes & details \r\n\n 400.001 Malformed content from the client \r\n\n 400.002 Request data does not match the application schema, please validate the request data. \r\n\n400.005 Empty request body \r\n\n 400.006 Content-type must be application/json \r\n\n ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIErrorResponse" }, "example": { "code": "400.006", "message": "Missing header Content-type", "details": [ { "error": "Content-type must be application/json" } ] } } } }, "401": { "description": "Unauthorized \r\n\n Error codes & details \r\n\n 401.001 Invalid Access Token, please validate the token, if error persists please renew your token. \r\n\n 401.002 Access Token Expired, please renew your access token. \r\n\n 401.003 API Product mismatch for token. Your token does not have access to the requested API \r\n\n 401.004 Invalid API Key, please validate the Client ID \r\n\n 401.005 Invalid API Key for given resource \r\n\n 401.006 Insufficient scope for Application \r\n\n 401.007 Invalid Username/Password combination, the provided combination of username and password is incorrect, please verify your credentials. \r\n\n 401.008 Invalid Refresh Token. \r\n\n 401.009 Invalid client secret \r\n\n 401.010 Refresh Token expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIErrorResponse" }, "example": { "code": "401.002", "message": "Access Token Expired", "details": [ { "error": "Access Token Expired, please renew your access token." } ] } } } }, "404": { "description": "Not Found \r\n\n Error codes & details \r\n\n 404.001 No resource for POST /path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIErrorResponse" }, "example": { "code": 404.001, "message": "No resource for POST /path", "details": { "error": "No resource for POST /path" } } } } }, "429": { "description": "Too Many Requests \r\n\n Error codes & details \r\n\n 429.001 Rate limit exceeded, too many requests have been sent per second. \r\n\n 429.002 Quota limit exceeded, too many requests have been sent per minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIErrorResponse" }, "example": { "code": 429.001, "message": "Rate limit exceeded", "details": { "error": "Rate limit exceeded, too many requests have been sent per second." } } } } }, "500": { "description": "Internal server error. \r\n\n Error codes & details \r\n\n 500 Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInsightsAPIErrorResponse" }, "example": { "code": "500", "message": "Internal server error", "details": [ { "error": "API is unable to retrieve data for the submitted request at this time. Please resubmit or contact Customer Support at (800-FREDDIE) for assistance." } ] } } } } }, "deprecated": false } } }, "components": { "schemas": { "PropertyInsightsAPIRequest": { "required": [ "inputAddress", "origination_System", "partyRoleIdentifier", "partyRoleType", "requestTransactionIdentifier" ], "type": "object", "properties": { "requestTransactionIdentifier": { "maxLength": 50, "minLength": 1, "type": "string", "description": "128-bit Globally unique identifier (GUID) assigned to each request.", "example": "4e6da9da-6b10-4995-89a0-b793b6f2b1b2" }, "partyRoleIdentifier": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The unique identifier assigned to the party role.", "example": "123456" }, "partyRoleType": { "maxLength": 50, "minLength": 1, "type": "string", "description": "Identifies the role that the party plays in the transaction. Parties may be either a person or legal entity. A party may play multiple roles in a transaction.", "example": "Seller", "enum": [ "Broker", "Seller", "Servicer", "Correspondent", "Lender", "Other" ] }, "partyRoleTypeOtherDescription": { "maxLength": 50, "minLength": 1, "type": "string", "description": "A free-form text field used to collect additional information when \"Other\" is selected for Party Role Type." }, "loan_Identifier": { "$ref": "#/components/schemas/PropertyInsightsAPIRequest_loan_Identifier" }, "origination_System": { "$ref": "#/components/schemas/PropertyInsightsAPIRequest_origination_System" }, "inputAddress": { "$ref": "#/components/schemas/PropertyInsightsAPIRequest_inputAddress" } }, "additionalProperties": false }, "PropertyInsightsAPIResponse": { "required": [ "inputAddress", "propertyData", "requestTransactionIdentifier", "standardizedAddress", "transactionDateTime" ], "type": "object", "properties": { "requestTransactionIdentifier": { "type": "string", "description": "128-bit Globally unique identifier (GUID) assigned to each request.", "example": "4e6da9da-6b10-4995-89a0-b793b6f2b1b2" }, "transactionDateTime": { "type": "string", "example": "2020-09-10T22:05:37.184Z" }, "inputAddress": { "$ref": "#/components/schemas/PropertyInsightsAPIResponse_inputAddress" }, "standardizedAddress": { "$ref": "#/components/schemas/PropertyInsightsAPIResponse_standardizedAddress" }, "propertyData": { "$ref": "#/components/schemas/PropertyInsightsAPIResponse_propertyData" } }, "additionalProperties": false }, "PropertyInsightsAPIErrorResponse": { "title": "PropertyInsightsAPIErrorResponse", "type": "object", "properties": { "errorEnvelope": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "PropertyInsightsAPIRequest_loan_Identifier": { "type": "object", "properties": { "loanIdentifier": { "type": "string", "description": "A unique identifier assigned by an entity to identify the loan", "example": "L104231" }, "loanIdentifierType": { "type": "string", "description": "A value from a MISMO prescribed list that specifies the type of loan identifier.", "example": "LenderLoan", "enum": [ "LenderLoan", "AgencyCase", "UniversalLoan" ] } }, "additionalProperties": false }, "PropertyInsightsAPIRequest_origination_System": { "required": [ "loanOriginationSystemVendorIdentifier", "loanOriginationSystemVersionIdentifier" ], "type": "object", "properties": { "loanOriginationSystemVendorIdentifier": { "minLength": 1, "type": "string", "description": "A unique identifier agreed upon by the parties to the transaction to identify the vendor of the loan origination system used to process the loan", "example": "AccurateLOS" }, "loanOriginationSystemVersionIdentifier": { "minLength": 1, "type": "string", "description": "Specifies the version of the loan origination system used to process the loan", "example": "2.7" } }, "additionalProperties": false }, "PropertyInsightsAPIRequest_inputAddress": { "required": [ "addressLineText", "cityName", "postalCode", "stateCode" ], "type": "object", "properties": { "addressLineText": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The address with the address number, pre-directional, street name, post-directional, address unit designators and address unit value.", "example": "8200 Jones Branch Drive" }, "addressUnitIdentifier": { "type": "string", "description": "The identifier value associated with the Secondary Address Unit Designator of the subject property.", "example": "B1C" }, "cityName": { "maxLength": 100, "minLength": 1, "type": "string", "description": "The name of the city.", "example": "McLean" }, "postalCode": { "maxLength": 10, "minLength": 5, "pattern": "^[0-9]{5}(?:-[0-9]{4})?$", "type": "string", "description": "The postal code (ZIP Code in the US) for the address. ZIP Code may be either 5 or 9 digits.", "example": "22102" }, "stateCode": { "pattern": "^[A-Za-z\\s]*$", "type": "string", "description": "The two-character representation of the US state, US Territory, Canadian Province, Military APO FPO, or Territory.", "example": "VA", "enum": [ "AK", "AL", "AR", "AZ", "CA", "CO", "CT", "DC", "DE", "FL", "GA", "GU", "HI", "IA", "ID", "IL", "IN", "KS", "KY", "LA", "MA", "MD", "ME", "MI", "MN", "MO", "MS", "MT", "NC", "ND", "NE", "NH", "NJ", "NM", "NV", "NY", "OH", "OK", "OR", "PA", "PR", "RI", "SC", "SD", "TN", "TX", "UT", "VI", "VA", "VT", "WA", "WI", "WV", "WY" ] } }, "additionalProperties": false }, "PropertyInsightsAPIResponse_inputAddress": { "required": [ "addressLineText", "cityName", "postalCode", "stateCode" ], "type": "object", "properties": { "addressLineText": { "type": "string", "description": "The address with the address number, pre-directional, street name, post-directional, address unit designators and address unit value.", "example": "8200 Jones Branch Drive" }, "addressUnitIdentifier": { "type": "string", "description": "The identifier value associated with the Secondary Address Unit Designator of the subject property.", "example": "B1C" }, "cityName": { "type": "string", "description": "The name of the city.", "example": "McLean" }, "postalCode": { "type": "string", "description": "The postal code (ZIP Code in the US) for the address. ZIP Code may be either 5 or 9 digits.", "example": "22102" }, "stateCode": { "type": "string", "description": "The two-character representation of the US state, US Territory, Canadian Province, Military APO FPO, or Territory.", "example": "VA" } } }, "PropertyInsightsAPIResponse_standardizedAddress": { "required": [ "addressLineText", "cityName", "countyName", "fipsCountyCode", "fipsStateNumericCode", "latitudeCoordinateValue", "longitudeCoordinateValue", "postalCode", "stateCode" ], "type": "object", "properties": { "addressLineText": { "type": "string", "description": "The address with the address number, pre-directional, street name, post-directional, address unit designators and address unit value.", "example": "8200 Jones Branch Drive" }, "addressUnitIdentifier": { "type": "string", "description": "The identifier value associated with the Secondary Address Unit Designator of the subject property.", "example": "B1C" }, "cityName": { "type": "string", "description": "The name of the city.", "example": "McLean" }, "postalCode": { "type": "string", "description": "The postal code (ZIP Code in the US) for the address. ZIP Code may be either 5 or 9 digits.", "example": "22102" }, "stateCode": { "type": "string", "description": "The two-character representation of the US state, US Territory, Canadian Province, Military APO FPO, or Territory.", "example": "VA" }, "fipsCountyCode": { "type": "string", "description": "Code identifying the county. (Designator Code based on Federal Information Processing Standard Publication 6-4).", "example": "059" }, "fipsStateNumericCode": { "type": "string", "description": "A unique two digit numeric code to identify each State and State equivalent entity. These State codes are part of the Federal Information Processing Standards (FIPS), an official coding system developed by the National Institute of Standards and Technology (NIST, formerly the National Bureau of Standards), U.S. Department of Commerce, and maintained by the U.S. Geological Survey (USGS).", "example": "51" }, "countyName": { "type": "string", "description": "The county name of the area.", "example": "Fairfax" }, "latitudeCoordinateValue": { "type": "string", "example": "41.509600" }, "longitudeCoordinateValue": { "type": "string", "example": "-81.675600" } } }, "PropertyInsightsAPIResponse_propertyData_appraisalData": { "required": [ "PUDIndicator", "PUDLegalName", "accessoryUnitIndicator", "appraisaleffectivedate", "attachmentType", "homeOwnersAssociationDuesPaymentAmountMonthly", "homeOwnersAssociationDuesPaymentAmountYearly", "livingUnitCount", "neighborhoodBoundariesDescription", "neighborhoodName", "ownerOfPublicRecordName", "projectDesignType", "projectDeveloperControlledIndicator", "projectName", "propertyDesignStyleDescription", "propertyRightsAppraised", "propertyStructureBuiltYear", "propertyZoningCategoryType", "siteZoningClassificationDescription", "siteZoningComplianceDescription", "specialFloodHazardAreaIndicator", "structureAreaMeasure" ], "type": "object", "properties": { "appraisalFormType": { "type": "string", "description": "Specifies the form used to provide the property valuation.