Abstract
This document contains the basic information needed in order to interact with the First American Flood Data Services (FAFDS) implementation of the MISMO 2.1 Flood xml specification. Its main purpose is to describe how to build a valid flood request and interpret the different possible responses.
Last Modified $Date: 2007/06/25 20:43:45 $
A Document Type Definition is a set of rules used to define the valid structure of an xml document. All of the files that are sent and received through the First American Flood xml interface should be well-formed and should validate against the appropriate DTDs listed below.
The 2.1 DTDs are broken up by request and response. Each has an "enveloping" part and a "data" part. The data part contains the flood request or response data, while the enveloping part provides information about the parties involved and how they interface (login info, preferred response types, etc.) The enveloping DTDs include the respective data DTDs in their definitions, so for validation purposes, it is only necessary to refer to the enveloping DTDs.
The available request action types are listed below, with a brief example of the xml for each type. For further information, see the following sections.
Required Request Fields for more information on the various fields.
Faxes, Emails, and Embedded Files of Completed Certificates for an overview of how to request a PDF flood determination certificate for completed orders.
Request a new flood determination.
Example 2.1. Original request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1" _ActionType="Original">
<_PRODUCT _CategoryDescription="Flood">
<_NAME _Identifier="FL"/>
</_PRODUCT>
<BORROWER _FirstName="Joe" _LastName="Tester">
<_RESIDENCE/>
</BORROWER>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY _StreetAddress="7600 Hunters Mill Rd"
_StreetAddress2=""
_City="Blacksburg"
_State="VA"
_PostalCode="24060">
</PROPERTY>
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Upgrade an existing basic determination to a life-of-loan determination.
Example 2.2. Upgrade request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="Upgrade"
FloodCertificationIdentifier="0987654321"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Edit an existing determination in order to to provide additional information or correct existing information. This example changes the loan number to 'MyUpdatedLoanNum12345'.
Example 2.3. Change request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1" _ActionType="Change"
FloodCertificationIdentifier="0987654321">
<MORTGAGE_TERMS LenderCaseIdentifier="MyUpdatedLoanNum12345"/>
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Cancel an existing determination.
Example 2.4. Cancellation request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="Cancellation"
FloodCertificationIdentifier="0987654321"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Reactivate an existing cancelled determination.
Example 2.5. Reissue request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="Reissue"
FloodCertificationIdentifier="0987654321"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Look up an existing determination, usually to check if an in-research item has been completed.
Example 2.6. StatusQuery request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="StatusQuery"
FloodCertificationIdentifier="0987654321"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Get a listing of researched items that require additional information or have been completed but not yet retrieved.
The request is identical to a normal StatusQuery, except there is no FloodCertificationIdentifier specified.
Clients who order for multiple accounts using the same login can retrieve pending results for all accounts by omitting the InternalAccountIdentifier. If an InternalAccountIdentifier is specified, then the results will be for that account only. In general, clients should omit the InternalAccountIdentifier unless there is a specific system requirement for retrieving results on a per-account basis.
Example 2.7. StatusQuery (Pending) request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST MISMOVersionID="2.1" _ActionType="StatusQuery"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Dispute the results of an existing flood determination.
Example 2.8. Dispute request
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<KEY _Name="FAFDS.Dispute.DisputedItems" _Value="ZONE"/>
<KEY _Name="FAFDS.Dispute.SupportingDocuments" _Value="ELEVATION_CERTIFICATE, SURVEY"/>
<KEY _Name="FAFDS.Dispute.Description" _Value="Even though the property is
technically located in a flood zone, it is actually on top of a hill ...."/>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="Dispute"
_RushIndicator="N"
FloodCertificationIdentifier="0987654321"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
The STATUS element is where the response type information is returned, along with any comments or error messages. The STATUS element has 4 attributes:
_Condition: Success or Error
_Code: code representing a given status
_Name: more user-friendly representation of the status than the code
_Description: comments or error messages regarding the status
There are 6 response types.
The flood determination is complete.
Example 3.1. Complete response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:40:41-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<LENDER_extension _City="Austin" _PostalCode="78758" _State="TX" _StreetAddress="123 Lender Blvd" _UnparsedName="First Lender, Inc"/>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY _City="BLACKSBURG" _County="MONTGOMERY" _PostalCode="24060" _State="VA" _StreetAddress="7600 HUNTERS MILL RD"/>
<FLOOD_DETERMINATION FloodCertificationIdentifier="0302000299" FloodPartialIndicator="N" FloodProductCertifyDate="2003-02-24T10:40:41-0500" SpecialFloodHazardAreaIndicator="N" _LifeOfLoanIndicator="N">
<_LOAN_INFORMATION RegulatoryAgencyLenderIdentifier="myLenderId"/>
<_COMMUNITY_INFORMATION NFIPCommunityIdentifier="510100" NFIPCommunityName="BLACKSBURG, TOWN OF" NFIPCommunityParticipationStartDate="1980-05-15" NFIPCounty="MONTGOMERY" NFIPStateCode="VA"/>
<_BUILDING_INFORMATION NFIPFloodZoneIdentifier="C" NFIPMapIdentifier="510100" NFIPMapIndicator="Y" NFIPMapPanelDate="1980-05-15" NFIPMapPanelIdentifier="0006" NFIPMapPanelSuffixIdentifier="B"/>
<_INSURANCE_INFORMATION NFIPCommunityParticipationStatusType="Regular" ProtectedAreaIndicator="N"/>
</FLOOD_DETERMINATION>
</FLOOD_RESPONSE>
<STATUS _Condition="Success" _Code="S0010" _Name="Complete" _Description="1. *** THIS CERTIFICATION FOR DEMONSTRATION PURPOSES ONLY ***"/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
The determination could not be completed automatically, so it has been sent to research.
Example 3.2. In Research response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:47:01-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY AssessorsParcelIdentifier="APN123" _City="BLACKSBURG" _County="MONTGOMERY" _PostalCode="24060" _State="VA" _StreetAddress="112 MAIN DR"/>
<FLOOD_DETERMINATION FloodCertificationIdentifier="0302000300" _LifeOfLoanIndicator="N"/>
</FLOOD_RESPONSE>
<STATUS _Condition="Success" _Code="S0011" _Name="In Research" _Description="Order 0302000300 submitted for research at 10:47 AM CST on 02/24/2003. You can expect a response no later than 10:47 AM CST on 02/25/2003. "/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
The research staff needs additional information, such as a legal description, in order to complete the determination.
Example 3.3. Additional Info response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:47:01-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY AssessorsParcelIdentifier="APN123" _City="BLACKSBURG" _County="MONTGOMERY" _PostalCode="24060" _State="VA" _StreetAddress="112 MAIN DR"/>
<FLOOD_DETERMINATION FloodCertificationIdentifier="0302000300" _LifeOfLoanIndicator="N"/>
</FLOOD_RESPONSE>
<STATUS _Condition="Success" _Code="S0012" _Name="Additional Info Needed" _Description="We need additional information to locate the subject property. Fax to 1-800-447-9664: Property Appraisal; Section, Block & Lot; Legal that matches Address; Metes & Bounds Description; Lot, Block and Subdivision."/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
The duplicate-checking algorithm has determined that the request duplicates an existing determination.
The status of the original order is contained in the _Description attribute of the STATUS element. The _Description is of the form "code:name", where code and name correspond to the entries in the Status Codes appendix. The flood certification number of the original order is contained in the FloodCertificationIdentifier attribute of the FLOOD_DETERMINATION element.
So for example, the response below indicates that the request just processed is a duplicate of order 0302000299, which has a status of S0010, or Complete. The original order can be retrieved with a status query on the provided flood certification number.
Example 3.4. Duplicate response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:40:41-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY _City="BLACKSBURG" _County="MONTGOMERY" _PostalCode="24060" _State="VA" _StreetAddress="7600 HUNTERS MILL RD"/>
<FLOOD_DETERMINATION FloodCertificationIdentifier="0302000299" _LifeOfLoanIndicator="N"/>
</FLOOD_RESPONSE>
<STATUS _Condition="Success" _Code="S0013" _Name="Duplicate" _Description="S0010:Complete"/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
The determination has been cancelled.
Example 3.5. Cancelled response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:47:01-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY AssessorsParcelIdentifier="APN123" _City="BLACKSBURG" _County="MONTGOMERY" _PostalCode="24060" _State="VA" _StreetAddress="7600 HUNTERS MILL RD"/>
<FLOOD_DETERMINATION FloodCertificationIdentifier="0302000300" _LifeOfLoanIndicator="N"/>
</FLOOD_RESPONSE>
<STATUS _Condition="Success" _Code="S0014" _Name="Cancelled" _Description="You requested credit for this FloodCert on 02/24/2003.The flood zone determination is no longer available."/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
List of all researched items that require additional information or have been completed but not yet retrieved.
Example 3.6. Pending List response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T10:47:01-0500">
<RESPONSE_DATA>
<EXTENSION>
<EXTENSION_SECTION>
<EXTENSION_SECTION_DATA>
<PENDING_LIST>
<PendingItem FloodCertificationIdentifier="0000000000" LenderCaseIdentifier="1234567" StatusCode="S0012"/>
<PendingItem FloodCertificationIdentifier="1111111111" LenderCaseIdentifier="1234567" StatusCode="S0012"/>
<PendingItem FloodCertificationIdentifier="2222222222" LenderCaseIdentifier="2342341" StatusCode="S0010"/>
<PendingItem FloodCertificationIdentifier="3333333333" LenderCaseIdentifier="9876543" StatusCode="S0010"/>
</PENDING_LIST>
</EXTENSION_SECTION_DATA>
</EXTENSION_SECTION>
</EXTENSION>
<STATUS _Code="S0015" _Condition="Success" _Description="Pending list request processed" _Name="Processed"/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
There are a number of different error responses. The error information is represented by the STATUS element.
Example 3.7. Login Error response
Since the request failed before any flood requests were actually processed, the STATUS is at the level of the envelope (RESPONSE) because there are no individual flood responses (RESPONSE_DATA).
<RESPONSE_GROUP> <RESPONSE ResponseDateTime="2003-02-24T12:51:29-0500"> <STATUS _Condition="Error" _Code="E0010" _Name="Error" _Description="Invalid User ID/Password."/> </RESPONSE> </RESPONSE_GROUP>
The remaining examples show errors at the RESPONSE_DATA level.
Example 3.8. Invalid Request Type Error response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T13:06:05-0500">
<RESPONSE_DATA>
<STATUS _Condition="Error" _Code="E0030" _Name="Error" _Description="Invalid action type: Transfer" />
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
Example 3.9. Business Logic Error response
<RESPONSE_GROUP>
<RESPONSE ResponseDateTime="2003-02-24T13:08:33-0500">
<RESPONSE_DATA>
<STATUS _Condition="Error" _Code="E0040" _Name="Error" _Description="Post office box is not a valid property address"/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
The remaining errors just differ in code and description.
These are the status codes for the various Success and Error responses. The codes are the official indicators of the status state. They are unique and constant. The names associated with each code are human-friendly representations of the codes and are not guaranteed to remain unchanged.
Table A.1. Success Status Codes
| Code | Name | Meaning |
|---|---|---|
| S0010 | Complete | The flood determination is complete. |
| S0011 | In Research | The flood determination is currently in research. |
| S0012 | Additional Info Needed | The flood determination has been researched, but needs more information. |
| S0013 | Duplicate | The request is a duplicate of an existing determination. |
| S0014 | Cancelled | The determination has been cancelled. |
| S0015 | Processed | A generic code to indicate that an action succeeded, for which none of the above codes is applicable. |
Table A.2. Error Status Codes
| Code | Name | Meaning |
|---|---|---|
| E0000 | Server Unavailable | Server is not able to accept and process requests. |
| E0002 | Internal Server Error | An unexpected error has occurred. |
| E0010 | Missing Authentication | The login id and/or password are not present. |
| E0011 | Invalid Authentication | The login id and/or password are not valid. |
| E0020 | Missing Value | A required data item is missing. |
| E0030 | Invalid Value | An invalid data item has been submitted. |
| E0040 | Business Logic | An attempt to cancel a cancelled determination, provide a PO box as the property address, etc. |
This appendix provides examples of what information is required by each type of flood request and how to specify that information in the request.
Many of the following examples are not complete requests in themselves. Portions are removed for clarity (indicated by '...').
The basic information required by all requests is login/password and the type of action being requested.
Every client using the FAFDS xml interface is given a login id and password when the account is set up. The login id and password go in the corresponding LoginAccountIdentifier and LoginAccountPassword attributes of the REQUEST element. If the login account is ordering on behalf of another account (called an "internal account"), then that internal account is specified in the InternalAccountIdentifier attribute.
The type of action being requested is specified in the _ActionType attribute of the FLOOD_REQUEST element. The _ActionType attribute can be Original, StatusQuery, Cancellation, Reissue, or Upgrade. (The Transfer action is not currently supported.) See Request Types for more information on these types.
Example B.1. All Requests
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST _ActionType="Original">
...
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
In addition, every request can provide optional KEY elements that will be echoed back in the response. These are useful as a means for clients to place tracking IDs in the request. The keys are not stored with the order, but they are echoed back in the response.
KEYs can be inserted as the first child elements of the REQUEST element and also as the first child elements of the REQUEST_DATA element. This allows keys to be associated at the envelope level and at the data level. The names of the keys in the example below are totally arbitrary. They can be named something else. There can be multiple keys as long as the names are different.
Example B.2. KEY Elements in Request
<REQUEST_GROUP>
<REQUEST ... >
<KEY _Name="EnvTrackingNo" _Value="T1234567890"/>
<REQUEST_DATA>
<KEY _Name="ReqTrackingNo" _Value="R1234567890"/>
<KEY _Name="ReqTrackingNo2" _Value="R0987654321"/>
<FLOOD_REQUEST ... />
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Here is the response with the KEY elements echoed back.
Example B.3. KEY Elements in Response
<RESPONSE_GROUP>
<RESPONSE ... >
<KEY _Name="EnvTrackingNo" _Value="T1234567890"/>
<RESPONSE_DATA>
<KEY _Name="ReqTrackingNo" _Value="R1234567890"/>
<KEY _Name="ReqTrackingNo2" _Value="R0987654321"/>
<FLOOD_RESPONSE ... />
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
Apart from the login information, all that is needed is the flood certification number of the previous order that is to be queried, upgraded, cancelled, or reissued. This is contained in the FloodCertificationIdentifier attribute of the FLOOD_REQUEST element.
Example B.4. StatusQuery, Upgrade, Cancel, Reissue Requests
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<FLOOD_REQUEST _ActionType="StatusQuery"
FloodCertificationIdentifier="0123456789"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
The basic information contained in an Original (new order) request is the flood product being requested, the loan information, and the property information.
A flood product is optional in the request. If there is no product specified then the default product on the FAFDS account is used.
The product is indicated in the _PRODUCT element by specifying the FAFDS product code in the _Identifier attribute of the _NAME child element. The most common product codes are listed in the table below. For a complete list of products geared to your business, please contact the Account Management department at 800-447-1772.
Table B.1. Common Product Codes
| Description | Code |
|---|---|
| Basic Flood Determination | F |
| Life-of-Loan Flood Determination | FL |
| Life-of-Loan with Census | FLC |
| Life-of-Loan Related Loan | FLR |
Example B.5. Flood Product Information
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST ... >
<_PRODUCT _CategoryDescription="Flood">
<_NAME _Identifier="FL"/>
</_PRODUCT>
<BORROWER ... />
<MORTGAGE_TERMS ... />
<PROPERTY ... />
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Borrower name and loan number are not strictly required, but it is recommended that they are submitted. The borrower's name goes in the _FirstName and _LastName attributes of the BORROWER element. The loan number goes in the LenderCaseIdentifier attribute of the MORTGAGE_TERMS element.
Example B.6. Loan Information
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST ... >
<_PRODUCT ... />
<BORROWER _FirstName="Joe" _LastName="Tester">
<_RESIDENCE/>
</BORROWER>
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY ... />
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
The lender ID is a data field that prints in box 3 on the FEMA form. According to FEMA, "The lender funding the loan should identify itself as follows: FDIC - insured lenders should indicate their FDIC Insurance certificate number; Federally-insured credit unions should indicate their charter/insurance number; Farm Credit institutions should indicate their UNINUM number. Other lenders who fund loans sold to or securitized by FNMA or FHLMC should enter the FNMA or FHLMC seller/servicer number."
In summary, the lender ID is how you identify yourself to your regulatory agency. The (optional) RegulatoryAgencyLenderIdentifier attribute of the FLOOD_REQUEST element allows clients to send a lender ID with each flood request, that will print on the FEMA form.
Example B.7. Lender Identifier
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST RegulatoryAgencyLenderIdentifier="mylenderid" ... >
<_PRODUCT ... />
<BORROWER ... />
<MORTGAGE_TERMS ... />
<PROPERTY ... />
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
Basic property information is required. The address of the property for which the flood determination is being requested maps to the attributes of the PROPERTY element.
Example B.8. Property
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST ... >
<_PRODUCT ... />
<BORROWER ... />
<MORTGAGE_TERMS ... />
<PROPERTY _StreetAddress="7600 Hunters Mill Rd"
_StreetAddress2=""
_City="Blacksburg"
_State="VA"
_PostalCode="24060"/>
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
In addition, an optional assessors parcel number or legal description may be specified to help identify the property if the order needs to be researched.
The assessors parcel number goes in the AssessorsParcelIdentifier attribute of PROPERTY, while the legal description goes in the _LEGAL_DESCRIPTION child element of PROPERTY. The _Type attribute of _LEGAL_DESCRIPTION is always "Other" and the _TextDescription attribute contains the actual text of the description.
Example B.9. Property
...
<PROPERTY _StreetAddress="7600 Hunters Mill Rd"
_StreetAddress2=""
_City="Blacksburg"
_State="VA"
_PostalCode="24060"
AssessorsParcelIdentifier="myApn123">
<_LEGAL_DESCRIPTION _Type="Other"
_TextDescription="A legal description"/>
</PROPERTY>
...
There are some data items used by First American Flood that are not specifically provided for in the DTDs. In order to submit these items, they must be passed in as KEY elements. To distinguish these special keys, the key name is prefixed by the letters "FAFDS" followed by a period.
The currently defined FAFDS keys are listed below. They are all optional.
The additional reference identifier is a single piece of information that will be stored in our system along with the flood determination. By default, it will print on the FEMA form in Section I, Box 1. If you do not want it displayed on the form, a FAFDS account representative can change that preference.
Example B.10. FAFDS.AdditionalReferenceIdentifier
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<KEY _Name="FAFDS.AdditionalReferenceIdentifier" _Value="MyRefNum"/>
<FLOOD_REQUEST ... >
...
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
The branch identifies the cost center to which the request will be billed. It will print on the FEMA form in Section I, Box 1.
Example B.11. FAFDS.Branch
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<KEY _Name="FAFDS.Branch" _Value="MyCostCenterId"/>
<FLOOD_REQUEST ... >
...
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
If an item of data needs to be stored with the order, but it is not a normal field on the FEMA form, then that data can be submitted using the FAFDS.TrackingIdentifier KEY. The data will be returned in responses, but will not print on the FEMA form. This field can be used to store numbers that clients can use to update their systems for that flood order.
Example B.12. FAFDS.TrackingIdentifier
<REQUEST_GROUP>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
<KEY _Name="FAFDS.TrackingIdentifier" _Value="MyTrackingId"/>
<FLOOD_REQUEST ... >
...
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
For a refinance or related loan order, either the flood certification number or the loan number of the original order must be used to tie the new order to the original. (Only one or the other is required.)
Example B.13. Original Requests (Refinance or Related)
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST _ActionType="Original"
FloodCertificationIdentifier="0123456789"
OriginalFloodDeterminationLoanIdentifier="origLoanNum123">
<_PRODUCT ... />
<BORROWER ... />
<MORTGAGE_TERMS ... />
<PROPERTY ... />
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
For a life-of-loan conversion order, there are 5 additional pieces of information that must be submitted as KEY elements of the form
<KEY _Name="FAFDS.LOLConversion.fieldName" _Value="fieldValue"/>
Table B.2. Life-of-Loan Conversion Keys
| Key Name | Key Value |
|---|---|
| FAFDS.LOLConversion.NFIPCommunityIdentifier | NFIP community number for jurisdictional community |
| FAFDS.LOLConversion.NFIPMapPanelIdentifier | Map panel number (panel only - no suffix) |
| FAFDS.LOLConversion.NFIPMapPanelSuffixIdentifier | Map panel suffix (suffix only - no panel) |
| FAFDS.LOLConversion.NFIPFloodZoneIdentifier | Flood zone pertaining to property |
| FAFDS.LOLConversion.Vendor | Vendor code of vendor providing determination |
The FAFDS.LOLConversion.NFIPMapPanelIdentifier key should not contain the suffix. It should only contain the 2,3, or 4 character map panel number. The single character suffix, if needed, should be submitted in the FAFDS.LOLConversion.NFIPMapPanelSuffixIdentifier key, as demonstrated in the example below. If you only have access to a combined panel/suffix, then you can split them up according to the following logic:
If combinedPanelSuffix length is less than or equal to 4, then there is no suffix. If it is greater than 4, then the panel is the first 4 characters and the suffix is the remainder (should just be a single character.)
Example B.14. Original Requests (Life-of-Loan Conversion)
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<!-- Life-of-Loan Conversion Information -->
<KEY _Name="FAFDS.LOLConversion.NFIPCommunityIdentifier" _Value="510100"/>
<KEY _Name="FAFDS.LOLConversion.NFIPMapPanelIdentifier" _Value="0006"/>
<KEY _Name="FAFDS.LOLConversion.NFIPMapPanelSuffixIdentifier" _Value="B"/>
<KEY _Name="FAFDS.LOLConversion.NFIPFloodZoneIdentifier" _Value="C"/>
<KEY _Name="FAFDS.LOLConversion.Vendor" _Value="FDSI"/>
<FLOOD_REQUEST _ActionType="Original"
FloodCertificationIdentifier="0123456789"
OriginalFloodDeterminationLoanIdentifier="origLoanNum123">
<_PRODUCT ... />
<BORROWER ... />
<MORTGAGE_TERMS ... />
<PROPERTY ... />
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
When an order completes, the flood determination information is contained within the FLOOD_DETERMINATION element of the response. The KEYs with the names described above will also be echoed back in the response, but these are just copies of the KEYs that were passed in and are not part of the flood determination.
The FloodCertificationIdentifier of the order to edit must be specified. Apart from that, only the fields to be changed must be specified, according to the following rules:
If a value is specified in an element or attribute, that will become the new value.
If an element or attribute is empty or missing completely, the original value will not change.
In the following example, the LenderCaseIdentifier will be updated to LoanNum123, the existing value of _StreetAddress2 will be removed, and all other values on the original order will remain unchanged.
Example B.15. Change Requests
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<FLOOD_REQUEST _ActionType="Change"
FloodCertificationIdentifier="0123456789">
<MORTGAGE_TERMS LenderCaseIdentifier="LoanNum123"/>
<PROPERTY _StreetAddress2=""/>
</FLOOD_REQUEST>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
The information needed for a Dispute request is as follows.
This indicates the existing flood determination that is being disputed. The value goes in the FloodCertificationIdentifier attribute of the FLOOD_REQUEST element.
This indicates if the dispute request is to be expedited. The "Y" or "N" value goes in the _RushIndicator attribute of the FLOOD_REQUEST element.
This is a comma-separated list of one or more items that are being disputed. The valid values are shown in the following table. If the item that is being disputed is not one of the following, just include it in the list anyway and it will be marked as "OTHER".
Table B.3. Disputed Items
| Value | Description |
|---|---|
| ZONE | flood zone |
| COMMUNITY | community number |
| PANEL | map panel |
| MAP_DATE | map date |
| CBRA_STATUS | Coastal Barrier Resource Area status |
The comma-separated list of items to dispute goes in a KEY element with the name "FAFDS.Dispute.DisputedItems". For example, the following KEY indicates that the flood zone and map panel are being disputed.
<KEY _Name="FAFDS.Dispute.DisputedItems" _Value="ZONE, PANEL"/>
This is another comma-separated list. It contains a list of one or more documents that support the reasons for the dispute. The valid values are shown in the following table. Again, if the item to be submitted is not one of the following, include it in the list anyway and it will be marked as "OTHER".
Table B.4. Supporting documentation
| Value | Description |
|---|---|
| LOCATOR_MAP | |
| SURVEY | |
| APPRAISAL | |
| COMMUNITY_LETTER | |
| FEMA_LETTER | |
| ELEVATION_CERTIFICATE |
The comma-separated list of supporting documents goes in a KEY element with the name "FAFDS.Dispute.SupportingDocuments". For example, the following KEY indicates that an elevation certificate will be used to support the dispute.
<KEY _Name="FAFDS.Dispute.SupportingDocuments" _Value="ELEVATION_CERTIFICATE"/>
Once the dispute request has been submitted, the supporting documents specified in the request must be faxed to FAFDS.
This is a brief text description explaining the situation and the reason for the dispute. It goes in a KEY element with the name "FAFDS.Dispute.Description".
<KEY _Name="FAFDS.Dispute.Description" _Value="Even though the property is
technically located in a flood zone, it is actually on top of a hill ...."/>
Example B.16. Dispute Requests
<REQUEST_GROUP>
<REQUEST ... >
<REQUEST_DATA>
<KEY _Name="FAFDS.Dispute.DisputedItems" _Value="ZONE"/>
<KEY _Name="FAFDS.Dispute.SupportingDocuments" _Value="ELEVATION_CERTIFICATE"/>
<KEY _Name="FAFDS.Dispute.Description" _Value="Even though the property is
technically located in a flood zone, it is actually on top of a hill ...."/>
<FLOOD_REQUEST MISMOVersionID="2.1"
_ActionType="Dispute"
_RushIndicator="N"
FloodCertificationIdentifier="0123456789"/>
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
If the account is set up to allow it, a completed flood determination certificate can be faxed or emailed, or embedded in the xml response as a Base64-encoded pdf file.
To fax and/or email the certificate, specify a PREFERRED_RESPONSE entry for each method in the REQUESTING_PARTY element.
The _Format attribute should be 'PDF' (only format currently supported), the _Method attribute should be 'Fax' for fax and 'SMTP' for email, and the _Destination should contain the fax number or email address to which the completed certificate should be sent.
<REQUEST_GROUP>
<REQUESTING_PARTY>
...
<PREFERRED_RESPONSE _Format="PDF" _Method="Fax" _Destination="512-555-1234"/>
<PREFERRED_RESPONSE _Format="PDF" _Method="SMTP" _Destination="my.email@mydomain.com"/>
</REQUESTING_PARTY>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
...
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
To embed the certificate in the xml response, specify a PREFERRED_RESPONSE entry in the REQUESTING_PARTY element.
The _Format attribute should be 'PDF' (only format currently supported), the _Method attribute should be 'File', and the _UseEmbeddedFileIndicator should be 'Y'.
If there is no such PREFERRED_RESPONSE entry, or if the _UseEmbeddedFileIndicator is 'N' or not present, then the embedded file will not be returned in the response.
<REQUEST_GROUP>
<REQUESTING_PARTY>
...
<PREFERRED_RESPONSE _Format="PDF" _Method="File" _UseEmbeddedFileIndicator="Y"/>
</REQUESTING_PARTY>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
...
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
An embedded pdf will only be returned if a PREFERRED_RESPONSE indicates it in the request, regardless of the type of request (Original, StatusQuery, Change, etc.) The example above is exactly the same for any request type where a PDF should be returned in the response.
In particular, this means that StatusQuery requests must include a PREFERRED_RESPONSE in order to receive a pdf embedded in the response.
The embedded certificate is returned in the response as a Base64-encoded pdf file. The Base64 data is contained in the DOCUMENT child element of the EMBEDDED_FILE element. The attributes of the EMBEDDED_FILE element provide information such as the MIME type of the file, the encoding type, and the version of the format that the file is created as. For example, the response below contains a file that is in the Adobe Pdf v1.2 format, with MIME type "application/pdf", that is encoded using Base64. Using this information, the client should be able to process the embedded data to regenerate the pdf file.
<RESPONSE_GROUP>
<RESPONDING_PARTY/>
<RESPOND_TO_PARTY/>
<RESPONSE ResponseDateTime="2003-04-29T15:29:49-0500">
<RESPONSE_DATA>
<FLOOD_RESPONSE>
<BORROWER _FirstName="Joe" _LastName="Tester"/>
<MORTGAGE_TERMS LenderCaseIdentifier="loannum123"/>
<PROPERTY _City="BLACKSBURG"
_County="MONTGOMERY"
_PostalCode="24060"
_State="VA"
_StreetAddress="7600 HUNTERS MILL RD"/>
<EMBEDDED_FILE MIMEType="application/pdf"
_Description="Adobe Pdf"
_EncodingType="Base64"
_Extension="pdf"
_Name="Certificate_0304001144"
_Version="1.2">
<DOCUMENT>JVBERi0xLjM ... more Base64 data would go here ...</DOCUMENT>
</EMBEDDED_FILE>
<FLOOD_DETERMINATION
...
</FLOOD_DETERMINATION>
</FLOOD_RESPONSE>
<STATUS _Code="S0010"
_Condition="Success"
_Description="1. *** THIS CERTIFICATION FOR DEMONSTRATION PURPOSES ONLY *** "
_Name="Complete"/>
</RESPONSE_DATA>
</RESPONSE>
</RESPONSE_GROUP>
If the account is set up to allow it, a fax and/or email request for additional information can be sent to the processor when an order that is being researched requires more data to complete the determination. The relevant fax/email information that is on the account can be overridden by specifying a CONTACT_DETAIL in the REQUESTING_PARTY element.
Within that CONTACT_DETAIL, the CONTACT_POINT with _RoleType "Work" and _Type "Email" is the email address to which requests for additional information will be emailed. The CONTACT_POINT with _RoleType 'Work" and _Type "Fax" is the fax number to which requests for additional information will be faxed.
<REQUEST_GROUP>
<REQUESTING_PARTY _Name="Joe's Mortgage Co.">
<CONTACT_DETAIL _Name="Maria Lee">
<CONTACT_POINT _RoleType="Work" _Type="Email" _Value="myemail@somemail.com"/>
<CONTACT_POINT _RoleType="Work" _Type="Fax" _Value="512-555-3456"/>
<CONTACT_POINT _RoleType="Work" _Type="Phone" _Value="512-555-1234"/>
</CONTACT_DETAIL>
</REQUESTING_PARTY>
<REQUEST LoginAccountIdentifier="AskForFirstAmericanLogin"
LoginAccountPassword="AskForFirstAmericanPassword"
InternalAccountIdentifier="AskForFirstAmericanAccount"
RequestDateTime="2003-01-20T23:10:56">
<REQUEST_DATA>
...
</REQUEST_DATA>
</REQUEST>
</REQUEST_GROUP>
MISMO has adopted the ISO 8601 standard for dates and times. In the context of the FAFDS xml interface, this means the following:
Dates are represented in the form yyyy-mm-dd.
Times are specified as hh:mm:ss, in 24 hr format.
In order to reduce ambiguity regarding time zones and daylight savings time changes, ISO 8601 assumes Coordinated Universal Time (UTC) as standard time. To indicate local time, an offset of the form +hhmm or -hhmm can optionally be appended. This is the local time difference ahead of or behind UTC. An offset of -0500, for example means that the given time is 5 hours behind UTC. An offset of +0230 means that the given time is 2 and a half hours ahead of UTC. If the given time _is_ UTC, then a 'Z' is appended instead of an offset.
First American Flood's time zone is Central Time, so the local time offset will change between -0500 and -0600 depending on whether it's daylight savings time or not.
Dates and times are separated by a 'T', so a full date/time looks like yyyy-mm-ddThh:mm:ss(+-)hhmm. Currently, the only full date/time fields of this form in the response are ResponseDateTime and FloodProductCertifyDate. The others are just date (yyyy-mm-dd).
Example E.1. Date/Time Formats
<RESPONSE_GROUP> <RESPONSE ResponseDateTime="2003-02-24T10:40:41-0500"> <RESPONSE_DATA> <FLOOD_RESPONSE> <BORROWER .../> <MORTGAGE_TERMS .../> <PROPERTY _.../> <FLOOD_DETERMINATION ... FloodProductCertifyDate="2003-02-24T10:40:41-0500"> <_COMMUNITY_INFORMATION .../> <_BUILDING_INFORMATION ... NFIPMapPanelDate="1980-05-15">/> <_INSURANCE_INFORMATION .../> </FLOOD_DETERMINATION> </FLOOD_RESPONSE> <STATUS _Condition="Success" _Code="S0010" _Name="Complete" .../> </RESPONSE_DATA> </RESPONSE> </RESPONSE_GROUP>