openapi: 3.2.0
info:
  title: Statements Retriever Statements List API
  description: Enables a secure view of customer statements
  version: '1.0'
tags:
- name: statements-list
  description: Returns list of statements
paths:
  /statement/accounts/{acctId}:
    summary: GET Statements list
    description: This endpoint get list of Statements
    get:
      tags:
      - statements-list
      summary: List statements for an account
      description: Retrieve all statements for a specific account
      operationId: listStatements
      parameters:
      - name: acctId
        in: path
        description: Account identifier
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
      - name: fromDate
        in: query
        description: It is lower limit of duration for which user wants to retrieve documents.
        required: false
        deprecated: false
        schema:
          type: string
          maxLength: 10
          minLength: 10
          pattern: ^[0-9\-]{10}$
        example: '2020-08-08'
      - name: toDate
        in: query
        description: It is upper limit of duration for which user wants to retrive documents.
        required: false
        deprecated: false
        schema:
          type: string
          maxLength: 10
          minLength: 10
          pattern: ^[0-9\-]{10}$
        example: '2020-12-31'
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/StatementsResponseBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      deprecated: false
components:
  schemas:
    ErrorResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'An API error response.

        '
      properties:
        meta:
          type: object
          additionalProperties: true
          description: Contains Non-standard meta information
        errors:
          type: array
          description: 'Contains one or more error messages and is mutually exclusive with the data item.

            This will not be returned in success scenarios.

            '
          items:
            $ref: '#/components/schemas/ErrorType'
          maxItems: 50
          minItems: 0
      nullable: false
    StatementsListResponseBody:
      type: object
      additionalProperties: false
      deprecated: false
      description: Statements List Response
      properties:
        statements:
          $ref: '#/components/schemas/StatementsListBody'
      required:
      - statements
    ErrorType:
      type: object
      additionalProperties: true
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 9709-4675-2456-7801
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9\-]{1,50}$
        code:
          type: string
          description: Machine readable, unique code of the message related to particular case within operation execution.
          example: ACCOUNT_NUMBER_NOT_FOUND
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        title:
          type: string
          description: Short description of the error. Not for displaying purposes.
          example: The authorization credentials required for this request are invalid.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
        detail:
          type: string
          description: Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,.']{1,250}$
        meta:
          type: object
          additionalProperties: true
          description: Object containing non-standard meta-information about the error.
      required:
      - code
      - id
      - title
    StatementsListBody:
      type: array
      additionalProperties: false
      deprecated: false
      description: Statements List
      items:
        $ref: '#/components/schemas/Statements'
      maxItems: 999
      minItems: 0
    StatementsResponseObjectBody:
      type: object
      additionalProperties: false
      deprecated: false
      description: Letters List Response
      properties:
        id:
          type: string
          example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        type:
          type: string
          example: statements
          maxLength: 10
          minLength: 10
          pattern: ^[a-zA-Z]{10}$
        attributes:
          $ref: '#/components/schemas/StatementsListResponseBody'
      nullable: false
    Statements:
      type: object
      additionalProperties: false
      deprecated: false
      description: The document details list data
      properties:
        statementDate:
          type: string
          example: '2021-05-11'
          maxLength: 10
          minLength: 10
          pattern: ^[0-9\-]{10}$
        statementReference:
          type: string
          example: Tmpaak5UWm1OVEU1WXpNeU9EZ3habVE1TldKa05qZGhMRUZCUkZWVk9VRTVWVE5NTXpCbE5GWkJSa1pETTBkVVUxRTBNMGMwTVVrMVVFcE1UVTFTTUZKRlVrcFBSVWhRUVV0S1IwcFE6c3RhdGVtZW50
          maxLength: 999
          minLength: 1
          pattern: ^[A-Za-z0-9/=_.-]{1,999}$
        accountId:
          type: string
          example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      nullable: false
    StatementsResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: Statement List Response
      properties:
        data:
          $ref: '#/components/schemas/StatementsResponseObjectBody'
      nullable: true
  responses:
    BadRequest:
      description: "The request could not be understood by the server due to malformed \nsyntax. The client SHOULD NOT repeat the request without \nmodifications.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-400-bad-request:
              $ref: '#/components/examples/example-error-400-bad-request'
    InternalServerError:
      description: "Server encountered an error processing request. This should not \nhappen normally, but it is a generic error message, given when \nno more specific message is suitable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-500:
              $ref: '#/components/examples/example-error-500'
    StatementsResponseBody:
      description: Document Details Response
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatementsResponseType'
          examples:
            StatementListResponse:
              $ref: '#/components/examples/StatementListResponse'
    ServiceUnavailable:
      description: 'Service Unavailable

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-503:
              $ref: '#/components/examples/example-error-503'
    NotFound:
      description: 'delivery not found, or delivery did not contain any articles

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-404:
              $ref: '#/components/examples/example-error-404'
    Unauthorized:
      description: 'The user could not be authenticated for this request.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-401:
              $ref: '#/components/examples/example-error-401'
  examples:
    StatementListResponse:
      value:
        data:
          id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
          type: STATEMENTS
          attributes:
            statements:
            - statementDate: '2025-05-19'
              statementReference: TmpneVl6WXhNV1UyTWpsak9USTJabVZtT0RnNVlURmxMRVpRVmtkQ05EUTBTVkZJUVVwbE1GTkxTVWxKVkZSUU5VVkVTRWMwTVVsU1RVeE5UMUZETURFeE9VbzJTak14TjB4UU5FcFI6c3RhdGVtZW50
              accountId: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
    example-error-500:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error.
    example-error-401:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: AUTHENTICATION_ERROR
          title: The user could not be authenticated for this request.
    example-error-503:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
    example-error-404:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found.
    example-error-400-bad-request:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: BAD_REQUEST
          title: The request is invalid or not properly formed.
  headers:
    Cache-Control:
      description: GIS mandatory response header. This is added by the Cognac sidecar.
      schema:
        type: string
        default: no-cache, no-store, must-revalidate
        deprecated: false
        example: no-cache, no-store, must-revalidate
        maxLength: 35
        minLength: 35
        pattern: ^no-cache, no-store, must-revalidate$
        nullable: false
  securitySchemes:
    ExternalTiaaUsCCAuth:
      type: oauth2
      description: OAuth2.0 Client Credentials Grant authentication using TIAA-US for external APIs
      flows:
        clientCredentials:
          tokenUrl: https://token.tiaa-dev.us.barclays.intranet:8443/as/token.oauth2
          scopes:
            read: read only
            write: write only