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

# CRS

CRS (Common Reporting Standard) is the global standard for the automatic exchange of financial account information. Financial institutions report their reportable accounts once a year to their national tax authority, which exchanges the data with other jurisdictions. 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/crs/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/crs/v1/submissions/{submissionId}/accounts` with a batch of accounts.
  </Step>

  <Step title="Submit">
    `POST /reports/crs/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>

While a submission is still a draft you can [delete it](/regulatory/rrc/api/crs/delete-submission) along with every account pushed under it. To change anything you have already reported, open a new submission for the same 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. 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.

## 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/crs/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).

## API Reference

Explore the full API specification in the [Swagger documentation](https://api.rrc.finventi.com/reports/crs/swagger-ui/index.html).

<Info>
  **IP Whitelisting Required:** Before you can access the Swagger documentation, your IP address must be whitelisted. Contact us to register your IP addresses.
</Info>

## Resources

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

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

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

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