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

# Update an account

> Amend an account by its account number.

<Note>
  In a submission this edits the not-yet-reported account in place. In a correction it amends the already-reported account; amending an account the tax authority has never seen is rejected, so add new accounts with [POST](/regulatory/rrc/api/fatca/push-accounts) instead.
</Note>


## OpenAPI

````yaml put /reports/fatca/v1/submissions/{submissionId}/accounts/{accountNumber}
openapi: 3.1.0
info:
  title: FATCA REST API
  description: >
    <p>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.</p>
  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/{accountNumber}:
    put:
      tags:
        - FATCA REST API
      summary: Update an account
      description: >-
        Updates an account by its account number. In a submission it edits the
        not-yet-reported account in place; in a correction it amends the
        already-reported account. Amending an account the tax authority has
        never seen is rejected, new accounts are added with POST.
      operationId: putAccount
      parameters:
        - name: submissionId
          in: path
          required: true
          schema:
            type: string
        - name: accountNumber
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FatcaAccount'
            examples:
              example:
                $ref: '#/components/examples/FatcaPutAccountRequest'
        required: true
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FatcaAccountResult'
              examples:
                example:
                  $ref: '#/components/examples/FatcaPutAccount200'
        '400':
          description: Account rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FatcaAccountResult'
              examples:
                example:
                  $ref: '#/components/examples/FatcaPutAccount400'
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:
    FatcaPutAccountRequest:
      value:
        accountNumber: LT601010012345678901
        accountNumberType: IBAN
        balance: 13000
        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
    FatcaPutAccount200:
      value:
        status: SUCCESS
        accountNumber: LT601010012345678901
        errors: []
    FatcaPutAccount400:
      value:
        status: FAILED
        accountNumber: LT601010012345678901
        errors:
          - fields:
              - accountNumber
            message: >-
              Account 'LT601010012345678901' is not in this submission; add it
              with POST
  securitySchemes:
    bearer-jwt:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.sandbox.finventi.com/realms/sti-connector/protocol/openid-connect/token
          scopes: {}

````