> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FATCA

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Push accounts">
    `POST /reports/fatca/v1/submissions/{submissionId}/accounts` with a batch of accounts.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

| Status            | Meaning                                                           |
| ----------------- | ----------------------------------------------------------------- |
| `DRAFT`           | Open for pushing accounts; not yet submitted.                     |
| `PROCESSING`      | Submitted; being reported to the tax authority.                   |
| `ACTION_REQUIRED` | Some accounts were rejected and need correcting and re-reporting. |
| `REPORTED`        | Accepted by the tax authority.                                    |
| `FAILED`          | Reporting failed.                                                 |

## Webhook

Instead of polling for status, pass a `webhookUrl` when you [open a submission](/regulatory/rrc/api/fatca/create-submission). Once the submission finishes processing, the connector calls it with a POST carrying a JSON body:

```json theme={null}
{"submissionId": "<submission id>", "status": "ACCEPTED"}
```

`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.

| Environment | IP addresses                                                |
| ----------- | ----------------------------------------------------------- |
| Test        | 34.78.184.35, 35.195.129.148, 34.76.178.43, 88.119.208.29   |
| Production  | 130.211.66.226, 35.205.15.220, 104.155.69.28, 88.119.208.29 |

## Authentication

All endpoints require a bearer JWT obtained via the OAuth2 `client_credentials` grant. See [Authentication](/regulatory/rrc/authentication).

## Resources

<CardGroup cols={2}>
  <Card title="Submissions" icon="folder-plus" href="/regulatory/rrc/api/fatca/create-submission">
    Open a reporting batch, submit it, and track its status
  </Card>

  <Card title="Accounts" icon="building-columns" href="/regulatory/rrc/api/fatca/push-accounts">
    Push, amend, and delete the accounts you report
  </Card>

  <Card title="Report" icon="chart-line" href="/regulatory/rrc/api/fatca/get-submission-report">
    Reported-versus-pending counts of accounts and messages
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/regulatory/rrc/api/fatca/get-account-errors">
    Accounts the tax authority rejected, with error codes
  </Card>
</CardGroup>