FATCA File Preparation Guide

Tags: FATCA, Prepare File, File Preperation Guide

This section identifies some primary online resources provided by IRS for FATCA file preparation, provides some xml document guidelines and describes the validation done during the file submission process.

IDES Resources

The primary resource for guidance on the preparation of FATCA XML documents is the International Data Exchange Service (IDES) website.

IDES website URLDescription



  • FATCA XML Schema v2.0
  • FATCA XML Notification Schema v2.3
  • Sample Nil Files


FATCA XML Schema Best practices


How to Correct, Void, and Amend Records


Guidelines for creating DocRefId values.



  • Data Format and Structure

FATCA Document Guidelines

When preparing the FATCA XML document, the following should be considered.

  1. Use XML version 1.0 - The current version of the FATCA XML schemas is written using v1.0. Higher versions of XML will fail schema validation.

    <?xml version='1.0' encoding='utf-8'?>
  2. All schema namespaces should be declared at the beginning of the XML document, i.e. within the <FATCA_OECD> root element. This approach is used in the IDES sample files.

    <ftc:FATCA_OECD xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemalocation='urn:oecd:ties:fatca:v2' xmlns:iso='urn:oecd:ties:isofatcatypes:1' xmlns:ftc='urn:oecd:ties:fatca:v2' xmlns:stf='urn

    This enhances the readability of the document and reduces the likelihood of namespace reference errors.

  3. All elements should be prefixed with the namespace alias. This approach is used in the IDES sample files.


    This helps with identifying errors caused by incorrect schema references.

  4. The XML document should be formatted on different lines with indentation. This will assist with easily identifying and resolving any schema validation errors.

  5. The SendingCompanyIN must be 000000.00000.TA.780 this is IRD's Host Country Tax Authority (HCTA) ID.

  6. The ReportingFI TIN must be the Reporting GIIN, i.e. your company's GIIN.

  7. Filer Category is required for 2016 submission onwards.

  8. MessageRefId should begin with the Reporting GIIN followed by some unique FI generated value.

    Example: For GIIN 2IW3WK.00001.ME.780, a possible MessageRefId is

  9. DocRefId should begin with the Reporting GIIN followed by a period.

    Example: 2IW3WK.00000.LE.152.d38z421f-7a8p-4e01-7ju1-3hu165f6fe8a

  10. Files should be named using the following format


    GIIN - Reporting GIIN
    FileType - Either FATCA1, FATCA2, FATCA3 or FATCA4 (or FATCA11, FATCA12, FATCA13, FATCA14 for testing)
    Date - Date Created

    Example: 7L6ZDL00001ME780_FATCA11_20170504.xml

FATCA File Validation

During the file submission process, only files which pass validation will be accepted. Two levels of validation are done

  1. Schema Validation – This ensures that the file conforms to the FATCA XML schemas.
  2. Data Validation – Additional validation done to help minimize the likelihood of file errors and corrections from IRS/IDES.

Data Validation

The following describes the different types of validation done during the Test Validation and File Submission processes.

Validation TypeDescription

Reporting GIIN

  • Ensures that the Reporting GIIN in the file matches the GIIN which was selected (for multiple GIINs registered) or the GIIN registered with IRD (single GIIN).

Reporting Period

  • The Reporting Period in the file must match the one entered.

Submission Type

  • The submission Type must match the one selected.

  • Only Test Submission Types (FATCA11, 12, 13, 14) are allowed in test validation and test submission types are not allowed in real reporting files.

Transmitting Country

  • The transmitting country must be TT

Receiving Country

  • The receiving country must be US

Sending Company

  • The SendingCompanyIN must be 000000.00000.TA.780

Filer Category

  • Filer Category is required for all submissions from 2016 onwards

  • The MessageRefId must begin with the GIIN which was selected (for multiple GIINs registered) or the GIIN registered with IRD (single GIIN).

  • The MessageRefId is unique, i.e. it does not match any previous submission for that GIIN.


  • The DocRefId must begin with the GIIN which was selected (for multiple GIINs registered) or the GIIN registered with IRD (single GIIN) followed by a period (.) See example above.


  • Files must contain at least one record or a nil report element.

The following validation is performed during the file submission process only.

Validation TypeDescription


  • All TIN/SSN numbers must be in the valid format


  • CorrMessageRefId are required for non-new file submissions.

  • CorrMessageRefId should not be used for new file submissions.

  • CorrMessageRefId must match a previous file submission.

Amended Submission Type

  • Only files which have received valid notifications can be amended, i.e. the CorrMessageRefId in an amended file must match a previous file with a valid notification.

Corrected Submission Type

  • Only files which have received corrections request (Record level or field level errors) can be corrected, i.e. the CorrMessageRefId in a corrected file must match a previous file with a correction required.