What a Tax Return API Should Actually Do

If you're building a fintech app, a payroll product, a service bureau or a vertical tool for tax offices, sooner or later someone asks: "Can we file the return too?" Then you go looking for a tax API, and you find out how few of them do the whole job.

This article is a checklist. It's what we think a tax return API should do if you're going to put your customers' refunds on it.

1. A real return model, not a form filler

A return isn't a set of PDF fields. It's a data model: a taxpayer, a spouse, dependents, income documents, adjustments, credits, payments, and the relationships between them. A good API lets you send structured data (a W-2 is a W-2 object, not a list of box numbers) and handles the calculation.

Ask:

• Does it calculate, or just store what you send?
• Does it handle the forms your users actually need: Schedules 1, 2 and 3, Schedule C, Schedule 8812, the EIC worksheet, education credits?
• Does it know which tax year it's calculating, with that year's tables?

2. E-file through MeF, end to end

The IRS accepts electronic returns through the Modernized e-File system (MeF). Getting a return accepted involves more than generating XML:

• The return has to match the IRS schema for that tax year
• It has to pass the IRS business rules
• It goes out in a transmission from an authorized transmitter
• The IRS sends back an acknowledgment: accepted or rejected, with reasons

IRS Publication 4164, Modernized e-File (MeF) Guide for Software Developers and Transmitters, is the reference. We wrote a plain-English version: MeF e-file explained for software teams.

The secret: ask any vendor this one question: "Show me a rejected acknowledgment and how your API returns it." Anyone can show an accepted return. The rejections are where the work is: the business-rule code, the field it points to, and a way for your user to fix it and resend without starting over. If the answer is a vague error string, the API was built for a demo, not a season.

3. Status you can build a product on

Your users will ask "where's my return?" more than anything else. The API should give you a clear status for each return, from draft through transmitted, accepted or rejected, and on to funded if there's a bank product. Webhooks or a socket beat polling.

4. Bank products

Many taxpayers pay their preparation fee from their refund through a refund transfer, and some want a refund advance. If your product serves tax offices, that's not optional. The API should handle the bank enrollment for the office, the application on the return, and the funding status. More in bank products through an API.

5. Offices, preparers and EFINs

If your customers are tax offices, the API has to model them: the firm and its EFIN, the preparers and their PTINs, the sites, the permissions. Returns belong to an office. Transmissions go out under an EFIN. See offices and EFINs as data.

6. Security that matches the data

Tax data is some of the most sensitive data there is. Look for encryption in transit and at rest, scoped credentials per partner, audit logs, and data kept to the minimum your use case needs. IRS Publication 1345 sets out the security and privacy obligations of authorized e-file providers.

7. A sandbox and a real test plan

You shouldn't touch production until you've run real scenarios: different filing statuses, dependents, rejected returns, a bank product. A sandbox with test data, and a vendor who walks you through testing, saves weeks.

The short checklist

Capability	Question to ask
Return model	Does it calculate for the stated tax year?
MeF	Can I see a rejected ack and the fix flow?
Status	Do I get events, or do I have to poll?
Bank products	Office enrollment, application and funding status?
Offices	EFINs, PTINs, sites and permissions?
Security	Scoped keys, audit logs, encryption?
Testing	Sandbox and a test plan before production?

Red flags when evaluating a vendor

• "We support all forms." No one does. Ask for the list for the tax year you need, and whether it includes the state returns your users file.
• The demo only shows accepted returns. Ask for a reject, a fix and a resend.
• No answer about tax-year changes. Ask what happened when the 2025 tax law changed amounts mid-year, and how quickly the engine was updated.
• Shared credentials. If every partner uses the same kind of key with the same access, your users' data is only as safe as the least careful partner.
• No audit log. You'll need to answer "who changed this return and when." If the API can't tell you, neither can you.

How the pieces fit in a product

A typical flow in a fintech app looks like this:

1. Your user signs in to your app and starts a return
2. Your app sends their data to the API: personal details, W-2s, 1099s
3. The API calculates and returns the result: refund or balance due, the forms used
4. Your user reviews and signs
5. The API transmits through MeF and reports the acknowledgment
6. If there's a bank product, the API reports the funding status
7. Your app shows the user where everything stands

Your team owns the experience. The API owns the tax logic and the IRS plumbing.

Who this is for

• Fintechs and banking apps that want users to file where their money already is
• Payroll and HR platforms that already hold the W-2
• Service bureaus that support many tax offices
• Vertical software for tax offices that wants filing without building an engine

We have the API

TaxWallet has the API: tax returns, MeF e-file, bank products, offices and EFINs. Tell us what you're building and we'll walk you through it and send sandbox access and the docs. DM API on Instagram @taxwallet.ai, or read more on our developers page.

FAQ

What is MeF?

The IRS Modernized e-File system, which accepts electronic tax returns and sends back acknowledgments.

Can any app e-file returns?

Software has to pass IRS testing for each tax year, and returns go out through an authorized e-file provider. Publication 1345 and Publication 4164 have the details.

Do you publish pricing?

We talk through your use case first, because volume and features vary. DM API to start.

Is there a sandbox?

Yes. Access and docs are sent on request after a short conversation.