> ## 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. # Push accounts > Add a batch of reportable accounts to a submission. ## OpenAPI ````yaml post /reports/fatca/v1/submissions/{submissionId}/accounts openapi: 3.1.0 info: title: FATCA REST API description: >

REST API for reporting FATCA (Foreign Account Tax Compliance Act) US reportable account data. Open a submission for a reporting year, send the reportable accounts under its id, then submit it to the tax authority.

version: 0.0.1 servers: - url: https://api.rrc.dev.finventi.com description: Development - url: https://api.rrc.finventi.com description: Production security: - bearer-jwt: [] tags: - name: FATCA REST API description: >- REST API for submitting and correcting FATCA account data. Create a submission for a reporting year, push the reportable accounts under its id, the service will package the account data and send it to the regulatory authority. paths: /reports/fatca/v1/submissions/{submissionId}/accounts: post: tags: - FATCA REST API summary: Push accounts description: >- Adds a batch of reportable accounts to the submission, keyed by account number. Push each account as it stands, with its holder and any substantial owners attached to it; each account becomes exactly one account report. In a submission, pushing an account number already present replaces it. In a correction this adds accounts the tax authority has not seen — an account it has is rejected, and must be amended with PUT or removed with DELETE. Accounts that fail are reported individually and the rest of the batch is still saved. operationId: postAccounts parameters: - name: Idempotency-Key in: header description: >- Client-provided idempotency key. UUID v4 suggested, max 255 characters. If provided, duplicate requests with the same key return the cached response. schema: type: string maxLength: 255 - name: submissionId in: path required: true schema: type: string requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/FatcaAccount' examples: example: $ref: '#/components/examples/FatcaPostAccountsRequest' required: true responses: '201': description: All accounts saved content: application/json: schema: type: array items: $ref: '#/components/schemas/FatcaAccountResult' examples: example: $ref: '#/components/examples/FatcaPostAccounts201' '207': description: Partial success content: application/json: schema: type: array items: $ref: '#/components/schemas/FatcaAccountResult' examples: example: $ref: '#/components/examples/FatcaPostAccounts207' '400': description: All failed content: application/json: schema: type: array items: $ref: '#/components/schemas/FatcaAccountResult' examples: example: $ref: '#/components/examples/FatcaPostAccounts400' components: schemas: FatcaAccount: type: object description: >- A US reportable account. Push the account as it stands, with its holder and any substantial owners attached to it. Each account you push becomes exactly one account report. properties: accountNumber: type: string description: >- Account number, or its functional equivalent where the account has no number. Identifies the account within the submission, so it must be unique across the accounts you push. example: LT601010012345678901 maxLength: 200 minLength: 0 accountNumberType: type: string description: >- Type of the account number. IBAN values are checked against the IBAN structure. enum: - IBAN - OBAN - ISIN - OSIN - OTHER - ELECTRONIC_MONEY_PRODUCT example: IBAN balance: type: number description: >- Balance at the end of the reporting year. For a closed account, the balance on the day it was closed. example: 12345.67 currency: type: string description: >- Currency the balance is denominated in, ISO 4217. Report one currency per account. example: USD minLength: 1 closed: type: boolean default: false description: The account was closed during the reporting year. accountHolder: $ref: '#/components/schemas/FatcaAccountHolder' description: The holder of the account. substantialOwners: type: array description: >- US owners of an entity holder. Required for types `OWNER_DOCUMENTED_FFI_WITH_SPECIFIED_US_OWNERS` and `PASSIVE_NFFE_WITH_SUBSTANTIAL_US_OWNERS`, not accepted otherwise. items: $ref: '#/components/schemas/FatcaSubstantialOwner' payments: type: array description: >- Payments made to the account during the year. Send at most one entry per payment type, carrying the gross total for the whole year. items: $ref: '#/components/schemas/FatcaPayment' required: - accountHolder - accountNumber - accountNumberType - balance - currency FatcaAccountResult: type: object description: Result of pushing, updating or deleting a single account properties: status: $ref: '#/components/schemas/Status' accountNumber: type: string description: >- The account number echoed back, to correlate this result with your record errors: type: array description: Why the account was rejected. Empty when the account was accepted. items: $ref: '#/components/schemas/FieldError' required: - errors - status FatcaAccountHolder: type: object description: >- The holder of the account. Supply exactly one of `individual` or `organisation`. properties: individual: $ref: '#/components/schemas/FatcaIndividual' organisation: $ref: '#/components/schemas/FatcaHolderOrganisation' FatcaSubstantialOwner: type: object description: >- A US owner of an entity holder. Supply exactly one of `individual` or `organisation`. properties: individual: $ref: '#/components/schemas/FatcaIndividual' organisation: $ref: '#/components/schemas/FatcaOrganisation' FatcaPayment: type: object description: A payment made to the account during the reporting year. properties: type: type: string description: Type of the payment. enum: - DIVIDENDS - INTEREST - GROSS_PROCEEDS_OR_REDEMPTIONS - OTHER example: INTEREST amount: type: number description: Gross total for the whole reporting year. example: 120 currency: type: string description: Currency of the amount, ISO 4217. example: USD minLength: 1 description: type: string description: Free-text description of the payment. example: Interest credited during 2025 maxLength: 4000 minLength: 0 required: - amount - currency - type Status: type: string enum: - SUCCESS - FAILED FieldError: type: object description: Per-item validation/processing error properties: code: type: string description: >- Validation error code returned by the regulatory authority; only present for records that failed authority validation example: 51 fields: type: array description: >- Fields that caused the error; may be empty for errors not tied to a single field (e.g. cross-field validation) example: - iban items: type: string message: type: string description: Human-readable error message required: - fields FatcaIndividual: type: object description: A natural person. properties: residenceCountryCodes: type: array description: >- Every jurisdiction the person is tax resident in, ISO 3166-1 alpha-2. example: - US items: type: string tins: type: array description: Tax identification numbers. items: $ref: '#/components/schemas/FatcaTin' names: type: array description: >- Names the person is reported under. Send several only where the person is known under different names; each entry then needs a `nameType`. items: $ref: '#/components/schemas/FatcaIndividualName' maxItems: 2147483647 minItems: 1 addresses: type: array items: $ref: '#/components/schemas/FatcaAddress' maxItems: 2147483647 minItems: 1 nationalities: type: array description: Nationalities, ISO 3166-1 alpha-2. example: - US items: type: string birthInfo: $ref: '#/components/schemas/FatcaBirthInfo' required: - addresses - names FatcaHolderOrganisation: type: object description: An entity holding the account. properties: type: $ref: '#/components/schemas/FatcaOrganisationType' description: >- Why the entity is reported. The two owner-documented and passive types additionally require `substantialOwners` on the account. example: PASSIVE_NFFE_WITH_SUBSTANTIAL_US_OWNERS residenceCountryCodes: type: array description: >- Every jurisdiction the entity is tax resident in, ISO 3166-1 alpha-2. example: - LT items: type: string tins: type: array description: Tax identification numbers. items: $ref: '#/components/schemas/FatcaTin' name: type: string description: Name of the entity example: Example Holdings UAB maxLength: 200 minLength: 0 nameType: type: string description: Type of entity name enum: - LEGAL - DOING_BUSINESS_AS - ALIAS - ALSO_KNOWN_AS - SMF_ALIAS_OR_OTHER example: LEGAL addresses: type: array items: $ref: '#/components/schemas/FatcaAddress' maxItems: 2147483647 minItems: 1 required: - addresses - name - type FatcaOrganisation: type: object description: An entity owning the account holder. properties: residenceCountryCodes: type: array description: >- Every jurisdiction the entity is tax resident in, ISO 3166-1 alpha-2. example: - US items: type: string tins: type: array description: Tax identification numbers. items: $ref: '#/components/schemas/FatcaTin' name: type: string description: Name of the entity example: Example Holdings LLC maxLength: 200 minLength: 0 nameType: type: string description: Type of entity name enum: - LEGAL - DOING_BUSINESS_AS - ALIAS - ALSO_KNOWN_AS - SMF_ALIAS_OR_OTHER example: LEGAL addresses: type: array items: $ref: '#/components/schemas/FatcaAddress' maxItems: 2147483647 minItems: 1 required: - addresses - name FatcaTin: type: object description: A taxpayer identification number. properties: number: type: string description: The number. A US taxpayer identification number is nine digits. example: 123456789 maxLength: 100 minLength: 0 issuedBy: type: string description: Jurisdiction that issued the number, ISO 3166-1 alpha-2. example: US minLength: 1 required: - issuedBy - number FatcaIndividualName: type: object description: A name a natural person is reported under. properties: firstName: type: string description: >- Given name. Use initials, or the value `NFN` (no first name), where it is not known. example: John maxLength: 100 minLength: 0 middleNames: type: array example: - Michael items: type: string lastName: type: string description: Family name. example: Smith maxLength: 100 minLength: 0 nameType: type: string description: >- Type of person name. Required on every entry when you send more than one name. enum: - LEGAL - AT_BIRTH - INDIV - ALIAS - NICK - ALSO_KNOWN_AS - SMF_ALIAS_OR_OTHER example: LEGAL required: - firstName - lastName FatcaAddress: type: object description: >- An address of a holder or substantial owner. Supply at least one of `addressFix` or `addressFree`; `addressFix` is preferred. properties: addressFix: $ref: '#/components/schemas/FatcaAddressFix' description: The address split into its parts. addressFree: type: string description: Address as free text. example: 100 maxLength: 500 minLength: 0 countryCode: type: string description: Country of the address, ISO 3166-1 alpha-2. example: US minLength: 1 type: type: string description: Type of address. enum: - RESIDENTAL_OR_HABITATION - RESIDENTAL - HABITATION - REGISTRATION - OTHER example: RESIDENTAL_OR_HABITATION required: - countryCode - type FatcaBirthInfo: type: object description: Birth details of a person. properties: birthDate: type: string format: date description: Date of birth. example: '1980-01-01' city: type: string description: City of birth. example: New York maxLength: 100 minLength: 0 citySubentity: type: string description: District of the city of birth. example: Manhattan maxLength: 100 minLength: 0 countryCode: type: string description: >- Country of birth, ISO 3166-1 alpha-2. Mutually exclusive with `formerCountryName`. example: US formerCountryName: type: string description: >- Only for a country of birth that no longer exists, e.g. the Soviet Union. Send it instead of `countryCode`. example: Soviet Union maxLength: 100 minLength: 0 FatcaOrganisationType: type: string description: Why an entity account holder is reportable. enum: - OWNER_DOCUMENTED_FFI_WITH_SPECIFIED_US_OWNERS - PASSIVE_NFFE_WITH_SUBSTANTIAL_US_OWNERS - NON_PARTICIPATING_FFI - SPECIFIED_US_PERSON - DIRECT_REPORTING_NFFE FatcaAddressFix: type: object description: An address split into its parts. Only `city` is required. properties: street: type: string description: Street name. example: 100 maxLength: 100 minLength: 0 buildingIdentifier: type: string description: Building number or name. example: 12 maxLength: 50 minLength: 0 suiteIdentifier: type: string description: Apartment or suite. example: 4B maxLength: 50 minLength: 0 floorIdentifier: type: string description: Floor. example: 3 maxLength: 50 minLength: 0 districtName: type: string description: District. example: Manhattan maxLength: 100 minLength: 0 pob: type: string description: Post office box. example: PO Box 1234 maxLength: 50 minLength: 0 postCode: type: string description: Postal code. example: 10001 maxLength: 50 minLength: 0 city: type: string description: City or town. example: New York maxLength: 100 minLength: 0 countrySubentity: type: string description: State, province or region. example: NY maxLength: 100 minLength: 0 required: - city examples: FatcaPostAccountsRequest: value: - accountNumber: LT601010012345678901 accountNumberType: IBAN balance: 12345.67 currency: USD closed: false accountHolder: individual: residenceCountryCodes: - US tins: - number: '123456789' issuedBy: US names: - firstName: John lastName: Smith addresses: - addressFix: street: 100 Main Street postCode: '10001' city: New York countryCode: US type: RESIDENTAL_OR_HABITATION payments: - type: INTEREST amount: 120 currency: USD - accountNumber: LT601010012345678902 accountNumberType: IBAN balance: 250000 currency: USD closed: false accountHolder: organisation: type: PASSIVE_NFFE_WITH_SUBSTANTIAL_US_OWNERS residenceCountryCodes: - LT tins: - number: '304123456' issuedBy: LT name: Example Holdings UAB addresses: - addressFree: Gedimino pr. 1, Vilnius countryCode: LT type: REGISTRATION substantialOwners: - individual: residenceCountryCodes: - US tins: - number: '123456789' issuedBy: US names: - firstName: John lastName: Smith addresses: - addressFix: street: 100 Main Street postCode: '10001' city: New York countryCode: US type: RESIDENTAL_OR_HABITATION payments: - type: DIVIDENDS amount: 3000 currency: USD FatcaPostAccounts201: value: - status: SUCCESS accountNumber: LT601010012345678901 errors: [] - status: SUCCESS accountNumber: LT601010012345678902 errors: [] FatcaPostAccounts207: value: - status: SUCCESS accountNumber: LT601010012345678901 errors: [] - status: FAILED accountNumber: LT601010012345678902 errors: - fields: - accountNumber message: Duplicate account number 'LT601010012345678902' FatcaPostAccounts400: value: - status: FAILED accountNumber: LT601010012345678902 errors: - fields: - accountNumber message: Duplicate account number 'LT601010012345678902' securitySchemes: bearer-jwt: type: oauth2 flows: clientCredentials: tokenUrl: >- https://auth.sandbox.finventi.com/realms/sti-connector/protocol/openid-connect/token scopes: {} ````