Upload
banh-mi
View
294
Download
0
Embed Size (px)
Citation preview
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
1/56
Electronic Appraisal Delivery (EAD) Portal
Technical Integration Guide
Version 1.4Last Updated: March 19, 2015
2015 Veros Real Estate SolutionsAppraisal forms 2015 Fannie Mae and Freddie Mac. Trademarks of the respective owners.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
2/56
EAD Technical Integration Guide Version 1.4 Page 2 of 55Confidential and Proprietary
Document Revisions
Date Version Change5/5/2014 1.1 Initial Version12/29/2014 1.2 Updated description fields related to HUD Case Number to reflect
name change: 'FHA Case Number'. Updated RI to indicate thatRequestDateTime is required. Updated SubmitAppraisal CO toindicate that RECIPIENT_FHA is conditional.
3/4/2015 1.3 Updated Hard Stop Codes and Hard Stop Override Codes Sections underAppendix A: Hard Stop, Override, and Error Codes with new FHA hardstops.
3/19/2015 1.4 Updated FHA5005 hard stop description under Appendix A: Hard Stop,Override, and Error Codes.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
3/56
EAD Technical Integration Guide Version 1.4 Page 3 of 55Confidential and Proprietary
Table of Contents1 Introduction .......................................................................................................................................... 5
1.1 Overview............................................................................................................................. ............... 51.2 Glossary ............................................................................................................................................... 6
2 EAD Integration Services .................................................................................................................... 7
2.1 Overview ....................................................................................................................................... 72.1.1 EAD Integration................................................................................................................................. 72.1.2 EAD Integration URL........................................................................................................................ 7
2.2 Connection Models....................................................................................................................... 72.2.2 PostBack ............................................................................................................................................ 8
2.3 XML/MIME Data Format..........................................................................................................10 2.3.1 HTTP and MIME............................................................................................................................. 102.3.2 Request Format ................................................................................................................................ 112.3.3 Response Format.............................................................................................................................. 12
2.4 Routing Information ...................................................................................................................142.4.1 Request Group ................................................................................................................................. 142.4.2 Response Group ............................................................................................................................... 16
2.5 STATUS_LOG ............................................................................................................................19
3 EAD Business Services ........................................................................................................................203.1 Overview ......................................................................................................................................20
3.1.1 Submit Appraisal ............................................................................................................................. 203.1.2 Get Findings..................................................................................................................................... 203.1.3 Get Findings Wait ............................................................................................................................ 203.1.4 Get Reports ...................................................................................................................................... 203.1.5 Successful Transaction Workflow ................................................................................................... 213.1.6 Hard Stop - Override Workflow ...................................................................................................... 22
3.2 Submit Appraisal.........................................................................................................................23Description .................................................................................................................................................... 23Routing Input................................................................................................................................................. 23Control Input ................................................................................................................................................. 24Business Input ............................................................................................................................................... 29Control Output............................................................................................................................................... 29
3.3 Get Findings.................................................................................................................................30Description .................................................................................................................................................... 30Routing Input................................................................................................................................................. 31Control Input ................................................................................................................................................. 31Control Output............................................................................................................................................... 32Business Output............................................................................................................................................. 37
3.4 Get Findings Wait .......................................................................................................................40Description .................................................................................................................................................... 40Routing Input................................................................................................................................................. 40Control Input ................................................................................................................................................. 40Control Output............................................................................................................................................... 40Business Output............................................................................................................................................. 40
3.5 Get Reports ..................................................................................................................................40
Description .................................................................................................................................................... 40Routing Input................................................................................................................................................. 41Control Input ................................................................................................................................................. 41Control Output............................................................................................................................................... 42Business Output............................................................................................................................................. 43
4 Error Handling ....................................................................................................................................445 EAD Integration Recommendations ..................................................................................................46
Overview ....................................................................................................................................................... 465.1 Validate Input XML Files during Development .............................................................................. 46
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
4/56
EAD Technical Integration Guide Version 1.4 Page 4 of 55Confidential and Proprietary
5.2 Record the Business Service Request GUID ................................................................................... 465.3 Use a Conversation ID ..................................................................................................................... 465.4 Monitoring and Health Checks ........................................................................................................ 465.5 DNS Best Practices .......................................................................................................................... 465.6 Set Appropriate Network Socket Timeout Intervals ........................................................................ 475.7 MIME Best Practices ....................................................................................................................... 47
Appendix A: Hard Stop, Override, and Error Codes ..............................................................................48 Hard Stop Codes.............................................................................................................................................48Hard Stop Override Request Codes..................................................................................................................49Hard Stop Override Decision Codes............................................................................................ ...................50Status/Error Codes......................................................................................................................................... 51Recipient Status Codes .................................................................................................................................. 52
Appendix B: EAD Error Codes (Routing Output) ...................................................................................53 Appendix C: Round Trip Test using Timeserver .....................................................................................54
Description .................................................................................................................................................... 54Routing Input................................................................................................................................................. 54
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
5/56
EAD Technical Integration Guide Version 1.4 Page 5 of 55Confidential and Proprietary
1 Introduction
1.1 Overview
The Electronic Appraisal Delivery (EAD) portal is the portal through which lenders will electronically submit
appraisal reports for delivery to the Federal Housing Administration (FHA). The Electronic Appraisal DeliveryTechnical Integration Guide (EAD TIG) is intended for lenders and third-party vendors that are developinginterfaces to submit appraisal data to EAD. Direct Integration projects must be managed in consultation with thethird-party vendor selected by FHA, Veros Real Estate Solutions.
For designated appraisal report forms, lenders will be required to deliver electronic appraisal data through EADto FHA.
The following three appraisal report forms must be submitted in MISMO 2.6 Errata 1 format:
Small Residential Income Property Appraisal Report (Freddie Mac Form 72/Fannie Mae Form 1025)
Manufactured Home Appraisal Report (Freddie Mac Form 70B/Fannie Mae Form 1004C)
Appraisal Update and/or Completion Report (Freddie Mac Form 442/Fannie Mae Form 1004D)
The following two appraisal report forms must be submitted in MISMO 2.6 GSE Extended format and must alsomeet the standards provided in the Uniform Appraisal Dataset (UAD) Specification:
Uniform Residential Appraisal Report (Freddie Mac Form 70/Fannie Mae Form 1004)
Individual Condominium Unit Appraisal Report (Freddie Mac Form 465/Fannie Mae Form 1073)
The UAD includes all data points required for a complete appraisal report form and standardizes key appraisaldata elements for a subset of fields.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
6/56
EAD Technical Integration Guide Version 1.4 Page 6 of 55Confidential and Proprietary
1.2 Glossary
DTDDocument Type Definitions (DTDs) are a set of rules that define the structure of an XML document.TheRouting Input/Output and Control Input/Output defined in this specification comprise a proprietary
message header to complete an EAD transaction. The xml structures are defined using DTDs which areprovided in the Integration Tool Kit available from Veros. There are multiple examples rendered withinthe specification which conform to the DTD structure.
GUID
A Globally Unique Identifier (GUID) is a value returned via the EAD response file. In the PostBack
connectivity model, the GUID is used as the unique identifier to reference the original request when receiving
the complete request response file. A GUID is returned with all requests.
HTML
Hypertext Markup Language (HTML) is the primary markup language used to create Web pages. It is a return
file format option for EAD response files.
HTTPS
HyperText Transfer Protocol Secure (HTTPS) is a secure protocol used on the Web to transfer hypertext
media. It is a stateless application level protocol, which takes place over TCP/IP using the default port 443.
MIME
Multipurpose Internet Mail Extensions (MIME) refers to an official Internet standard that specifies how
messages must be formatted so that they can be exchanged between different mail systems. MIME messages
can contain text, images, audio, video, or other application-specific data.
URL
A Uniform Resource Locator (URL) is the file or place in a file on a particular machine where a resource is
located. Most users are familiar with URLs as domain names.
UAD
The Uniform Appraisal Dataset (UAD) has been developed to improve the quality and consistency of appraisal
data on delivered loans. The UAD includes all data points required for a complete appraisal report form and
standardizes key data points.
XML
Extensible Markup Language (XML) is a set of standardized rules for marking-up documents that can be
shared on the Internet. It provides data independence from formatting constraints.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
7/56
EAD Technical Integration Guide Version 1.4 Page 7 of 55Confidential and Proprietary
2 EAD Integration Services
2.1 Overview
2.1.1 EAD Integration
Executing transactions in the EAD XML environment involves posting a multi-part MIME containing a well-formed
Extensible Markup Language (XML) file to the appropriate URL. The XML file contains a user id, password, and
connection mode specification (e.g. Synchronous) as well as data specific to the requested business service. The XML
file must be formatted according to the required Document Type Definition (DTD) for the transaction. Format validation
should be done on the client side. A Hypertext Transfer Protocol(s) (HTTPS) POST command is used to submit
transactions to EAD and receive responses. When the transaction is complete, a response multi-part MIME file will be
returned.
2.1.2 EAD Integration URL
The following URLs are used to connect to the EAD integration services:
EAD URLsURL Network Environment
https://direct-intg.electronicappraisaldelivery.com/servicerequest/ Internet Integrationhttps://direct.electronicappraisaldelivery.com/servicerequest/ Internet Production
To minimize customer impact when we make internal changes we do not publish the IP Addresses for the EADURLs. If you have a network configuration that requires this information, please contact Veros.
2.2 Connection Models
The XML Integration Server supports two connection models: Synchronous and PostBack. The followingsections describe the flow of each model.
2.2.1 Synchronous
DefinitionSynchronous is a model of communication where the request and the response are processed in a singleoperation. The requestor initiates the synchronous mode by setting the element: in the service request XML. Posting of a synchronous request will result inEAD returning a response XML envelope and any service output file(s).
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
8/56
EAD Technical Integration Guide Version 1.4 Page 8 of 55Confidential and Proprietary
Sending / Receiving flow diagram
The scenario below demonstrates a synchronous transaction. Under this scenario the results will be included inthe service response.
Synchronous Transaction
Client EAD
Service Request
Service Response
Usage
The table below lists business services that can be requested synchronously. If the service is unavailable or therequest was not received, the user should send the initial request again.
Business Service Average ExecutionTime
Timeout Interval
SubmitAppraisal 10 seconds 2 minutesGetFindings 10 seconds 2 minutes
GetReports 10 seconds 2 minutesMONITOR (Time Service) 1 second 30 seconds
2.2.2 PostBack
DefinitionPostBack is an additional model of communication in which data is transmitted to the customer when results areready. The customer will specify a URL where the responses will be delivered. This model of communicationeliminates the need for the customer to poll for the initial EAD response; the initial response will be deliveredwhen ready to the customers designated PostBack URL. If a request is submitted to more than one investor andthere is a delay between the investor response times, additional PostBack requests will be required as explainedon page 10.
The requestor initiates the PostBack mode by setting the following element and attributes: in the RI XML file. It isimportant that the customer indicates a valid PostBack URL for the transmission to work.
http://www.url.com/http://www.url.com/http://www.url.com/http://www.url.com/7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
9/56
EAD Technical Integration Guide Version 1.4 Page 9 of 55Confidential and Proprietary
Usage
PostBack is designed for long running business services. The table below lists the EAD services that can berequested using PostBack.
Business Service Average Execution
Time
Timeout Interval
GetFindingsWait 10 seconds 2 minutes
Submission of a PostBack request will result in EAD returning a GUID within the response XML envelope. It isrecommended that the returned GUID be placed in a persistent datastore for use later after the output from therequested service is received from the EAD PostBack session. The GUID should be used to correlate the requestto the PostBack response. It is also recommended that you utilize the Conversation ID for request/responsecorrelation which can be defined by the client at the creation of the request.
In the Session 1 diagram below a service request is made in the PostBack mode. The EAD server will return aGUID to the requestor and close the connection. The requestor stores the returned GUID for later use.
The EAD system will initiate Session 2 at a later time (based on business service requirements) and make a
PostBack to the designated URL from the original request. The EAD server will return any available results fromthe initial service request at this time and close the connection. The diagram below demonstrates the PostBackworkflow for a GetFindingsWait transaction. The first PostBack response is initiated when theRECIPIENT_STATUS changes.
PostBack Transaction
Client EAD
Session 1
ServiceRequest(Conversation ID)
ServiceResponse
(GUID)
RECIPIENT_STATUS
In Progress/FHA
Session 2ServiceResponse
towww.url.com
FHA Findings (ifavailable)
HTTP Response
RECIPIENT_STATUS
Successful/FHA
http://www.url.com/http://www.url.com/http://www.url.com/http://www.url.com/http://www.url.com/http://www.url.com/7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
10/56
EAD Technical Integration Guide Version 1.4 Page 10 of 55Confidential and Proprietary
2.3 XML/MIME Data Format
MIME was originally developed as a standard for defining the types of files attached to standard Internet mailmessages. The MIME standard has come to be used in many situations where one computer program needs tocommunicate with another program about what kind of file is being sent.
EAD requests and responses are each composed of one or multiple sections, and a multipartMIME structureallows the caller and the service to communicate about and identify these sections.
Refer to Section 5.7MIME Best Practices for additional guidance.
2.3.1 HTTP and MIME
When your customer application submits a request, the EAD service expects to receive an HTTP header and multipart
MIME stream in the body of the HTTP message. The HTTP header must include the following:
HTTP Post Message Header Request
Content-Typemust be multipart/form-data. This refers to the MIME header parameter in the
message header. All requests must be UTF-8 encoded.
Boundaryparameter must be set and utilized as outlined in RFC 1521. The numbers of dashes
that mark the boundary are significant. The header line that sets the boundary (i.e., boundary="-----------
-92A1B91BE760813DD832E784" ) always has two less dashes than the actual boundary lines. The final
boundary line always ends in two dashes.
MIME Request Header
Content-Dispositionmust be present in each body header and set to form-data. The name and
filename parameters are used as:
i. Nameparameter is required for all body sections. See example below for required stringvalues.
ii. Filenameparameter is optional and can represent the source filename for Business Input
file data.
Content-Typemay be required to specify the type of Business Input file data. See the businessservice definitions in Section 3.
When you receive a response from EAD, the HTTP header will include the following:
HTTP Post Message Header Response
Content-Typewill be multipart/form-data. This refers to the MIME header parameter in the
message header.
Boundaryparameter is set and utilized as outlined in RFC 1521. The numbers of dashes that
mark the boundary are significant. The value of the boundary string is entirely arbitrary. Client
applications must read it and use it to parse the body of the response message, but must make no
assumptions about its value.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
11/56
EAD Technical Integration Guide Version 1.4 Page 11 of 55Confidential and Proprietary
MIME Response Header
Content-Dispositionwill be present in each body header and set to form-data. The name and
filename parameters are used as:
i. Nameparameter is required for all body sections. See example below for required string
values.
ii. Filenameparameter may be returned in the response Business Output sections. See thebusiness service definitions in Section 3.
2.3.2 Request Format
The content of the HTTP post to EAD is multi-part MIME which contains the request XML files and anybusiness data files. Your multipart MIME implementation must conform to the IETF Guidelines. Please refer toRFC 2388, RFC 1806, RFC 822 and RFC 1521 athttp://www.ietf.org for further information.The MIME is comprised of three parts: Routing Input, Control Input, and Business Input.
Routing Input, RI, is an XML file containing information that identifies the requestor, the service
requested and the transaction model. See the Encryption Addendum for additional details.
Control Input, CI, is an XML file containing data required by the service, but not contained in a
business data file.
Business Input, BI, can be any file containing the business data required by a service e.g. an appraisal
file.
The HTTP headers and MIME section boundaries/headers conform to the requirements in section 2.3.1 above.The table below lists the headers required for each section of the MIME:
MIME Section Content-Disposition NameSecure Routing Input form-data EAD_RIControl Input form-data CIBusiness Input form-data Specific data file identifier i.e.
APPRAISAL_1
The MIME Request content is shown in the following example:
POST https://direct.electronicappraisaldelivery.com/ServiceRequest/ HTTP/1.1Content-Type: multipart/form-data; boundary=-------------------7d93d82e30658; charset=UTF-8Accept-Encoding: gzip, deflatePragma: no-cacheHost: direct.electronicappraisaldelivery.comContent-Length: 1359983Connection: Keep-Alive
---------------------7d93d82e30658Content-Disposition: form-data; name="EAD_RI"
bXcCaS97p8TtGzlgZ9ogRcEAaw1D1OQCpk1AQFfWYE5J2CheNtRBpuME+uB3wSkwjIWftkYxQ5JRTQ3Qhz7LrCM+TOORl2lFFTpVC9zGUP1xndfT6EQONViV0XGJieWCzXNyjO3XpEl7IdntkVKucrDN9gA7wlimUdw4Ya5sn08=9BWPkFDt0Ua/2gN9+BDT9XbYHBuadEREIV1EUmvon/jSr0HkndD/9lBo95H3UYD12TL3wmXVSqi7Ak/QqxzmVRDMgw2Wy... Encrypted SECURE_RI data here ...
---------------------7d93d82e30658Content-Disposition: form-data; name="CI"
http://www.ietf.org/http://www.ietf.org/http://www.ietf.org/http://www.w3.org/2001/04/xmlenc#rsa-1_5http://www.w3.org/2001/04/xmlenc#aes128-cbchttp://www.w3.org/2001/04/xmlenc#aes128-cbchttp://www.w3.org/2001/04/xmlenc#aes128-cbchttp://www.w3.org/2001/04/xmlenc#aes128-cbchttp://www.w3.org/2001/04/xmlenc#aes128-cbchttp://www.w3.org/2001/04/xmlenc#rsa-1_5http://www.ietf.org/7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
12/56
EAD Technical Integration Guide Version 1.4 Page 12 of 55Confidential and Proprietary
---------------------7d93d82e30658Content-Disposition: form-data; name="APPRAISAL_1"; filename="00002EAD-AS_MISMO.XML"Content-Type: text/xml
.... Appraisal data here ....
---------------------7d93d82e30658--
2.3.3 Response Format
The format of the response from EAD is multi-part MIME, which contains the response XML files and anyattached output data files. The MIME is comprised of three parts: Routing Output, Control Output, and Business
Output.
Routing Output, RO, is an XML file containing information that identifies the requestor, the service
requested and the transaction model. The input RI will be returned in the response file.
Control Output, CO, is an XML file containing data returned by the service, but not contained in a data
file e.g. Hard Stops, Status, etc.
Business Output, BO, can be any file containing the business data returned from a service e.g. a findings
file.
The HTTP headers and MIME section boundaries/headers conform to the requirements in section 2.3.1 above.The table below lists the headers required for each section of the MIME:
MIME
Section
Content-
Disposition
Content-Type Name
RoutingOutput
form-data text/plain EAD_RO
ControlOutput
form-data text/plain EAD_CO
BusinessOutput
form-data varies Depends on desired business output specifiedin request
The MIME Response content is shown in the following example:
HTTP/1.1 200 OKContent-Type: multipart/form-data; boundary=--------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei-----; charset=UTF-8Server: Microsoft-IIS/7.5
X-Powered-By: ASP.NETDate: Tue, 08 Jun 2014 17:37:26 GMTContent-Length: 1285
----------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei-----Content-Disposition: form-data; filename=EAD_RO; name=EAD_ROContent-Type: text/plain; charset=UTF-8
http://www.w3.org/2001/XMLSchemahttp://mismo.org/schemahttp://mismo.org/schemahttp://www.w3.org/2001/XMLSchema7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
13/56
EAD Technical Integration Guide Version 1.4 Page 13 of 55Confidential and Proprietary
----------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei----- Content-Disposition: form-data; filename=EAD_CO; name=EAD_COContent-Type: text/plain; charset=UTF-8
----------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei-------
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
14/56
EAD Technical Integration Guide Version 1.4 Page 14 of 55Confidential and Proprietary
2.4 Routing Information
2.4.1 Request Group
This section defines the elements associated with making a request to EAD. The envelope elements serve as awrapper around the request data. The Routing Input is required by all services. The Routing Input must also beencrypted before it is transmitted; please see the Encryption Addendum for details.
Routing Input
DTD Reference: RequestGroup.dtd
ELEMENT: REQUEST_GROUPRequired: YesCardinality: 1
Description: This element contains general information to make a request.
Attribute
Format
Required
DescriptionREQUESTING_PARTY Element N Not used at this time.
RECEIVING_PARTY Element N Not used at this time.SUBMITTING_PARTY Element N Not used at this time.REQUEST Element Y Refer to REQUEST element.
ELEMENT: REQUESTRequired: YesCardinality: 1Description: Contains the calling users credentials and the business service to be called.
Attribute Format Required DescriptionRequestDatetime $ Y Date time stamp of request. This must be current and
contain valid time zone information to avoid therequest being rejected due to expiration. TheDateTime format must be in RFC 3339 format.Examples are 2010-06-30T08:43:10-05:00 forEastern Standard Time or 2010-06-30T13:43:10Zfor UTC (Coordinated Universal Time).
InternalAccountIdentifier # N Not used at this time.LoginAccountIdentifier $ Y EAD User ID.LoginAccountPassword $ Y EAD Password.KEY Element N Refer to KEY element.REQUEST_DATA Element Y Refer to REQUEST_DATA element.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
15/56
EAD Technical Integration Guide Version 1.4 Page 15 of 55Confidential and Proprietary
ELEMENT: KEYRequired: NoCardinality: 0 or 1Description: The Conversation ID will persist the transaction and can be used for tracking
purposes.
Attribute Format Required Description_Name $ N _Name = ConversationID
_Value $ N Customer defined transaction identifier.Value is defined by customer.
ELEMENT: REQUEST_DATARequired: YesCardinality: 1
Description: This element defines the EAD Service and Connection mode.
Attribute Format Required Description_GloballyUniqueIdentifier $ N Not used at this time.PRODUCT Element Y See PRODUCT element.
ELEMENT: PRODUCTRequired: YesCardinality: 1Description: Identifies the business service requested. Please see section 3 for the available
business services.
Attribute Format Required Description_Name $ Y Identifies the name of the system, e.g. EAD.
_FunctionName $ Y Identifies the service requested, e.g. SubmitAppraisal._VersionNumber $ Y Identifies the version of the service requested.CONNECTION Element Y Refer to CONNECTION element.
ELEMENT: CONNECTIONRequired: YesCardinality: 1Description: Identifies the connection model and relevant information for this request.
Attribute Format Required Description_ModeIdentifier $ Y Identifies the communication model used to submit the
request.Values:SynchronousPostBack
PostBackURLIdentifier $ C The URL of the web server where the response will beposted. Required if ModeIdentifier = PostBack.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
16/56
EAD Technical Integration Guide Version 1.4 Page 16 of 55Confidential and Proprietary
Example Routing InputSubmit Appraisal
2.4.2 Response Group
This section defines the elements associated with receiving a response from EAD. The envelope elementsserve as a wrapper around the response data. The Routing Output is returned by all services. Please refer to thebusiness services in Section 3 for Control Output and Business Output requirements.
Routing Output
DTD Reference: ResponseGroup.dtd
ELEMENT: RESPONSE_GROUPRequired: YesCardinality: 1
Description: This element contains information returned in a response.
Attribute Format Required DescriptionRESPONDING_PARTY Element N Not used at this time.RESPOND_TO_PARTY Element N Not used at this time.RESPONSE Element Y Refer to RESPONSE element.
ELEMENT: RESPONSERequired: YesCardinality: 1Description: This element contains information returned in a response.
Attribute Format Required DescriptionResponseDatetime $ N Date time stamp of response.InternalAccountIdentifier # N Not used at this time.LoginAccountIdentifier $ N Not used at this time.LoginAccountPassword $ N Not used at this time.KEY Element N Refer to KEY element.
RESPONSE_DATA Element N Refer to RESPONSE _DATA element.STATUS Element Y Refer to STATUS element.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
17/56
EAD Technical Integration Guide Version 1.4 Page 17 of 55Confidential and Proprietary
ELEMENT: KEYRequired: NoCardinality: 0 or 1Description: The Conversation ID will persist the transaction and can be used for tracking
purposes.
Attribute Format Required Description_Name $ N _Name = ConversationID
_Value $ N Customer defined transaction identifier.Value is defined by customer.
ELEMENT: RESPONSE_DATARequired: NoCardinality: 0 or 1
Description: Element contains the GUID returned by EAD.
Attribute Format Required Description_GloballyUniqueIdentifier $ N Globally Unique Identifier (GUID) that is returned by
EAD and is used to retrieve the results.PRODUCT Element N See PRODUCT element.
ELEMENT: PRODUCTRequired: NoCardinality: 0 or 1
Description: Identifies the EAD product or service requested.
Attribute Format Required Description_Name $ Y Identifies the name of the system, e.g. EAD.
_FunctionName $ Y Identifies the service requested, e.g. SubmitAppraisal._VersionNumber $ Y Identifies the version of the service requested.
ELEMENT: STATUSRequired: YesCardinality: 1Description: Contains EAD application level error information if one occurs. Please note this
element does not include errors from the requested business service. Please refer toAppendix B, EAD Error Codes, for a list of potential errors.
Attribute Format Required Description_Condition $ Y The EAD error condition._ Name
$
Y
The EAD error name.
_Description $ Y The text description of the error from EAD._Code $ Y Code that identifies the EAD error.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
18/56
EAD Technical Integration Guide Version 1.4 Page 18 of 55Confidential and Proprietary
Example Routing OutputSynchronous Response from GetFindings Service
Example Routing OutputInitial PostBack Response from GetFindingsWait Service
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
19/56
EAD Technical Integration Guide Version 1.4 Page 19 of 55Confidential and Proprietary
2.5 STATUS_LOG
When a failure occurs or UAD messages are present the STATUS_LOG will be returned asBusiness Output andshould be parsed and displayed to the end user. The STATUS_LOG provides additional detailed information thathelps the user identify what action is required. The information also assists in the troubleshooting process if
contacting a help desk is necessary. The STATUS_LOG is returned in the MIME sectionname=EAD_STATUS_LOG .
Service ErrorsIf a request encounters multiple errors, only a single error code can be returned in the EAD_CO STATUSelement, but all applicable errors will be returned in the STATUS_LOG.
----------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei-----Content-Disposition: form-data; filename=EAD_STATUS_LOG; name=EAD_STATUS_LOGContent-Type: text/plain; charset=UTF-8
UAD Compliance Check
EAD will return an error message to the user if certain data is not provided or does not conform to thecompliance rules defined in the UAD Specification and its appendices.
When an appraisal has failed one or more UAD Compliance rules checks, EAD will return a Hard Stop Code 401(if one or more of the rules are Fatal severity) or 402 (if all of the rules are Warning severity). For each appraisalthat has received a Hard Stop Code 401 or 402, the errors that contributed to the Hard Stop are returned in theSTATUS_LOG in the response to a GetFindings or GetFindingsWait call.
The example below contains both a warning and fatal edit.
----------ieoau._._+2_8_GoodLuck8.3-ds0d0J0S0Kl234324jfLdsjfdAuaoei-----Content-Disposition: form-data; filename=EAD_STATUS_LOG; name=EAD_STATUS_LOGContent-Type: text/plain; charset=UTF-8
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
20/56
EAD Technical Integration Guide Version 1.4 Page 20 of 55Confidential and Proprietary
3 EAD Business Services
3.1 Overview
The following service versions are currently supported by EAD:
_Name _FunctionName _VersionNumberEAD SubmitAppraisal 1.0EAD GetFindings 1.0EAD GetFindingsWait 1.0EAD GetReports 1.0MONITOR ReturnEST 2.0
3.1.1 Submit Appraisal
This service is used to submit appraisal data prior to loan endorsement. Appraisals may be submitted in one ofthe supported XML formats (MISMO 2.6, MISMO 2.6 Errata 1, MISMO 2.6GSE). Submissions in XML formatmust also include an embedded copy of the first-generation appraisal PDF file.
Upon first submission, the request will be assigned a Document File ID by EAD. If submitting aresubmission/correction, this identifier should be referenced to avoid having the submission rejected as aduplicate submission for the loan. For product types where two or three appraisals are required, multipleappraisals may be submitted together, and will be associated with the same Document File ID.
After submission, an initial confirmation of receipt will be returned. Findings may be retrieved through theGetFindings service and/or through the EAD web portal.
3.1.2 Get Findings
This service is used to retrieve findings generated by EAD after your submission has been evaluated.
The processing status of the submission (in progress, success, failure, override requested) is returned by thisservice. It is recommended that submitters poll the Get Findings service to ensure that their submissions havebeen processed successfully, to retrieve findings, or to retrieve Hard Stop messages in the case of a failure.
If a submission has failed and Hard Stop messages have been received through this service, a request to overridesome types of Hard Stops can be submitted through the Submit Appraisal service.
3.1.3 Get Findings Wait
This service is a variant of the Get Findings Service that is designed for clients who implement a PostBackservice.
3.1.4 Get Reports
This service is used to retrieve reports from EAD. Currently, the Submission Summary Report (SSR) is availablethrough this service.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
21/56
EAD Technical Integration Guide Version 1.4 Page 21 of 55Confidential and Proprietary
3.1.5 Successful Transaction Workflow
The diagram below demonstrates a successful Submit Appraisal request and two subsequent Get Findingsrequests to obtain the results. While EAD is processing the appraisal, Get Findings returns the recipient statusIN PROGRESS. Once the appraisal has been processed and has no hard stops that need to be addressed, GetFindings returns the recipient status SUCCESSFUL.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
22/56
EAD Technical Integration Guide Version 1.4 Page 22 of 55Confidential and Proprietary
3.1.6 Hard Stop - Overr ide Workflow
The diagram below demonstrates the workflow for resolving an overridable hard stop. As above, the SubmitAppraisal request results in the issuance of a Document File ID. After the appraisal has been processed by EAD,the call to Get Findings indicates that the recipient status of NOT SUCCESSFULand returns the hard stopsthat apply to the appraisal. The submitter then calls Submit Appraisal again to submit a hard stop override
request, and after that request is approved by the system, a final call to Get Findings indicates that the recipientstatus is now SUCCESSFUL.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
23/56
EAD Technical Integration Guide Version 1.4 Page 23 of 55Confidential and Proprietary
3.2 Submit Appraisal
Description
This service is used to submit appraisal data in designated XML format, or to provide updates or corrections toan existing submission.
The format for a Submit Appraisal request is comprised of the following files and MIME sections:
MIME Section Content-Disposition NameRouting Input Form-data EAD_RIControl Input Form-data CIBusiness Input Form-data APPRAISAL_1Business Input Form-data APPRAISAL_2 *Business Input Form-data APPRAISAL_3 *
* A single appraisal is required for the vast majority of submissions to EAD. Where there are changes to the
single appraisal, those updates should be resubmitted as a replacement/update to Appraisal 1. A secondary ortertiary appraisal data file should only be submitted where additional appraisals are used as part of theunderwriting decision or if an update or report of reinspection is required.
The format for a Submit Appraisal response is comprised of the following files and MIME sections
MIME Section Content-Disposition NameRouting Output Form-data EAD_ROControl Output Form-data EAD_CO
Routing I nput
The Submit Appraisal service supports the Synchronous connection mode.
PRODUCT
_Name: EAD_FunctionName: SubmitAppraisal_VersionNumber: 1.0
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
24/56
EAD Technical Integration Guide Version 1.4 Page 24 of 55Confidential and Proprietary
Control I nput
DTD Reference: EADSubmitAppraisalRequest_v1_0.dtd
ELEMENT: SUBMIT_APPRAISAL_REQUESTRequired: Yes
Cardinality: 1Description: This element contains all required information for a Submit Appraisal request.
Attribute Format Required DescriptionLenderLoanNumber $15 C Number used by the Lender to identify a loan. This
number must be provided on initial submissions andmay be included on resubmissions if it has changed.
EADDocumentFileIdentifier $10 C A unique number generated by EAD to track theappraisal documents submitted for a loan. Thisnumber must be provided when sending aresubmission/correction.
EADBusinessUnitNumber $8 C Identifies the business unit with which an initialsubmission should be associated. This value mustonly be provided for initial submissions (it may not
be changed after the initial submission).SOFTWARE_PROVIDER Element Y Please see SOFTWARE_PROVIDER element.RECIPIENT_FHA Element C Please see RECIPIENT_FHA element.DATA_FILE Element N Please see DATA_FILE element.OVERRIDE_REQUEST Element N Please see OVERRIDE_REQUEST element.DELETE_FILE Element N Please see DELETE_FILE element.
On an initial submission:
When an appraisal is initially submitted to EAD, the Lender Loan Number, DATA_FILE,SOFTWARE_PROVIDER and RECIPIENT_FHA are required. The Business Unit Number must alsobe specified.
If you are a lender, your EAD lender administrator may have configured multiple business units in EAD
to represent your company's organizational hierarchy. The business unit you specify will determine
which users may access your submission. Please contact your EAD lender administrator to determine
the proper Business Unit Number to be used.
If you are a lender agent, you have the ability to submit appraisals on behalf of one or more lenders. The
business unit you specify will determine which lender you are submitting for, and which Lender IDs are
available for use. Please contact your EAD lender agent administrator to determine the proper Business
Unit Number to be used for each lender.
On a resubmission:
The DocumentFileIdentifier is generated by EAD after the initial submission of appraisal data for aloan. To resubmit appraisal data for updates or corrections, this identifier must be populated with theproper value; otherwise, a duplicate check will reject the submission.
If the Lender Loan Number has changed, it may be updated through direct integration or the EAD webportal. To correct a value through direct integration, provide the new value in theSUBMIT_APPRAISAL_REQUEST element.
A resubmission may include any one or more of the following: (1) updates to the Lender Loan Number
or FHA attributes, (2) an updated appraisal file to replace a previously submitted file, or (3) a new
Secondary Appraisal file to be added to a previous submission.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
25/56
EAD Technical Integration Guide Version 1.4 Page 25 of 55Confidential and Proprietary
To update an FHA attribute:
To update FHA attributes after the initial submission, include the RECIPIENT_FHA element with the
new attribute values. If you are not changing any of the attributes for FHA, this element is not required
in the request.
To request a Hard Stop override:
If you received notification of a Hard Stop error in the results from a call to GetFindings, you may also
use the SubmitAppraisal service to request an override. Include an OVERRIDE_REQUEST element for
each Hard Stop that should be overridden. Resubmissions and Hard Stop override requests may not be
combined in a single request.
ELEMENT: SOFTWARE_PROVIDERRequired: YesCardinality: 1
Description: This element provides the account information.
Attribute Format Required Description_AccountNumber $9 Y Please contact Veros for your account number.
ELEMENT: RECIPIENT_FHARequired: NoCardinality: 0 or 1Description: This element contains all information specific to a submission to FHA. It must be
included when initially submitting an appraisal to FHA. It may also be included whenmaking subsequent updates to FHA attributes.
Attribute Format Required DescriptionFHALenderID #5 C The Title II Lender ID of the lender by which the
appraisal(s) will be delivered to FHA. This value isrequired on an initial submission. When makingupdates to FHA attributes, this value is not requiredif it has not changed.
HUDCaseNumber $11 C The FHA Case Number associated with theproperty being appraised. This value is required onan initial submission. When making updates toFHA attributes, this value is not required if it hasnot changed. Format must be ###-#######. Any
program type suffix should not be included.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
26/56
EAD Technical Integration Guide Version 1.4 Page 26 of 55Confidential and Proprietary
ELEMENT: DATA_FILERequired: NoCardinality: 0 or moreDescription: The APPRAISAL file in any of the supported formats is required. When required, the
1004MC Market Conditions Addendum data should be included in the same file asthe appraisal. For some products, an APPRAISAL_2 and/or APPRAISAL_3 file mayalso be required. Submissions in designated XML format should also include anembedded copy of the appraisal first generation PDF file.
The following appraisal form types are supported:
Uniform Residential Appraisal Report (FNM 1004/FRE 70)
Manufactured Home Appraisal Report (FNM 1004C/FRE 70B)
Small Residential Income Property Appraisal Report (FNM 1025/FRE 72)
Individual Condominium Unit Appraisal Report (FNM 1073/FRE 465)
Appraisal Update and/or Completion Report (FNM 1004D/FRE 442) *
* The Appraisal Update and/or Completion Report form may only be submitted as anAPPRAISAL_2 or APPRAISAL_3 file. One of the other supported appraisal formtypes must be submitted or be already present as APPRAISAL_1.
Attribute Format Required Description_Type $ Y Values:
1004/701004C/70B1025/721073/4651004D/442
_FormatType $ Y MISMO_VersionNumber $ C The version number indicates whether the appraisal file is UAD
compliant. UAD specifications are not available for all forms. Validvalues for all forms are listed below.
Valid Values for reviewed for UAD Compliance (1004/70, 1073/465):
UAD = indicates appraisal is UAD compliantBlank = indicates appraisal is legacy form prior to UADstandard
Valid values for all other Forms (1004C/70B, 1025/72, 1004D/442)
Blank = indicates appraisal is form to which UAD standarddoes not apply
_Name $ Y APPRAISAL_1APPRAISAL_2APPRAISAL_3
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
27/56
EAD Technical Integration Guide Version 1.4 Page 27 of 55Confidential and Proprietary
ELEMENT: OVERRIDE_REQUESTRequired: NoCardinality: 0 or more
Description: This element provides a request for a Hard Stop override.
Attribute Format Required Description_Name $ C The name of the file that caused the Hard Stop.
This attribute must be included if the Hard Stop isfile-specific. Possible values:APPRAISAL_1APPRAISAL_2APPRAISAL_3
_HardStopCode $ Y The code representing the Hard Stop type thatshould be overridden. Please see Appendix A for alist of potential values.
_ReasonCode $ Y The code representing the reason why the HardStop should be overridden. Please see Appendix Afor a list of potential values.
_ReasonComment $250 N A brief comment to help justify the reason forrequesting the override. Any text over 250characters in length will be truncated.
An OVERRIDE_REQUEST element may not be included in a request that also contains aDATA_FILE, Updated Loan Number or Investor Attributes, or a DELETE_FILE element.
ELEMENT: DELETE_FILERequired: NoCardinality: 0 or moreDescription: This element allows you to remove a secondary or tertiary file from the submission if
it was uploaded in error.
Attribute Format Required Description_Name $ Y The name of the file to be deleted from the
document file. Possible values:APPRAISAL_2APPRAISAL_3
Typically, a file that requires corrections should be replaced with an updated file using the DATA_FILEelement. However, if a file was uploaded in error and should be deleted completely from the documentfile, use the DELETE_FILE element. Every Document File must have an APPRAISAL_1 file, so theAPPRAISAL_1 file cannot be deleted, only replaced.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
28/56
EAD Technical Integration Guide Version 1.4 Page 28 of 55Confidential and Proprietary
Example Control InputSubmitAppraisal (Submit Appraisal)
Example Control InputSubmitAppraisal (Submit Two Appraisals)
Example Control Input
SubmitAppraisal (Change Loan Number)
Example Control InputSubmitAppraisal (Change FHA Case Number and Loan Number)
Example Control InputSubmitAppraisal (Upload Corrected Appraisal)
Example Control InputSubmitAppraisal (Add Secondary Appraisal)
Example Control InputSubmitAppraisal (Request Hard Stop Overrides)
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
29/56
EAD Technical Integration Guide Version 1.4 Page 29 of 55Confidential and Proprietary
Example Control InputSubmitAppraisal (Delete Appraisal 2 file)
Business Input
For an initial Submit Appraisal Request the appraisal XML file must be included as Business Input. Thesecondary appraisal file is Optional. Files must be UTF-8 encoded. The following Content-Type declarationmust be included in the Business Input BI MIME section:
XML files: use either
Content-Type: text/xml
Content-Type: text/plain
Valid files include the following:
APPRAISAL_1: Supported appraisal form (except 1004D/442), in a supported XML format.
Optional Additional Files:
APPRAISAL_2 and/or APPRAISAL_3 containing any supported appraisal form in a supported XMLformat.
Control Output
DTD Reference: EADSubmitAppraisalResponse_v1_0.dtd
ELEMENT: SUBMIT_APPRAISAL_RESPONSERequired: YesCardinality: 1
Description: This element contains the response to the submission.
Attribute Format Required DescriptionDocumentFileIdentifier $10 C A unique number generated by EAD to track the
appraisal documents submitted for a loan. ADocumentFileIdentifier may not be generated fornew submissions that contain errors.
LenderLoanNumber $15 Y Number used by the Lender to identify a loan.STATUS Element Y Please see the STATUS element.RECIPIENT_FHA Element C Please see the RECIPIENT_FHA element.
ELEMENT: STATUSRequired: YesCardinality: 1Description: This element contains error messages from the requested business service.
Attribute Format Required Description_Condition $ Y SUCCESS or FAILURE._ Name $ Y SERVICE
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
30/56
EAD Technical Integration Guide Version 1.4 Page 30 of 55Confidential and Proprietary
_Description $ Y Text Description of the status or error._Code $ Y Code associated with the error. Please see Appendix A
for a list of potential values.
ELEMENT: RECIPIENT_FHARequired: Conditional
Cardinality: 0 or 1Description: This element contains information specific to a submission to FHA.
Attribute Format Required DescriptionFHALenderID #5 Y The Title II Lender ID of the lender by which the
appraisal(s) will be delivered to FHA.HUDCaseNumber $11 Y The FHA Case Number associated with the
property being appraised. Format will be ###-#######. Any program type suffix will not beincluded.
Example Control OutputSubmit Appraisal
3.3 Get Findings
Description
This service is used to check on the status of an appraisal submission and retrieve findings.
The format for a Get Findings request is comprised of the following MIME sections:
MIME Section Content-Disposition NameRouting Input Form-data EAD_RIControl Input Form-data CI
The format for a Get Findings response is comprised of the following files and MIME sections:
MIME Section Content-Disposition NameRouting Output Form-data EAD_ROControl Output Form-data EAD_COBusiness Output Form-data 0 or more files based on
_RETURN_FILE element if
findings are available
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
31/56
EAD Technical Integration Guide Version 1.4 Page 31 of 55Confidential and Proprietary
Routing I nput
The Get Findings Service supports the Synchronous connection mode only. For the PostBack connection mode, use the
GetFindingsWait service described in section 3.4 below.
PRODUCT
_Name: EAD_FunctionName: GetFindings_VersionNumber: 1.0
Control I nput
DTD Reference: EADGetFindingsRequest_v1_0.dtd
ELEMENT: GET_FINDINGS_REQUESTRequired: YesCardinality: 1
Description: This element contains all required information for a Get Findings request.
Attribute Format Required DescriptionEADDocumentFileIdentifier $10 Y A unique number generated by EAD to track the
appraisal documents submitted for a loan._RETURN_FILE Element N Please see _RETURN_FILE element.SOFTWARE_PROVIDER Element Y Please see SOFTWARE_PROVIDER element.
ELEMENT: _RETURN_FILERequired: NoCardinality: 0 or more
Description: This element contains the list of requested return files.
Attribute Format Required Description_FileType $ Y Values:
FHA_FINDINGS_XMLFHA_FINDINGS_HTML
Note: No Output Files are returned to therequester by default. If output files arerequired, the _RETURN_FILE element must bepopulated.
ELEMENT: SOFTWARE_PROVIDERRequired: YesCardinality: 1Description: This element provides the account information.
Attribute Format Required Description_AccountNumber $9 Y Please contact Veros for your account number.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
32/56
EAD Technical Integration Guide Version 1.4 Page 32 of 55Confidential and Proprietary
Example Control InputGet Findings
Control Output
DTD Reference: EADGetFindingsResponse_v1_0.dtd
ELEMENT: GET_FINDINGS_RESPONSERequired: YesCardinality: 1
Description: This element contains the available information for the specified Document File.
Attribute Format Required DescriptionDocumentFileIdentifier $10 Y A unique number generated by EAD to track the
appraisal documents submitted for a loan.LenderLoanNumber $15 Y Number used by the Lender to identify a loan.STATUS Element Y Please see the STATUS element.RECIPIENT_STATUS Element C Please see the RECIPIENT_STATUS element.RECIPIENT_FHA Element C Please see the RECIPIENT_FHA element.HARD_STOP Element N Please see the HARD_STOP element.FINDINGS_SUMMARY Element N Please see the FINDINGS_SUMMARY element.
ELEMENT: STATUSRequired: YesCardinality: 1
Description: This element contains error messages from the requested business service.
Attribute Format Required Description_Condition $ Y SUCCESS or FAILURE._ Name $ Y SERVICE_Description $ Y Text Description of the error._Code $ Y Code associated with the error. Please see Appendix A
for a list of potential values.
ELEMENT: RECIPIENT_STATUSRequired: YesCardinality: 0 or moreDescription: This element contains error messages from the processing of the submission by EAD.
This element may not be returned if the service call resulted in an error (see STATUS
element above).
Attribute Format Required Description_Name $ Y Recipient name
Values:FHA: Federal Housing Administration
_Condition $ Y SUCCESSFUL, IN PROGRESS, OVERRIDEREQUESTED or NOT SUCCESSFUL.
_Description $ Y Text Description of the status.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
33/56
EAD Technical Integration Guide Version 1.4 Page 33 of 55Confidential and Proprietary
_Code $ Y Code associated with the status. Please see AppendixA for a list of potential values.
ELEMENT: RECIPIENT_FHARequired: Conditional
Cardinality: 0 or 1Description: This element contains all information specific to a submission to FHA.
Attribute Format Required DescriptionFHALenderID #5 Y The Title II Lender ID of the lender by which the
appraisal(s) will be delivered to FHA.HUDCaseNumber $11 Y The FHA Case Number associated with the
property being appraised. Format will be ###-#######. Any program type suffix will not beincluded.
ELEMENT: HARD_STOPRequired: No
Cardinality: 0 or moreDescription: These elements contain the Hard Stop errors encountered while processing the
appraisal submission. Appendix A lists the current Hard Stop codes, but since newcodes may be added in the future, your implementation must not fail whenencountering a code that is not recognized.
Attribute Format Required Description_Name $ C The name of the file that caused the Hard Stop. This
attribute will be included if the Hard Stop is file-specific. Possible values:APPRAISAL_1APPRAISAL_2APPRAISAL_3
_Description $ Y Text Description of the error._Code $ Y Code associated with the error. Please see Appendix
A for a list of potential values._OverrideStatus $ N APPROVED, IN PROGRESS, DENIED_OverrideDecisionCode $ N The code representing the reason why the Hard Stop
override request was approved or denied. Please seeAppendix A for a list of potential values.
_OverrideDecisionDescription $ N Text description of the override decision._OverrideDecisionComment $ N A brief comment providing additional information
about the override request approval or denial.HARD_STOP_RECIPIENT Element Y Please see the HARD_STOP_RECIPIENT element.
ELEMENT: HARD_STOP_RECIPIENTRequired: YesCardinality: 1 or moreDescription: This element identifies the recipient to whom the hard stop is associated.
Attribute Format Required Description_Name $ Y Recipient name
Values:FHA: Federal Housing Administration
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
34/56
EAD Technical Integration Guide Version 1.4 Page 34 of 55Confidential and Proprietary
ELEMENT: FINDINGS_SUMMARYRequired: NoCardinality: 0 or more
Description: This element identifies the Findings Report files returned.
Attribute Format Required Description_Recipient $ Y Recipient name
Values:FHA: Federal Housing Administration
_Format $ Y Values:HTMLXML
The returned format(s) are determined by theinput element _RETURN_FILE.
_Name $ Y The nameparameter for the Business Output MIMESection containing the report data.
_Filename $ Y The filenameparameter for the Business OutputMIME Section containing the report data.
Example Control OutputGet Findings (Submission Processing in Progress)
Example Control OutputGet Findings (Submission Successful)
Example Control OutputGet Findings (Fatal Hard Stops)
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
35/56
EAD Technical Integration Guide Version 1.4 Page 35 of 55Confidential and Proprietary
Example Control Output
Get Findings (Overridable Hard Stops)
Example Control OutputGet Findings (Hard Stop Override Request in Progress)
In the following example, one Hard Stop override request has been accepted, but the other is still pending:
Example Control OutputGet Findings (Hard Stop Override Requests Approved)
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
36/56
EAD Technical Integration Guide Version 1.4 Page 36 of 55Confidential and Proprietary
Example Control OutputGet Findings (Hard Stop Override Request Denied)
In the following example, one of the Hard Stop override requests has been denied, so the submission has notbeen accepted:
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
37/56
EAD Technical Integration Guide Version 1.4 Page 37 of 55Confidential and Proprietary
Business Output
The Business Output for a GetFindings Request will include the STATUS LOG if an error or one or more UADMessages is encountered. The Business Output will also include FHA findings if requested in the Control Inputand available. The following table lists the current file and its location within the MIME Response.
File Description MIME LocationName FileName
Status Log EAD_STATUS_LOG EAD_STATUS_LOGFHA Findings XML Derived from Control Output Derived from Control OutputFHA Findings HTML Derived from Control Output Derived from Control Output
Status Log Definition
DTD Reference: EAD_STATUS_LOG_v1_1.dtd
ELEMENT: STATUS_LOGRequired: No
Cardinality: 1Description: This element contains error messages and UAD compliance messages.
Attribute Format Required DescriptionSERVICE_ERRORS Element N Please see the SERVICE_ERRORS element.UAD_COMPLIANCE_ERRORS Element N Please see the UAD_COMPLIANCE_ERRORS
element.
ELEMENT: SERVICE_ERRORSRequired: NoCardinality: 0 or 1
Description: This element contains one or more error message from EAD.
Attribute Format Required DescriptionSERVICE_ERROR Element Y Please see the SERVICE_ERROR element.
ELEMENT: SERVICE_ERRORRequired: NoCardinality: 1 or more
Description: This element contains a specific error message from EAD.
Attribute Format Required Description_Code $ Y Code associated with the error. Please see Appendix A
for a list of potential values._Description $ Y Text Description of the error.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
38/56
EAD Technical Integration Guide Version 1.4 Page 38 of 55Confidential and Proprietary
ELEMENT: UAD_COMPLIANCE_ERRORSRequired: NoCardinality: 0 or 1
Description: This element contains one or more UAD messages from EAD.
Attribute Format Required Description_Name $ Y Identifies to which appraisal UAD Message is
relatedSubmissionDateTime $ Y Datetime of submission.UAD_COMPLIANCE_ERROR Element Y Please see the UAD_COMPLIANCE_ERROR
element.
ELEMENT: UAD_COMPLIANCE_ERRORRequired: NoCardinality: 1 or more
Description: This element contains a specific UAD message from EAD.
Attribute Format Required Description_Code $4000 Y Code associated with the error. Please see the UAD
Message List.FormSection $4000 Y Identifies the section within the appraisal to which themessage is related.
FormField $4000 Y Identifies the form field within the appraisal to whichthe message is related.
DataPoint $4000 Y Identifies the specific data point within the appraisal towhich the message is related.
PropertyAffected $14 Y Identifies the affected property within the appraisal towhich the message is related.
ActionMessage $1000 Y Description of the action needed to resolve themessage.
_Severity $4000 Y Describes the severity of the message:- Fatal- Warning
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
39/56
EAD Technical Integration Guide Version 1.4 Page 39 of 55Confidential and Proprietary
FHA Findings XML Definition
If FHA findings are available, the file(s) requested in the RETURN_FILE element will be returned. Thefollowing defines the file structure for FHA XML Findings.
DTD Reference: EAD_FINDINGS_MESSAGES_LOG_v1_0.dtd
ELEMENT: FINDINGS_MESSAGES_LOGRequired: YesCardinality: 1Description: This element contains findings for up to three appraisals, based on how many
appraisals were submitted to EAD and have findings available.
Attribute Format Required DescriptionFINDINGS_MESSAGES Element Y Please see the FINDINGS_MESSAGES element.
ELEMENT: FINDINGS_MESSAGESRequired: YesCardinality: 1 or more
Description: This element contains one or more findings messages for the specified appraisal.
Attribute Format Required Description_Name $ Y Identifies to which appraisal Findings Message is
relatedRecipient $ Y FHASubmissionDateTime $ Y Datetime of submission.
FINDINGS_MESSAGE Element Y Please see the FINDINGS_MESSAGE element.
ELEMENT: FINDINGS_MESSAGERequired: Yes
Cardinality: 1 or moreDescription: This element contains a specific Findings Message.
Attribute Format Required Description_Code $10 Y Code associated with the message. Please contact FHA
for complete list of messages.FormSection $100 Y Identifies the section within the appraisal to which the
message is related.FormField $300 Y Identifies the form field within the appraisal to which
the message is related.DataPoint $100 Y Identifies the specific data point within the appraisal to
which the message is related.PropertyAffected $100 Y Identifies the affected property within the appraisal to
which the message is related.ActionMessage $4000 Y Description of the action needed to resolve the
message._Severity $100 Y Describes the severity of the message:
- Fatal- Warning- Overridable
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
40/56
EAD Technical Integration Guide Version 1.4 Page 40 of 55Confidential and Proprietary
3.4 Get Findings Wait
Description
This service is used to check on the status of an appraisal submission and retrieve findings. The GetFindingsWaitservice is identical to the GetFindings function described above, but its response model is tailored for thePostBack connection mode.
Clients that choose to implement the PostBack model will typically want the EAD Service to wait to respond ifthe specified Document File ID is still being processed by the system. Utilizing the GetFindingsWait service callallows the client to make reduced calls to the service, and receive a PostBack response only when the processingof the desired Document File has resulted in a SUCCESSFUL or NOT SUCCESSFUL status. If processingresults are complete when the request is received, the PostBack response will be sent immediately.
Routing I nput
The GetFindingsWait Service supports the PostBack connection mode only. For the Synchronous connection mode, use
the GetFindings service described in section 3.3 above.
PRODUCT
_Name: EAD_FunctionName: GetFindingsWait_VersionNumber: 1.0
Control I nput
DTD Reference: EADGetFindingsRequest_v1_0.dtd
The Control Input is identical to that of GetFindings.
Control Output
DTD Reference: EADGetFindingsResponse_v1_0.dtd
The Control Output is identical to that of GetFindings.
Business Output
The Business Output is identical to that of GetFindings.
3.5 Get Reports
Description
This service is used to retrieve reports from EAD. Currently, the Submission Summary Report (SSR) is availablethrough this service.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
41/56
EAD Technical Integration Guide Version 1.4 Page 41 of 55Confidential and Proprietary
The format for a Get Reports request is comprised of the following MIME sections:
MIME Section Content-Disposition NameRouting Input Form-data EAD_RIControl Input Form-data CI
The format for a Get Reports response is comprised of the following files and MIME sections:
MIME Section Content-Disposition NameRouting Output Form-data EAD_ROControl Output Form-data EAD_COBusiness Output Form-data 0 or more files based on
availability of reports
Routing I nput
The GetReports Service supports the Synchronous connection mode only.
PRODUCT
_Name: EAD_FunctionName: GetReports_VersionNumber: 1.0
Control I nput
DTD Reference: EADGetReportsRequest_v1_0.dtd
ELEMENT: GET_REPORTS_REQUESTRequired: YesCardinality: 1
Description: This element contains all required information for a Get Reports request.
Attribute Format Required DescriptionRETURN_SSR Element N Please see RETURN_SSR element.SOFTWARE_PROVIDER Element Y Please see SOFTWARE_PROVIDER element.
ELEMENT: RETURN_SSRRequired: NoCardinality: 0 or 1Description: This element contains the details of a Submission Summary Report (SSR) request.
Attribute Format Required Description
EADDocumentFileIdentifier $10 Y A unique number generated by EAD to track theappraisal documents submitted for a loan._EADRecipient $ Y Recipient name
Values:FHA: Federal Housing AdministrationALL: Federal Housing Administration
_Format $ Y Values:PDF
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
42/56
EAD Technical Integration Guide Version 1.4 Page 42 of 55Confidential and Proprietary
ELEMENT: SOFTWARE_PROVIDERRequired: YesCardinality: 1
Description: This element provides the account information.
Attribute Format Required Description_AccountNumber $9 Y Please contact Veros for your account number.
Example Control InputGet Reports
Control Output
DTD Reference: EADGetReportsResponse_v1_0.dtd
ELEMENT: GET_REPORTS_RESPONSERequired: YesCardinality: 1
Description: This element contains the requested reports.
Attribute Format Required DescriptionSTATUS Element Y Please see the STATUS element.RETURN_SSR_DATA Element N Please see the RETURN_SSR_DATA element.
ELEMENT: STATUSRequired: YesCardinality: 1
Description: This element contains error messages from the requested business service.
Attribute Format Required Description_Condition $ Y SUCCESS or FAILURE._ Name $ Y SERVICE_Description $ Y Text Description of the error._Code $ Y Code associated with the error. Please see Appendix A
for a list of potential values.
ELEMENT: RETURN_SSR_DATARequired: NoCardinality: 0 or moreDescription: This element identifies the SSR report files returned.
Attribute Format Required DescriptionDocumentFileIdentifier $10 Y A unique number generated by EAD to track the
appraisal documents submitted for a loan.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
43/56
EAD Technical Integration Guide Version 1.4 Page 43 of 55Confidential and Proprietary
_Recipient $ Y Recipient nameValues:FHA: Federal Housing Administration
_Format $ Y Values:PDF
_Name $ Y The nameparameter for the Business Output MIMESection containing the report data.
_Filename $ Y The filenameparameter for the Business OutputMIME Section containing the report data.
Example Control OutputGet Reports
Business Output
The Business Output for a Get Reports request corresponds to the RETURN_SSR_DATA elements in theControl Output. Each returned report indicated in the Control Output will have a corresponding Business OutputMIME section. Files in PDF format will be Base64 encoded. The Business Output MIME sections for the aboveControl Output example are shown below:
---------------------7d93d82e30658Content-Disposition: form-data; filename="SSR_FHA_DocumentFileID.pdf", name="BO_EAD1"Content-Type: application/pdfContent-Transfer-Encoding: base64
012345ABC... base64 PDF data here ...
012345ABC
---------------------7d93d82e30658--
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
44/56
EAD Technical Integration Guide Version 1.4 Page 44 of 55Confidential and Proprietary
4 Error Handling
There are two types of errors that can occur using the EAD interface: EAD errors and Business Service errors.
EAD Errors are specific to the formatting of the MIME file and the validation of the user id. If any part of theMIME file is not well formatted or is missing data you will receive an EAD Error. You will also receive an EAD
error if the User ID is not authenticated for the requested business service. For a complete list of EAD Errorsplease refer to Appendix B. These errors will be returned in the STATUS element of theRouting Outputresponse xml file.
Example RO STATUS Element:
When there is not an EAD error, the STATUS element will contain the following parameters:
Business Errors are errors returned from the service requested e.g. SubmitAppraisal, GetFindings, etc.Examplesof such errors include invalid Control Input request parameters or structure, or user accountauthorization. When a Business error occurs, the _Condition attribute in the STATUS element in the ControlOutput response file will be FAILURE. The_Description and_Code attributes will contain information aboutthe critical error. For a complete list of errors please refer to Appendix A (Status/Error Codes).
When a failure occurs the STATUS_LOG will be returned asBusiness Output and should be displayed to the enduser. The STATUS_LOG provides additional detailed information that helps the user identify what action isrequired. The information also assists in the trouble shooting process if contacting a help desk is necessary.Please refer to the next pages for an Example Error Workflow and STATUS_LOG.
Example CO STATUS Element:
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
45/56
EAD Technical Integration Guide Version 1.4 Page 45 of 55Confidential and Proprietary
FAILURE
SUCCESS
Error HandlingResponse
MIME file
Routing
Output
Using Appendix B
determine error from
_Code A ttribute
_Condition =
ERRORCheck
STATUS_Condition
attribute
_Condition =
PROCESSINGUsing Appendix B
determine request status
from _Code Attribute
_Condition = DONE
Control
Output
Check Attribute
STATUS_Condition
for "FAILURE" or
"SUCCESS"
Process
Successful
Response Data
Perform exception
processing based on
_Code and _Description
Attribute
Business
OutputSTATUS_LOG
Display STATUS_
LOG to user
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
46/56
EAD Technical Integration Guide Version 1.4 Page 46 of 55Confidential and Proprietary
5 EAD Integration Recommendations
Overview
Whether you are building or buying specific components for your solution, your implementation must take intoaccount the EAD Integration Recommendations. This is critical to ensure the efficient flow of informationthrough the EAD interface.
5.1 Validate Input XML Files during Development
It is important for client applications to validate input and output XML files during development. EAD s bestpractice is to build the customer application so that validation is an optional behavior, turned off by default,which can be turned on by editing a configuration file.
5.2 Record the Business Service Request GUID
This is critical for troubleshooting in case of a business service error. The customer application should always
log service request GUIDs, along with enough information to correlate them with specific customer requests.
5.3 Use a Conversation ID
Conversation IDs are another useful aid to troubleshooting. Since they are set by the customer system, theyprovide proof of end-to-end service completion from the customer perspective.
5.4 Monitoring and Health Checks
Customers desiring to perform automated, scheduled checks of EAD system health may do so by sending aMONITOR request not more often than once every five minutes.
Customers must not perform SubmitAppraisal or other business service requests to test system health.
5.5 DNS Best Practices
The EAD URL Names are resolvable across the Internet. We strongly recommend following the DNS Practicesto ensure reliability of your connections to EAD:
Customers should use one DNS server to resolve all queries to EAD. This server should be able to do
recursive DNS queries and another DNS server should be used only if the first one fails to respond.
It is strongly suggested that customers not round robin their DNS queries.
Customers should allow DNS to perform queries for address resolution from the authoritative source,
and honor the default Time To Live (TTL).
Caching of the DNS resolution beyond 60 seconds can cause application problems. Note: Unexpected
sources of DNS caching include the Unix Name Service Caching Daemon (NSCD) as well as the JavaJVM. NSCD should not be allowed to cache host resolution beyond 60 seconds. For Java,
the problematic setting is networkaddress.cache.ttl.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
47/56
EAD Technical Integration Guide Version 1.4 Page 47 of 55Confidential and Proprietary
5.6 Set Appropriate Network Socket Timeout Intervals
The network driver on the customers computer is designed to gracefully timeout and return control to the callingapplication if normal operations exceed a predetermined interval. The default value of the network timeout canbe as long as five minutes. If the customer system does not set network timeout intervals, the user may be forcedto wait longer than necessary in the event of a network problem.
EAD strongly recommends that customer systems set the timeout intervals for network events as follows, andthat the timeout intervals are configurable within the application, using these:
Connection Timeout: 30 seconds.
Send Timeout: 10 minutes.
Receive Timeout: 120 seconds.
We also recommend that these timeout intervals be configurable in the application, with the default values asshown above.
5.7 MIME Best Practices
Common pitfalls can occur when creating a MIME request or when processing the MIME response. Thefollowing is a list of recommendations:
Creating MIME
Use a Third Party MIME solution
Follow RFC 2046 guidelines regarding boundaries.
Processing MIME
If you decided to use a string comparison method:
Consider issues with case comparison.
Trim spaces to avoid leading blanks, etc.
Use classes like HTTPClient.Util to get the Boundary by parsing the contentType
string and take care of spaces and delimiters. See example below:HTTPClient.Util.getParameter("boundary", contentType);
Avoid hard coding expected order.
Need to have ability to handle changes to header sections.
Do not merge header lines into a single line, i.e. merge of Content-Type and Content-
Disposition declarations.
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
48/56
EAD Technical Integration Guide Version 1.4 Page 48 of 55Confidential and Proprietary
Appendix A: Hard Stop, Override, and Error Codes
Hard Stop Codes
In addition to supporting the current Hard Stop codes below, your implementation must not fail when
encountering a code that is not recognized, as new codes may be added in the future.
Code Hard Stop Description Override Allowed(Manual Request)
100 Appraised value is missing or provided in an invalid format N101 Appraised value is less than $5,000 Y102 Appraised value is less than or equal to $0 N200 Missing appraiser certification information NFHA201 Appraiser must be on the FHA Appraiser Roster YFHA202 Appraiser must have a valid certification in the state where the property resides NFHA203 Appraiser certification was not active as of the appraisal effective date NFHA204 Appraiser certification was terminated as of the appraisal effective date NFHA205 Appraiser was ineligible as of the appraisal effective date NFHA210 Appraisal contains supervisory appraiser information N
300 Missing subject address N302 Unknown subject address Y303 Invalid address: unit number required or not validated Auto 401 UAD compliance check failure (one or more fatal) N402 UAD compliance check failure (warnings only) Auto FHA500 FHA Case Number is missing or provided in an invalid format NFHA501 FHA Case Number on appraisal does not match Document File NFHA502 FHA Case Number on appraisal is cancelled or not found NFHA503 FHA Case Number assigned to property does not match subject address Auto1FHA504 FHA Case Number on appraisal is not assigned to lender NFHA600 Appraiser digital signature is missing Auto1FHA601 Appraiser digital signature is in an invalid format Auto1FHA602 Appraiser digital signature name or license information does not match appraisal Auto FHA603 Appraisal could not be validated against appraisal digital signature Auto1
9000 Invalid submission: File too large N9001 Appraisal data in invalid format: Appraisal file deleted or renamed prior to
submissionN
9001 Appraisal data in invalid format: XML is not well formed N9001 Appraisal data in invalid format: XML contains non-UTF8 characters N9001 Appraisal data in invalid format: XML file type cannot be auto-detected N9001 Appraisal data in invalid format: XML file does not match the specified format
and formN
9001 Appraisal data in invalid format: XSD check failure N
9003 PDF not included in XML submission N
9005 Invalid form type for Appraisal 1: 1004D/442 N
FHA3100 For purchase transaction, Date of Contract must be provided NFHA3105 For purchase transaction, Contract Price must be provided N
FHA3200 Location must be provided NFHA3205 Sum of all land uses must be at least 1% but not greater than 100% N
FHA3210 Neighborhood Predominant Price must be provided N
FHA3300 Site Area must be greater than "0" unless under condominium ownership N
FHA4000 2 Subject property market value decline indicator must be provided N
FHA4001 Appraisal Update indicates that the market value of the subject property hasdeclined in value
Y
FHA4100 Form purpose must be provided N
FHA4200 Effective Date of Appraisal must be provided N
7/25/2019 EAD Direct Integration - Technical Integration Guide v1_4
49/56
EAD Technical Integration Guide Version 1.4 Page 49 of 55Confidential and Proprietary
Code Hard Stop Description Override Allowed
(Manual Request)FHA4205 Effective Date of Appraisal Update must be provided N
FHA5000 Building Status must be provided N
FHA5005 Year Built must be provided N
FHA5010 Effective Age must be provided N
FHA5015 Improvement Type must be provided N
FHA5016 Project Description must be provided N
FHA5100 Foundation Type must be provided NFHA5200 Car Storage Type must be provided N
FHA5400 Number of rooms must be provided N
FHA5401 Number of rooms must be greater than or equal to the number of bedrooms N
FHA5405 Number of bedrooms must be provided N
FHA5410 Number of bathrooms must be provided N
FHA6000 Price of Prior Sale/Transfer must be provided N
FHA6005 Gross Living Area must be provided N
1The following data characteristics result in an automatic system override:
a. appraisal with unknown subject address if year built is equal to 2 years old or lessb. appraisal with unknown subject address that is in Puerto Rico, U.S. Virgin Islands, or Guam
c. appraisal with subject address that cannot be validated against the property associated with the FHACase Numberd. appraisal with XML digital signature that is missing or could not be validatede. UAD Compliance check failure (warnings only)
2Hard Stop that applies to form 442/1004D only.
The Hard Stop will be recorded, automatically overridden and included in the response. These automaticoverrides may be changed to manual overrides or hard stops with a fatal severity in future releases.
Hard Stop Override Request Codes
101: Appraised value is less than $5,000Code Override Request Code Description Comment Required
RQ10101 Value is correct and validated by lender NRQ10199 Other (see comments) Y
302: Unknown subject address
Code Override Request Code Description Comment RequiredRQ30201 Recent/new construction NRQ30202 Subject address located in rural area NRQ30203 Address has recently changed and therefore may not be in your database NRQ30204 Address is correct and verified via local professional NRQ30205 Address is correct and verified by lende