Skip to main content
FATCA (Foreign Account Tax Compliance Act) requires financial institutions to report accounts held by US persons, and by entities with US owners, to their tax authority once a year. This connector exposes a REST API: you push accounts into a submission for a reporting year, then hand it off to be reported to the tax authority.

​
How it works

A submission holds every account you report for one reporting year. Push accounts into it over as many calls as you need, then submit it:
1

Open a submission

POST /reports/fatca/v1/submissions with the reporting year. You get back a submissionId that scopes every subsequent call. Optionally include a webhookUrl to be notified when the submission finishes processing.
2

Push accounts

POST /reports/fatca/v1/submissions/{submissionId}/accounts with a batch of accounts.
3

Submit

POST /reports/fatca/v1/submissions/{submissionId}:submit starts report generation and submission to the tax authority. After this call the submission is no longer editable.
4

Track progress and fix errors

Poll GET .../status for the high-level state, or GET .../report to track progress pending counts of accounts and messages. GET .../accounts/errors lists the accounts with unresolved tax authority validation errors, with the error codes to fix.

​
Nothing to report

If you have no reportable accounts for a year, open a submission and submit it without pushing any accounts. This reports that you have nothing to report for the year.

​
Corrections

Opening a submission for a year that has already been reported returns kind: CORRECTION. A correction works exactly like the first submission, using the same endpoints and keyed by accountNumber, but each call now acts on what the tax authority already holds:
  • POST /accounts adds accounts the tax authority has not seen. An account it already has is rejected.
  • PUT /accounts/{accountNumber} amends an already-reported account. Amending an account the tax authority has never seen is rejected.
  • DELETE /accounts/{accountNumber} deletes the account report at the tax authority. An account it has never seen returns 404.
Like any submission, a correction only reaches the tax authority once you submit it. Submitting a correction with no changes returns 409. You can open as many rounds for a year as you need, but only one at a time: opening a submission for a year whose earlier round is still being processed returns 409.

​
Pushing accounts

A batch is not all-or-nothing. Accounts that fail are reported individually and the rest of the batch is still saved, so a 207 response means some accounts were rejected while the others were stored. Send the optional Idempotency-Key header to make a retried batch safe. An entity holder of type OWNER_DOCUMENTED_FFI_WITH_SPECIFIED_US_OWNERS or PASSIVE_NFFE_WITH_SUBSTANTIAL_US_OWNERS requires substantialOwners on the account. Other holders do not accept it.

​
Submission status

status on a submission moves through:

​
Webhook

Instead of polling for status, pass a webhookUrl when you open a submission. Once the submission finishes processing, the connector calls it with a POST carrying a JSON body:
status is the tax authority’s validation result for the submission: ACCEPTED or REJECTED. Calls originate from the following IP addresses; whitelist them to receive the webhook.

​
Authentication

All endpoints require a bearer JWT obtained via the OAuth2 client_credentials grant. See Authentication.

​
Resources

Submissions

Open a reporting batch, submit it, and track its status

Accounts

Push, amend, and delete the accounts you report

Report

Reported-versus-pending counts of accounts and messages

Errors

Accounts the tax authority rejected, with error codes
Last modified on September 25, 2026