Scope and historical version
This article follows the IRAS third-edition CRS XML user guide published on 19 August 2020. It describes OECD CRS XML schema version 2.0, required for submissions from 1 February 2021; earlier submissions used version 1.01. The guide adapts OECD instructions to Singapore identifiers, missing-TIN reasons, passive NFE reporting and correction handling. It is a version-specific technical reference to be read with the CRS Regulations and reporting guidance, rather than a substitute for determining whether an account is reportable.
Electronic files and submission sequence
All CRS returns, including nil returns, are electronic. An institution can consolidate accounts for different reportable jurisdictions in one return. The guide permits XML uploads through the secure portal without digital signing, encryption or compression, with a maximum uncompressed size of 5 MB. Split larger returns and submit later files only after IRAS accepts the first. A correction or void file should be submitted no earlier than the day after the erroneous initial submission. A nil return can be filed directly in AEOI e-Services without an XML file; a fillable PDF alternative is also noted. No compulsory filename is specified, but naming the file with its MessageRefID is recommended.
Encoding, special characters and validation status
Begin with an XML declaration, use UTF-8 and omit a byte order mark. Escape ampersands, apostrophes, angle brackets and quotation marks using XML entities. The guide prohibits hash signs, double dashes and slash-asterisk sequences within data, with no acceptable substitute listed. Required validation elements must be present; a validation choice requires the applicable alternative. Some schema-optional elements are substantively mandatory unless information is unavailable under the stated circumstances. Other optional elements are recommended or not relevant to CRS. Version 2.0 requires strings to have at least one character: omit an unavailable optional element rather than sending an empty one. Perform schema validation before submission.
Header identity, countries and message type
SendingCompanyIN identifies the sender, which may be the reporting institution or an appointed provider. Use Entity ID Type, a space, then Entity ID, such as ASGD A1234567D. Listed types are UEN-Business, UEN-Local Co, UEN-Others, ASGD and ITR. TransmittingCountry and ReceivingCountry are both SG for reporting to IRAS, and MessageType is CRS. Leave Warning and Contact blank: processing is automated, and communication uses the registered point of contact or [email protected] with the submission acknowledgement ID. These blank fields should be omitted consistently with the non-empty-string rule.
MessageRefID and reporting dates
IRAS prescribes a unique 25-character MessageRefID: four-digit reporting year, ten-character sender tax reference, eight-digit creation date YYYYMMDD and a three-digit sequence. Pad a tax reference shorter than ten characters with trailing hyphens and do not include its entity-type label. The sequence may run from 000 to 999 for files produced that day; the guide examples use 001 and 002. ReportingPeriod is the year-end date in YYYY-MM-DD, such as 2017-12-31. Timestamp uses YYYY-MM-DDThh:mm:ss and may include fractional seconds. A service provider’s sender number is used in the message identifier, whereas document identifiers use the reporting institution’s number.
New, corrected and nil message indicators
MessageTypeIndic is required and must match the submission type selected in the portal. CRS701 means new information, CRS702 means correction or deletion of previously submitted information, and CRS703 means no reportable data after the required account review. AccountReport may be omitted for a nil XML return. CorrMessageRefID is not used for CRS, whether at header or DocSpec level. Cancelling a complete message requires deletion of its records rather than a header-level cancellation reference.
Individual residence and missing tax numbers
PersonParty_Type covers individuals and controlling persons. Report a separate AccountReport for each reportable tax-residence jurisdiction; do not put all jurisdictions into one IRAS account record. A residence change to accepted data requires voiding the affected report and submitting a new report with the new country code. Undocumented accounts use SG. TIN can repeat for recognised numbers in the residence jurisdiction. If unavailable, encouraged reason codes are IRAS101 for no TIN issued, IRAS102 for no reporting requirement, IRAS103 for changed circumstances while obtaining new self-certification and IRAS104 for other documented reasons. If neither TIN nor reason is supplied, omit the element instead of inserting zeros or artificial letters. Omit issuedBy if the issuing country is unknown.
Individual names and birth information
FirstName and LastName are required. If a complete first name is unavailable, an initial or NFN may be used; surname can accommodate the legally used prefix, suffix or two surnames, while structured names are preferred. Optional components include preceding title, title, middle name, name prefix, generation identifier and suffixes. Name-type codes OECD202–208 identify individual, alias, nickname, also-known-as, doing-business-as, legal and birth names. Birthdate uses YYYY-MM-DD and may be omitted where unavailable for a preexisting account. If birthplace is reported, supply city, optionally its subentity, and either current country code or former country name. Nationality is not applicable for CRS.
Addresses and undocumented accounts
Use the permanent residence address, or the mailing address on file if permanent residence is unavailable. Prefer AddressFix: City is required, PostCode should be included where available, and optional components cover street, building, suite, floor, district, post-office box and state/province. A structured address may use AddressFree for the street line while retaining fixed city, province and postcode. If no structured address is possible, use a single AddressFree string with spaces, slashes or line breaks, and omit AddressFix. CountryCode is still required. An undocumented account uses SG and “Undocumented” in AddressFree. Legal-address codes OECD301–305 denote residential/business, residential, business, registered office and unspecified.
Entity identification
OrganisationParty_Type contains tax residence, identification number, legal name and address. Multiple reportable residences require separate AccountReports; an accepted residence-code change follows the void-and-new procedure. An entity IN may be a TIN, company registration number or another number recognised by the residence tax authority, and may repeat. Missing-IN reasons use the same IRAS101–104 framework; otherwise omit the unavailable element without inventing a number. issuedBy gives the issuing jurisdiction and INType can describe the number type. Legal name and address are validation elements. Name-type attributes are optional.
Reporting institution and CRS body
Provide CrsBody with ReportingFI and one ReportingGroup for each body. AccountReport repeats within that group. ReportingFI identifies the institution maintaining the account, not the service provider transmitting the file. Its IN uses the registered Singapore tax reference, including entity type, space and identifier; do not move that type into INType. Use the reference associated with the institution’s CRS registration if it has several. For a trustee-documented trust, identify the trust and its IRAS-issued TDT reference, not merely the trustee. ReportingFI and account reports include DocSpec. Sponsor, Intermediary and PoolReport are not applicable to CRS. AccountReport is mandatory except a nil return or an institution-only correction.
Account number, status and holder classification
Use the institution’s account number or equivalent unique identifier; only exceptionally, where no numbering system exists, use NANUM. Codes OECD601–605 identify IBAN, other bank number, ISIN, other securities number and other identifiers. Supply available IBAN/ISIN with the appropriate type. The account may carry undocumented, closed and dormant Boolean attributes. AccountHolder is either Individual or Organisation; an entity also needs AcctHolderType. CRS101 means passive NFE with a reportable controlling person, CRS102 means a reportable person, and CRS103 means a passive NFE that is itself reportable. Do not apply entity classifications to an individual holder.
Passive NFE and controlling-person reporting: six scenarios
IRAS generally requires one account report per reportable controlling person. In the guide’s six cases: (1) entity and sole CP both resident in X require one CRS101 report; (2) entity and two CPs all in X require two CRS101 reports, one for each CP; (3) entity in reportable X and CPs in reportable Y and Z require two CRS101 reports plus one CRS103 entity report; (4) entity in X, one CP in X and another in Y require two CRS101 reports without a separate entity report; (5) entity in non-reportable X and CP in reportable Y require one CRS101 report; (6) entity in reportable X and CP in non-reportable Y require one CRS103 report. Each CP’s identifying data uses PersonParty_Type. Do not merge multiple reportable CPs into one report merely because they share a country.
Controlling-person relationships
Where available, CtrlgPersonType identifies the CP role. CRS801–803 mean legal-person control through ownership, other means or senior managing office. Trust roles CRS804–808 are settlor, trustee, protector, beneficiary and other. Equivalent roles for another legal arrangement are CRS809–813 in the same order. If a person has multiple roles, such as settlor and beneficiary, repeat the controlling-person element within the same account report for each relationship. Omit the role element if the information is unavailable in the institution’s records.
Balances, closure and payment categories
Report balance or value appropriate to the account: deposits/custody balances, cash value for insurance or annuity contracts, or debt/equity interest value. A closed account must have zero balance and the closed-account indicator. Amounts use two decimal places and mandatory three-letter ISO 4217 currency codes. Depository accounts report gross interest; custodial accounts report gross dividends, interest, sale/redemption proceeds and other asset income. Debt/equity and insurance/annuity accounts report gross payments including redemptions. Repeat Payment by type: CRS501 dividends, CRS502 interest, CRS503 gross proceeds/redemptions and CRS504 other CRS income. Each payment has its own amount and currency.
Document types and unique record identifiers
DocSpec distinguishes OECD0 resent institution data, OECD1 new data, OECD2 correction and OECD3 deletion. OECD10–13 are corresponding test values and must not be mixed with live data. OECD0 is only for unchanged ReportingFI in the same reporting period; a new year needs OECD1. ReportingFI DocRefID is reporting year + ten-character institution reference + FI + three-digit sequence. AccountReport DocRefID is reporting year + ten-character institution reference + a unique suffix of up to thirty characters. Pad short tax references with hyphens; use TDT reference for a trustee-documented trust. A new correction/deletion needs a new DocRefID. CorrDocRefID points to the latest accepted version, not automatically the original record. Every message likewise needs a unique MessageRefID. The only reused DocRefID is unchanged ReportingFI resent with OECD0.
Correction rules and permitted combinations
Only ReportingFI and AccountReport are independently correctable. To change any child, resend the whole affected correctable element and all its children; do not resend unrelated accounts. Use CRS702 for corrections, allowing OECD2 and/or OECD3 records but not new OECD1 records. An unchanged institution is resent as OECD0 with the same DocRefID and no correction reference. The matrix permits an OECD2 institution with no account, corrected accounts or deleted accounts; an OECD3 institution with no accounts or deleted accounts, subject to all associated accounts already being removed; and OECD0 only with corrected or deleted accounts. A correction of a correction must wait for acceptance of the first correction and reference that latest accepted record. All linked messages relate to the same reporting period.
Correction examples one and two: successive versions
Example one first corrects an account payment, then corrects its balance. The second correction links to the first correction’s DocRefID, retains the unchanged institution as OECD0 and omits the unaffected second account. Example two first corrects the institution address alone, then corrects one account. The later account correction resends the latest corrected institution version as OECD0, not the original institution version. An institution-only correction can omit account reports if none changed. Preserve a chain of accepted record identifiers so each later operation references the current version.
Correction examples three to seven: child edits and deletions
Example three changes a CP address by resending the complete account, including number, holder, CP and balance, plus the institution. Example four changes both institution address and one account balance, resending both complete elements but not the second unchanged account. Example five removes one of two institution addresses using a corrected institution that retains its name and remaining address; accounts are omitted. Example six deletes an account with OECD3 and its child data plus the institution, omitting the unaffected account. Institution deletion is rejected while any associated account remains. Example seven adds a Payment child through an OECD2 replacement of the complete existing account, not through a standalone new payment record.
Correction examples eight and nine: genuinely new records
Example eight adds another account for an already reported institution. Use a new CRS701 message with the new account as OECD1 and the unchanged institution as OECD0. This is relevant to split files or late reporting and is different from adding a child within an existing account. Example nine adds a different institution and its accounts in a new CRS701 message, with that institution and those accounts all treated as new records. Do not mix these new records into a CRS702 correction file.
Schema diagrams, namespaces and source inconsistencies
Appendix A maps the header, body, reporting institution/group, account, account-number attributes, individual/entity holders, CPs, payments, names and addresses to the schema. It also shows non-CRS pool/sponsor/intermediary branches that must not be mistaken for Singapore CRS requirements. Appendix B associates crs with CrsXML_v2.0.xsd, cfc with CommonTypesFatcaCrs_v2.0.xsd, ftc with FatcaTypes_v1.2.xsd, stf with OECDCrsTypes_v5.0.xsd, and iso with isocrstypes_v1.1.xsd. The 2018 revision raised file size from 2 MB to 5 MB; the 2020 revision added version 2.0, minimum string lengths, length caps, fractional timestamps and an updated country list. Some diagram notes say DocRefID starts with the tax reference, while the detailed IRAS format explicitly begins with reporting year. Use the full year-plus-reference format, rather than the simplified diagram identifiers. The institution-only correction diagram labels an unchanged institution as corrected in a note despite the surrounding example changing its address; follow the specific operation and correct reference chain.
Official source
This article independently explains the substantive contents of the official PDF, including the relevant conditions, procedures and annexes. The linked document remains the authoritative source for its original wording, and later changes should be checked separately.
Read the official PDF ↗