> ## 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/crs/v1/submissions/{submissionId}/accounts
openapi: 3.1.0
info:
  title: CRS REST API
  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: CRS REST API
    description: >-
      REST API for submitting and correcting CRS/DAC2 account data. Open a
      submission for a reporting year, push the reportable accounts under its
      id, then submit it to the tax authority.
paths:
  /reports/crs/v1/submissions/{submissionId}/accounts:
    post:
      tags:
        - CRS 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
        controlling persons 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/CrsAccount'
            example:
              - accountNumber: LT601010012345678901
                accountNumberType: IBAN
                balance: 15320.44
                currency: EUR
                accountType: DEPOSITORY_ACCOUNT
                openingType: PREEXISTING_ACCOUNT
                accountHolder:
                  selfCertification: PROVIDED
                  organisation:
                    type: REPORTABLE_PERSON
                    name: UAB Inventi
                    nameType: LEGAL
                    residenceCountryCodes:
                      - LV
                    tins:
                      - number: '39001011234'
                        issuedBy: LV
                    addresses:
                      - addressFree: Riga, Riga st. 1
                        countryCode: LV
                        type: REGISTRATION
                payments:
                  - type: INTEREST
                    amount: 142.75
                    currency: EUR
              - accountNumber: LT121000011101001000
                accountNumberType: IBAN
                balance: 248900
                currency: EUR
                accountType: CUSTODIAL_ACCOUNT
                openingType: NEW_ACCOUNT
                jointAccountHolders: 2
                accountHolder:
                  selfCertification: PROVIDED
                  organisation:
                    type: PASSIVE_NFE_WITH_REPORTABLE_CONTROLLING_PERSONS
                    name: UAB Inventi
                    nameType: LEGAL
                    residenceCountryCodes:
                      - LV
                    tins:
                      - number: '39001011234'
                        issuedBy: LV
                    addresses:
                      - addressFree: Riga, Riga st. 1
                        countryCode: LV
                        type: REGISTRATION
                controllingPersons:
                  - names:
                      - firstName: Jonas
                        lastName: Jonaitis
                    residenceCountryCodes:
                      - LV
                    tins:
                      - number: '39001011234'
                        issuedBy: LV
                    addresses:
                      - addressFree: Riga, Alberta st. 1
                        countryCode: LV
                        type: RESIDENTAL_OR_HABITATION
                    birthInfo:
                      birthDate: '1990-05-15'
                      city: Riga
                      countryCode: LV
                    roles:
                      - LEGAL_PERSON_CONTROL_BY_OWNERSHIP
                    selfCertification: PROVIDED
                payments:
                  - type: DIVIDENDS
                    amount: 5400
                    currency: EUR
                  - type: GROSS_PROCEEDS_OR_REDEMPTIONS
                    amount: 122000
                    currency: EUR
              - accountNumber: LT407300010002061111
                accountNumberType: IBAN
                balance: 0
                currency: EUR
                closed: true
                accountType: DEPOSITORY_ACCOUNT
                openingType: PREEXISTING_ACCOUNT
                accountHolder:
                  selfCertification: NOT_PROVIDED
                  individual:
                    names:
                      - firstName: Jonas
                        lastName: Jonaitis
                    residenceCountryCodes:
                      - LV
                    tins:
                      - number: '39001011234'
                        issuedBy: LV
                    addresses:
                      - addressFree: Riga, Riga st. 1
                        countryCode: LV
                        type: RESIDENTAL_OR_HABITATION
                    birthInfo:
                      birthDate: '1990-05-15'
                      city: Riga
                      countryCode: LV
        required: true
      responses:
        '201':
          description: All accounts saved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrsAccountResult'
              example:
                - status: SUCCESS
                  accountNumber: LT601010012345678901
                - status: SUCCESS
                  accountNumber: LT121000011101001000
                - status: SUCCESS
                  accountNumber: LT407300010002061111
        '207':
          description: Partial success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrsAccountResult'
              example:
                - status: SUCCESS
                  accountNumber: LT601010012345678901
                - status: FAILED
                  accountNumber: LT121000011101001000
                  errors:
                    - fields:
                        - accountNumber
                      message: Duplicate account number 'LT121000011101001000'
        '400':
          description: All failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrsAccountResult'
              example:
                - status: FAILED
                  accountNumber: LT601010012345678901
                  errors:
                    - message: Account holder address is missing
                    - message: Account holder name is missing or invalid
                - status: FAILED
                  accountNumber: LT121000011101001000
                  errors:
                    - message: >-
                        Organisation whose account holder type is not
                        PASSIVE_NFE_WITH_REPORTABLE_CONTROLLING_PERSONS cannot
                        have controlling person
components:
  schemas:
    CrsAccount:
      type: object
      description: >-
        A reportable financial account. Push the account as it stands, with its
        holder and any controlling persons 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 or value at the end of the reporting year. Must be 0 when
            account is `closed`.
          example: 12345.67
        currency:
          type: string
          description: Currency the balance is denominated in, ISO 4217
          example: EUR
          minLength: 1
        closed:
          type: boolean
          default: false
          description: The account was closed during the reporting year
        dormant:
          type: boolean
          default: false
          description: The account is dormant
        undocumented:
          type: boolean
          default: false
          description: The account is undocumented
        accountHolder:
          $ref: '#/components/schemas/CrsAccountHolder'
          description: The reportable holder of the account.
        controllingPersons:
          type: array
          description: >-
            Controlling persons of a passive non-financial entity holder.
            Required when the holder is an organisation of type
            `PASSIVE_NFE_WITH_REPORTABLE_CONTROLLING_PERSONS`, and not accepted
            otherwise.
          items:
            $ref: '#/components/schemas/CrsControllingPerson'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/CrsPayment'
          maxItems: 4
          minItems: 0
        accountType:
          $ref: '#/components/schemas/CrsFinancialAccountType'
          description: Type of financial account maintained for the holder.
          example: DEPOSITORY_ACCOUNT
        openingType:
          $ref: '#/components/schemas/CrsAccountOpeningType'
          description: >-
            Whether the account is a new or a pre-existing account, which
            decides the due diligence procedure that applied to it.
          example: PREEXISTING_ACCOUNT
        jointAccountHolders:
          type: integer
          format: int32
          description: >-
            Number of joint account holders. Send it only where the account is
            jointly held.
          example: 2
          maximum: 200
          minimum: 1
      required:
        - accountHolder
        - accountNumber
        - accountNumberType
        - accountType
        - balance
        - currency
        - openingType
    CrsAccountResult:
      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
          example: LT601010012345678901
        errors:
          type: array
          description: Why the account was rejected. Empty when the account was accepted.
          items:
            $ref: '#/components/schemas/FieldError'
      required:
        - errors
        - status
    CrsAccountHolder:
      type: object
      description: >-
        A holder of the account. Supply exactly one of `individual` or
        `organisation`.
      properties:
        individual:
          $ref: '#/components/schemas/CrsIndividual'
        organisation:
          $ref: '#/components/schemas/CrsOrganisation'
        selfCertification:
          $ref: '#/components/schemas/CrsSelfCertification'
          description: >-
            Whether the holder provided a valid self-certification. Required for
            both an individual and an entity holder.
          example: PROVIDED
        equityInterestTypes:
          type: array
          description: >-
            Roles by which the holder holds an equity interest in an investment
            entity that is a legal arrangement. Send them only where the holder
            is such an equity interest holder; a holder may hold several.
          items:
            $ref: '#/components/schemas/CrsEquityInterestType'
      required:
        - selfCertification
    CrsControllingPerson:
      type: object
      description: A controlling person of an passive non-financial entity holder.
      properties:
        residenceCountryCodes:
          type: array
          description: >-
            Every jurisdiction the person is tax resident in, ISO 3166-1
            alpha-2.
          example:
            - LV
          items:
            type: string
          maxItems: 2147483647
          minItems: 1
        tins:
          type: array
          description: Tax identification numbers.
          items:
            $ref: '#/components/schemas/CrsTin'
          maxItems: 2147483647
          minItems: 1
        names:
          type: array
          description: >-
            Names the person is reported under. Send several only where the
            person is known under different names.
          items:
            $ref: '#/components/schemas/CrsIndividualName'
          maxItems: 2147483647
          minItems: 1
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/CrsAddress'
          maxItems: 2147483647
          minItems: 1
        birthInfo:
          $ref: '#/components/schemas/CrsBirthInfo'
        roles:
          type: array
          description: Roles by which this person controls the entity.
          example:
            - LEGAL_PERSON_CONTROL_BY_OWNERSHIP
          items:
            type: string
            enum:
              - LEGAL_PERSON_CONTROL_BY_OWNERSHIP
              - LEGAL_PERSON_CONTROL_BY_OTHER_MEANS
              - LEGAL_PERSON_SENIOR_MANAGING_OFFICIAL
              - TRUST_SETTLOR
              - TRUST_TRUSTEE
              - TRUST_PROTECTOR
              - TRUST_BENEFICIARY
              - TRUST_OTHER
              - OTHER_ARRANGEMENT_SETTLOR_EQUIVALENT
              - OTHER_ARRANGEMENT_TRUSTEE_EQUIVALENT
              - OTHER_ARRANGEMENT_PROTECTOR_EQUIVALENT
              - OTHER_ARRANGEMENT_BENEFICIARY_EQUIVALENT
              - OTHER_ARRANGEMENT_OTHER_EQUIVALENT
              - NOT_REPORTED
          maxItems: 2147483647
          minItems: 1
        selfCertification:
          $ref: '#/components/schemas/CrsSelfCertification'
          description: Whether a valid self-certification was provided for this person.
          example: PROVIDED
      required:
        - addresses
        - names
        - residenceCountryCodes
        - roles
        - selfCertification
        - tins
    CrsPayment:
      type: object
      properties:
        type:
          type: string
          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: EUR
          minLength: 1
      required:
        - amount
        - currency
        - type
    CrsFinancialAccountType:
      type: string
      description: >-
        Type of financial account maintained for the holder. `NOT_REPORTED` is
        transitional, for data first reported under an earlier schema.
      enum:
        - DEPOSITORY_ACCOUNT
        - CUSTODIAL_ACCOUNT
        - CASH_VALUE_INSURANCE_OR_ANNUITY_CONTRACT
        - DEBT_OR_EQUITY_INTEREST_IN_INVESTMENT_ENTITY
        - NOT_REPORTED
    CrsAccountOpeningType:
      type: string
      description: Whether the account is new or pre-existing
      enum:
        - NEW_ACCOUNT
        - PREEXISTING_ACCOUNT
        - NOT_REPORTED
    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
    CrsIndividual:
      type: object
      description: A natural person holding the account
      properties:
        residenceCountryCodes:
          type: array
          description: >-
            Every jurisdiction the person is tax resident in, ISO 3166-1
            alpha-2.
          example:
            - LV
          items:
            type: string
          maxItems: 2147483647
          minItems: 1
        tins:
          type: array
          description: Tax identification numbers.
          items:
            $ref: '#/components/schemas/CrsTin'
          maxItems: 2147483647
          minItems: 1
        names:
          type: array
          description: Names the person is reported under.
          items:
            $ref: '#/components/schemas/CrsIndividualName'
          maxItems: 2147483647
          minItems: 1
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/CrsAddress'
          maxItems: 2147483647
          minItems: 1
        birthInfo:
          $ref: '#/components/schemas/CrsBirthInfo'
      required:
        - addresses
        - names
        - residenceCountryCodes
        - tins
    CrsOrganisation:
      type: object
      description: An entity account holder
      properties:
        type:
          $ref: '#/components/schemas/CrsOrganisationType'
        residenceCountryCodes:
          type: array
          description: Every jurisdiction the entity is tax resident in, ISO 3166-1 alpha-2
          example:
            - LV
          items:
            type: string
          maxItems: 2147483647
          minItems: 1
        tins:
          type: array
          description: Tax identification numbers.
          items:
            $ref: '#/components/schemas/CrsTin'
          maxItems: 2147483647
          minItems: 1
        name:
          type: string
          description: Name of the entity
          example: UAB Inventi
          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/CrsAddress'
          maxItems: 2147483647
          minItems: 1
      required:
        - addresses
        - name
        - residenceCountryCodes
        - tins
        - type
    CrsSelfCertification:
      type: string
      description: Whether a valid self-certification was provided
      enum:
        - PROVIDED
        - NOT_PROVIDED
        - NOT_REPORTED
    CrsEquityInterestType:
      type: string
      description: >-
        Role by which an equity interest is held in an investment entity that is
        a legal arrangement
      enum:
        - TRUST_SETTLOR
        - TRUST_TRUSTEE
        - TRUST_PROTECTOR
        - TRUST_BENEFICIARY
        - TRUST_OTHER
        - OTHER_ARRANGEMENT_SETTLOR_EQUIVALENT
        - OTHER_ARRANGEMENT_TRUSTEE_EQUIVALENT
        - OTHER_ARRANGEMENT_PROTECTOR_EQUIVALENT
        - OTHER_ARRANGEMENT_BENEFICIARY_EQUIVALENT
        - OTHER_ARRANGEMENT_OTHER_EQUIVALENT
    CrsTin:
      type: object
      description: Taxpayer identification number
      properties:
        number:
          type: string
          description: >-
            Taxpayer identification number. Where the institution was unable to
            obtain one, report the value `000000000`.
          example: 39001011234
          maxLength: 200
          minLength: 0
        issuedBy:
          type: string
          description: Jurisdiction that issued the number, ISO 3166-1 alpha-2.
          example: LV
          minLength: 1
      required:
        - issuedBy
        - number
    CrsIndividualName:
      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: Jonas
          maxLength: 200
          minLength: 0
        middleNames:
          type: array
          example:
            - Petras
          items:
            type: string
        lastName:
          type: string
          example: Jonaitis
          maxLength: 200
          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: AT_BIRTH
      required:
        - firstName
        - lastName
    CrsAddress:
      type: object
      description: Address of a holder or controlling person
      properties:
        addressFree:
          type: string
          description: Address as free text
          example: Riga, Riga st. 1
          maxLength: 4000
          minLength: 0
        countryCode:
          type: string
          description: Country of the address, ISO 3166-1 alpha-2
          example: LV
          minLength: 1
        type:
          type: string
          description: Type of address.
          enum:
            - RESIDENTAL_OR_HABITATION
            - RESIDENTAL
            - HABITATION
            - REGISTRATION
            - OTHER
          example: RESIDENTAL_OR_HABITATION
      required:
        - addressFree
        - countryCode
        - type
    CrsBirthInfo:
      type: object
      description: >-
        Birth information. Fields `city` and country are reported as a pair:
        send `city` with exactly one of `countryCode` or `formerCountryName`, or
        send neither.
      properties:
        birthDate:
          type: string
          format: date
          description: Date of birth
          example: '1980-01-01'
        city:
          type: string
          description: City of birth
          example: Berlin
          maxLength: 200
          minLength: 0
        citySubentity:
          type: string
          description: District or region of the city of birth.
          example: Mitte
          maxLength: 200
          minLength: 0
        countryCode:
          type: string
          description: >-
            Country of birth, ISO 3166-1 alpha-2. Mutually exclusive with
            `formerCountryName`.
          example: LV
        formerCountryName:
          type: string
          description: >-
            Name of the country of birth where it no longer exists and so has no
            country code. Mutually exclusive with `countryCode`.
          example: Soviet Union
          maxLength: 200
          minLength: 0
    CrsOrganisationType:
      type: string
      description: Type of reportable entity the account holder is
      enum:
        - PASSIVE_NFE_WITH_REPORTABLE_CONTROLLING_PERSONS
        - REPORTABLE_PERSON
        - PASSIVE_NFE_THAT_IS_REPORTABLE_PERSON
      example: REPORTABLE_PERSON
  securitySchemes:
    bearer-jwt:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: >-
            https://auth.sandbox.finventi.com/realms/sti-connector/protocol/openid-connect/token
          scopes: {}

````