Modelo 289 — Spain’s annual CRS account return

Modelo 289 is Spain’s annual CRS financial-account return, and it is not a form — it is a SOAP web service with a 512 KB message ceiling, two message types, and a correction grammar borrowed wholesale from the OECD. A Spanish institution with reportable accounts files it between January and the end of May; one with none still files. This is what the return carries, how it is transmitted, and how corrections and substitutions actually work.

1. What Modelo 289 is

The full name is “Declaración informativa anual de cuentas financieras en el ámbito de la asistencia mutua” — the annual information return on financial accounts in the field of mutual assistance. It is the Spanish channel for the OECD Common Reporting Standard and for DAC2, and it sits at procedure code GI42 in the Agencia Tributaria’s electronic office.

The legal chain behind it is worth having to hand, because auditors ask for it. Spain’s participation rests on the Convention on Mutual Administrative Assistance in Tax Matters (Strasbourg, 25 January 1988, as amended by the Protocol of 27 May 2010), whose Article 6 permits automatic exchange, and on the Multilateral Competent Authority Agreement signed in Berlin on 29 October 2014. On the EU side, Council Directive 2014/107/EU amended Directive 2011/16/EU to make automatic exchange of financial-account information mandatory between member states. Domestically, Real Decreto 1021/2015 of 13 November established the identification and reporting obligations, and Orden HAP/1695/2016 of 25 October approved the model, with the content of the return set out in its Annex III.

2. Who files — and the return nobody expects

The obligation falls on Spanish reporting financial institutions with accounts held or controlled by residents of the jurisdictions in the annexes. For a payments firm the threshold question sits prior to Modelo 289: whether it is a reporting financial institution at all, and whether its payment accounts or e-money balances are financial accounts under the standard.

The trap sits on the other side of that answer. Since 1 January 2022, an institution inside scope with no reportable accounts must still file an annual negative declaration. A web form covers exactly that case, so the negative filing does not need the web-service build — it needs someone to own the calendar entry. A firm that concludes “nothing to report” and files nothing has missed an obligation rather than discharged one.

3. The filing window

The statutory window runs from 1 January to 31 May of each year, covering financial information for the immediately preceding year. For the 2025 reference year the Agencia Tributaria publishes the campaign as running from 1 January to 1 June 2026.

A second date matters when explaining the timeline to a customer or a group tax function: the Agencia Tributaria forwards the consolidated data to member states and third states in September each year, in separate files per operation block, and sends presentations relating to earlier years periodically as they arrive. A correction filed in July does not wait twelve months to travel.

4. How it is transmitted

Presentation is telematic, by a web service based on the exchange of XML messages. The presentation message is CrsNtnlPresentation, an adaptation of the OECD’s published CRS_OECD message; the service definition is the CrsNtnlDeclaration WSDL, with the input message based on the CrsNtnlPresentation schema and the response on CrsNtnlReceipt. On receipt the Agencia Tributaria automatically validates both the XML format and the business rules.

Four build constraints follow from the specification, and each has caught teams out:

• Message size is capped at 512 KB, a limit the specification itself describes as provisional. At any real account volume the return must be split, which makes the presentation identifier and the correction grammar load-bearing rather than cosmetic.
• There is no XML signature. The SOAP messages are not signed with XMLDSig or anything analogous; what happens instead is SSL authentication with a client certificate — a recognised certificate of a natural or legal person admitted by the Agencia Tributaria. Sending the presentation constitutes acceptance of the data it contains.
• Test certificates are not accepted, even in pre-production, because of the tax administration’s security policy. A real certificate is a dependency of the first test, not of go-live.
• Dry runs are explicit. There is a pre-production environment, and in production the header field PresentationType takes the value Simulation instead of Normal. Get that wrong and the data is forwarded to the foreign tax administration concerned.

The presentation header carries the declarant’s NIF in NationalTIN, the reference year in Year, a presenter block with NIF, name and relationship to the declarant, and a PresentationCode the sender assigns. That code has a prescribed shape: 289 + the reference year + a remainder that must make the code unique for that declarant and year. It is the handle every later correction hangs off.

5. DAC2 or CRS: one return, two message types

A single return is not a single message. The header field MessageType splits the population by legal basis, and the split follows Article 4 of Real Decreto 1021/2015:

The practical consequence is that the same reference year produces at least two message streams, each with its own presentations, receipts and correction history. A reconciliation that counts “the accounts we filed” without splitting by MessageType will not tie to the receipts.

One field controls how strictly the response reads. DataQuality takes Maximum or Medium: at Maximum, the response shows rejections for errors and warnings for anomalies, and the message can then be re-sent at Medium, where only errors reject. Using Maximum as a deliberate first pass turns the tax administration’s validator into a free data-quality report.

6. Worked example — first year for a Spanish institution

Facts: a Spanish reporting financial institution completes its first CRS year with roughly 60,000 reportable accounts, spread across EU and non-EU jurisdictions, and around 4% of holders whose foreign TIN was never captured at onboarding.

Which rules apply: the return is due in the January–May window. Volume forces a split against the 512 KB ceiling, and the DAC2/CRS division forces a second split by legal basis. On the missing identifiers, the Agencia Tributaria has been explicit: the TIN of the account holder’s jurisdiction of residence must be reported, including for pre-existing accounts, and institutions must make reasonable efforts to obtain it, with a deadline of two years from the account’s classification as pre-existing.

What the practitioner does: runs the whole population at DataQuality Maximum in pre-production first, reads the warnings as a remediation backlog rather than noise, and starts the reasonable-efforts outreach on the 4% in January — not in May, because a documented outreach attempt is the evidence that discharges the standard, and it cannot be manufactured retrospectively. Presentation codes are generated as 289 + year + a sequence, one per chunk per message type, and stored against the receipt.

Outcome: the return goes in as a set of presentations, each with its own receipt, and the missing-TIN population is a tracked remediation list with dated evidence rather than a silent defect that surfaces when a receiving jurisdiction queries it. The Agencia Tributaria publishes a list of frequent Modelo 289 errors, refreshed in November 2025; reading it beforehand is cheaper than discovering its contents through rejections.

7. OECD1, OECD2, OECD3 — the correction grammar

Spain does not implement “complementary” and “substitutive” returns as separate filings. It implements them through the OECD’s DocSpec mechanism, and the mapping is where most implementation error lives. Inside DocSpec, the field DocTypeIndic takes:

• OECD1 — a new account record, added to those already presented;
• OECD2 — a correction;
• OECD3 — a cancellation;
• OECD0 — the exception: the Reporting FI itself is not being corrected or cancelled while account records are.

Two rules govern how they travel. OECD1 must be sent in its own presentation; OECD2 and OECD3 may share one. The Agencia Tributaria consolidates and forwards them the same way, in two operation blocks — which is why the data eventually sent for the Reporting FI is whatever arrived in the last presentation of each operation type.

Identity is the other half. DocRefId uniquely identifies an Account Report or a Reporting FI. When a later presentation corrects or cancels one, the correction carries a new unique DocRefId and names the prior one in CorrDocRefId. The combinations are prescribed:

8. Worked example — a substitutive return

Facts: after filing, an institution discovers that a systematic mapping error mis-stated balances across a whole product line. The correct answer is to replace the year’s submission, not to patch it record by record.

Which rules apply: a substitutive declaration is performed by sending, consecutively and with no new records or corrections in between, OECD3 cancellations of every previously submitted account record still in force — across as many presentations as it takes — and only then presenting the new information with OECD1. Cancelling the Reporting FI itself requires cancelling all its live account records too; where none remain, no Account Reports are reported and the Reporting FI alone carries OECD3.

What the practitioner does: works from a stored register of every DocRefId presented and its current status, because the cancellation set is defined by what is still in force, not by what was in the original file. Interleaving an OECD1 in the middle of the cancellation run breaks the sequence and leaves a hybrid state that is painful to unwind. The run is scripted, not hand-assembled.

Outcome: the year is cleanly replaced, and the register — not the original XML — is what makes that possible. Any firm that treats submitted files as write-once artefacts and does not keep a queryable DocRefId ledger will find its first substitution far harder than the rule requires.

9. Reading the receipt

The response message is a Receipt, and it is more granular than an acknowledgement. Its header carries a result of Accepted, Partially Accepted or Rejected; where the result is Accepted or Partially Accepted it also carries a Código Seguro de Verificación (CSV) and an Expediente reference — the two identifiers to keep, because they are what proves the filing later.

The body then reports counts of accepted and rejected DocRefIds and, for each one, validation details with an error or warning type, an error code and a message. A rejected presentation can come back either as a Receipt carrying that detail or as a SoapFault — two different failure shapes a client has to handle. Partially Accepted is the state that causes real damage when it is treated as success: part of the file is in, part is not, and only the per-DocRefId detail says which.

FAQ

What to do, today

• Tax reporting lead: confirm the negative-declaration calendar entry exists even if you expect nothing to report, and diary the December order that updates Annexes I and II.
• Engineer: size against 512 KB and design the split before anything else; generate PresentationCode as 289 + year + sequence and persist it with the receipt.
• Data owner: build a queryable DocRefId ledger with current status. Corrections and substitutions are defined against what is still in force.
• Operations: run the first pass at DataQuality Maximum in pre-production, and treat Partially Accepted as a failure state requiring per-record triage.
• Onboarding and CDD: start reasonable-efforts outreach for missing jurisdiction TINs in January, with dated evidence, against the two-year clock from classification as pre-existing.

Related: CRS for EMIs — are you a reporting financial institution? · How a CRS annual return is built · Modelo 196 — Spanish monthly account reporting · Spain reporting calendar