openapi: 3.0.0
info:
  version: 1.0.0
  title: Statements API
  description: >
                The Statements API allows the consumer to pull financial account statements documents from API People Core.


servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/apipeople/statements-api/1.0.0

  
tags:
  - name: APIs
    description: A set of APIs to query and pull Financial accounts Statements

paths:
  /statements/search:
    post:
      summary: 'Search Available Statements'
      description: |
              This API looks for available Financial Accounts Statements given an Account Id & Account Type. The API Consumer can also filter by a date range.

              - A request with a `startDate`, and without an `endDate`, returns all the qualified statements with a date equal to and greater than the start date. 
              - A request with an `endDate`, and without a `startDate`, returns all the qualified statements with a date equal to and less than the end date.
              - A  request without a `startDate` or an  `endDate` returns all the qualified statements for the keys requested. 
                   
      operationId: 'searchStatements'
      parameters:
        - name: x-correlation-id
          in: header
          required: true
          description: A UUID value compliant with RFC 4122 used to identify an API Request. The value is echoed back in the response header. See [Authentication](/api/authentication/#correlation-id) for more details.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postSearchStatementsRequest'
      responses:
        '200':
          description: Successful Statements Retrieval Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postSearchStatementsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '409':
          description: | 
            Conflict.
              The API was unable to process the request due to business validation rules.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      errorDetails: 
                        allOf:
                          - $ref: '#/components/schemas/ErrorDetails'
                          - type: object
                            properties:                    
                              code:  
                                example: 409
                              reason:  
                                example: "CONFLICT"
                              details:  
                                example: "Unauthorized Financial Account"
                                enum:
                                  - "Unauthorized Financial Account"
                                
        '500':
          description: API Internal Error.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      errorDetails: 
                        allOf:
                          - $ref: '#/components/schemas/ErrorDetails'
                          - type: object
                            properties:                    
                              code:  
                                example: 500
                              reason:  
                                example: "INTERNAL_SERVER_ERROR"
                              details:  
                                example: "Recipe function call failed (id: 61178786, job_id: j-AT6HQhcH-YGmr8a): Statement ID is not valid at line: 19092"
      security:
        - oAuth2_ClientCredentials: []
      tags:
        - APIs
  /statements/{statementId}:
    get:
      summary: 'Retrieve Statement'
      description: >
        This API retrieves a financial account statement content encoded in base64 given a `statementId`
        
        :::warning Sizeable Financial Accounts
          Given underlying core systems where statements are stored, the pulling of big size financial accounts statements could cause this API to give errors.
        :::
        
      operationId: 'getStatement'
      parameters:
        - name: x-correlation-id
          in: header
          required: true
          description: A UUID value compliant with RFC 4122 used to identify an API Request. The value is echoed back in the response header. See [Authentication](/api/authentication/#correlation-id) for more details.
          schema:
            type: string
        - name: statementId
          in: path
          required: true
          description: Statement Id
          example: 1007769
          schema:
            type: string
        - name: includeImages
          in: query
          required: true            
          description: Whether the financial account statement should include images or not.
          example: true
          schema:
            type: boolean           
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      responses:
        '200':
          description: Successful statement retrieval response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getStatementResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '409':
          description: | 
            Conflict.
              The API was unable to process the request due to business validation rules
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      errorDetails: 
                        allOf:
                          - $ref: '#/components/schemas/ErrorDetails'
                          - type: object
                            properties:                    
                              code:  
                                example: 409
                              reason:  
                                example: "CONFLICT"
                              details:  
                                example: "Unauthorized Financial Account"
                                enum:
                                  - "Unauthorized Financial Account"                               
        '500':
          description: API Internal Error.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - type: object
                    properties:
                      errorDetails: 
                        allOf:
                          - $ref: '#/components/schemas/ErrorDetails'
                          - type: object
                            properties:                    
                              code:  
                                example: 500
                              reason:  
                                example: "INTERNAL_SERVER_ERROR"
                              details:  
                                example: "Recipe function call failed (id: 61178786, job_id: j-AT6HQhcH-YGmr8a): Bank Routing Number is not valid at line: 19092"
      security:
        - oAuth2_ClientCredentials: []
      tags:
        - APIs

components:
  securitySchemes:
    oAuth2_ClientCredentials:
      type: oauth2
      description: OAuth 2 [Client Credentials Flow](https://docs.workato.com/api-mgmt/oauth2.html#how-to-setup-oauth-2-0)
      flows: 
        clientCredentials: 
          tokenUrl: https://apim.workato.com/oauth2/token
          scopes: {} # Scopes not used in v1
      
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  errorDetails: 
                    allOf:
                      - $ref: '#/components/schemas/ErrorDetails'
                      - type: object
                        properties:                    
                          code:  
                            example: 400
                          reason:  
                            example: BAD_REQUEST
                          details:  
                            example: Please verify input parameters.
    '401':
      description: |
        Unauthorized.

          :::info 401 errors
          There are two different error schemas for 401 errors, one when the API credentials sent are wrong or invalid and another one when the API credentials are valid but the operation is prohibited for the consumer.
          :::
          
      content:
        application/json:
          schema:
            oneOf:
              - allOf:
                - $ref: '#/components/schemas/Error'
                - type: object
                  properties:
                    errorDetails: 
                      allOf:
                        - $ref: '#/components/schemas/ErrorDetails'
                        - type: object
                          properties:                    
                            code:  
                              example: 401
                            reason:  
                              example: UNAUTHORIZED
                            details:  
                              example: Permission denied.
              - type: object
                properties:
                  error: 
                    type: string
                    example: Access to this API has been disallowed            
    '500':
      description: API Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
            
  parameters:
    xCorrelationId:
      name: x-correlation-id
      in: header
      required: true
      description: A UUID value compliant with RFC 4122 used to identify an API Request. The value is echoed back in the response header. See [Authentication](/api/authentication/#correlation-id) for more details.
      schema:
        type: string
        minLength: 36
        maxLength: 36
    xTimestamp:
      name: x-timestamp
      in: header
      required: true
      description: |
        The timestamp used to support the message signature. Should contain only numbers.
        
          :::warning  Rejected Timestamps
          Requests with timestamp > 5min will be rejected
          :::
        
      schema:
        type: string
        example: "1746197323"
    xSignature:
      name: x-signature
      in: header
      required: true
      description: |
        Payload signature used by the API Client to validate message authenticity. Signature is calculated via **HMAC SHA256** algorithm and is composed by: 
        
            -`HTTP_VERB + HTTP_URL + PAYLOAD + TIMESTAMP`.
            
        The key will be provided to API Consumer
      schema:
        type: string
        minLength: 64
        maxLength: 64

  #############################
  # API Pagination Parameters #
  #############################
    limit:
      name: limit
      in: query
      required: false            
      description: The maximum number of bytes to return in each response. The number of bytes MUST be a multiple of 3.  
      example: 1007769
      schema:
        type: integer
        maximum: 57671680
        default: 57671679
    offset:
      name: offset
      in: query
      required: false            
      description: Allows the call to understand where the previous call left off when returning multiple records and allowing a subsequent call to retrieve more records.
      example: 1007769
      schema:
        type: integer
        maximum: 57671680
        default: 0

########################
## Schemas of Objects
########################
  schemas:
    postSearchStatementsRequest: 
      type: object
      properties:
        accountId:
          type: string
          description: Financial Account Id    
        accountType:
          type: string
          enum:
            - D
            - S
          description: Financial Account Type    
        startDate:
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          format: date
          type: string
          description: Start date to look statements from.  
        endDate:
          pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
          format: date
          type: string
          description: End date to look statements to.
          
    postSearchStatementsResponse:
      description: JSON Payload for Statements lookup response.
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              id:
                description: Unique identifier for a financial account statement.
                type: string
                example: 1033013
              date:
                pattern: /([0-9]{4})-(?:[0-9]{2})-([0-9]{2})/
                format: date
                type: string
                example: "2025-06-30"
                description: Statement Date
              pageCount:
                description: The count of pages within a statement.
                type: string
                example: 2
              enclosuresCount:
                description: The count of enclosures within a statement.
                type: string
                example: 2  
    
    getStatementResponse:
      description: JSON Payload for a statement retrieval.
      type: object
      properties:
        id:
          description: Unique identifier for a financial account statement.
          type: string
          example: 1033013
        content:
          description: Base64 content.
          type: string
          example: "dGVzdHRlc3R0ZXN0dGVzdHRlc3R0ZXN0dGVzdHRlc3R0ZXN0dGVzdHRlc3R0ZXN0dGVzdHRlc3R0ZXN0dGVzdHRlc3R0ZXN0"
        totalBytes:
          type: string
          example: 1033013
          description: The size of a document in bytes
        pagination:
          $ref: '#/components/schemas/paginationResponse'
  ##############################################
  # API Standard Pagination Response DataModel #
  ##############################################
    paginationResponse:
      type: object
      properties:
        moreResults:
          description: Indicates if there is more content that could be returned from a subsequent call.
          type: boolean
        offset:
          description: Allows the next call to understand where it left off when returning multiple records and allowing a subsequent call to retrieve more records.
          type: string
          example: 1007769
  ################################
  # API Standard Error DataModel #
  ################################
    Error:
      required:
      - apiName
      - version
      - correlationId
      - timestamp
      - errorDetails
      properties:
        apiName:
          type: string
          example: Statements API
        version:
          type: string
          example: v1
        correlationId:
          type: string
          example: 679751e0-36ba-49a1-b992-599c75beec66
        timestamp:
          type: string
          example: "2025-06-05T10:12:43.642286-07:00"
        errorDetails:
          type: object
          properties:
            code:
              type: string
            reason:
              type: string
            details:
              type: string
    ErrorDetails:
      type: object
      properties:
        code:
          type: string
          description: HTTP standard error code
        reason:
          type: string
          description: Integration error identification code
        details:
          type: string
          description: Error descriptive description