openapi: 3.2.0
info:
  title: Transfer Agency Holding Holdings API
  description: The Transfer Agency Holding API provides programmatic access to investor holding and balance data maintained on the Transfer Agency register.
  version: v2.0.0
servers:
- url: https://sit.b2b.api.icg.citi.com/citiconnect/sit5/iis/api/funds/transferagency
  description: dev gateway url
- url: https://sandbox.b2b.api.icg.citi.com/citiconnect/sb/iis/api/funds/transferagency
  description: sandbox url
- url: https://b2b.api.icg.citi.com/citiconnect/prod/iis/api/funds/transferagency
  description: production gateway url
tags:
- name: Holdings
  description: Operations related to Holdings
paths:
  /v1/holdings/{fundManagerId}:
    get:
      tags:
      - Holdings
      summary: Query current holdings across various funds and asset classes
      description: Query current holdings across various funds and asset classes.
      operationId: getAccountHoldings
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Trade-Date'
      - $ref: '#/components/parameters/Account-Id'
      - $ref: '#/components/parameters/Fund-Manager-Id'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          headers:
            x-request-id:
              $ref: '#/components/headers/x-request-id'
            pagination-metadata:
              $ref: '#/components/headers/pagination-metadata'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-Investor-Account-Holdings-Response'
              example:
                fundManagerId: FM123
                accountsHoldings:
                - accountId: ACCT123
                  holdings:
                  - fundCode: FC001
                    shareClassCode: SCC001
                    shareClassCurrency: USD
                    isin: US1234567890
                    cusip: '123456789'
                    sedol: B000000
                    shareBalanceAmount: 100.5
                    shareBalanceValue: 1500.75
                    valuationPrice: 15
                    tradeDate: '2023-01-15'
                    settledBalanceAmount: 100.5
                    estimatedBalanceAmount: 100.5
                    group1Units: 50.25
                    group2Units: 50.25
        '400':
          $ref: '#/components/responses/Bad-Request'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/Not-Found'
        '405':
          $ref: '#/components/responses/Method-Not-Allowed'
        '415':
          $ref: '#/components/responses/Unsupported-Media-Type'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
      security:
      - oAuth2:
        - /authenticationservices/v1
components:
  examples:
    Method-Not-Allowed-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: Method not supported
          action: please use valid http verb
          code: CC00001
    Unsupported-Media-Type-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: Media type not supported
          action: please use valid content-type in header
          code: CC00002
    Not-Found-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: Resource that you are searching is not found
          action: Please use valid resource details
          code: CC00006
    Bad-Request-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: path-param fundManagerId is mandatory and it cannot be empty
          action: please provide valid value for fundManagerId
          code: VC00010
    Internal-Server-Error-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: unable to serve your request at this moment
          action: Please refer to documentation provided or contact support team
          code: CC00004
    Unauthorized-Example:
      value:
        ref_id: 444d0f3f-4x55-7g99-8b2c-0cf2a921a5ab
        errors:
        - issue: User not authorized for this functionality
          action: please use valid credentials to access this functionality
          code: CC00007
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Unauthorized-Example:
              $ref: '#/components/examples/Unauthorized-Example'
    Not-Found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Not-Found-Example:
              $ref: '#/components/examples/Not-Found-Example'
    Unsupported-Media-Type:
      description: Unsupported Media Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Unsupported-Media-Type-Example:
              $ref: '#/components/examples/Unsupported-Media-Type-Example'
    Internal-Server-Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Internal-Server-Error-Example:
              $ref: '#/components/examples/Internal-Server-Error-Example'
    Method-Not-Allowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Method-Not-Allowed-Example:
              $ref: '#/components/examples/Method-Not-Allowed-Example'
    Bad-Request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Bad-Request-Example:
              $ref: '#/components/examples/Bad-Request-Example'
  schemas:
    Error-Response:
      type: object
      title: ErrorResponse
      xml:
        name: ErrorResponse
      properties:
        ref_id:
          type: string
          maxLength: 60
          description: Unique ID for the Transaction
          title: ref_id
          xml:
            name: RefId
        errors:
          type: array
          title: Error Detail
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Error-Detail'
    Error-Detail:
      type: object
      title: Error Detail
      xml:
        name: errors
      properties:
        issue:
          type: string
          maxLength: 150
          description: more details about the issue
          title: issue
          xml:
            name: Issue
        action:
          type: string
          maxLength: 150
          description: corrective action to be taken to resolve above issue
          title: action
          xml:
            name: Action
        code:
          type: string
          maxLength: 10
          description: unique code representing the issue
          title: code
          xml:
            name: Code
    Accounts-Holdings:
      title: AccountsHoldings
      type: object
      properties:
        accountId:
          title: Account ID
          type: string
          description: Provide the unique ID for a trading Account linked to an Investor.
          maxLength: 35
        holdings:
          title: Holdings
          type: array
          items:
            $ref: '#/components/schemas/Holdings-Response'
      additionalProperties: false
    Holdings-Response:
      title: HoldingsResponse
      type: object
      properties:
        fundCode:
          title: Fund Code
          type: string
          description: Fund Code identifier.
          maxLength: 35
        shareClassCode:
          title: Share Class Code
          type: string
          description: Share Class Code identifier.
          maxLength: 35
        shareClassCurrency:
          title: Share Class Currency
          type: string
          description: The Share Class currency, in ISO4217.
          maxLength: 32
        isin:
          title: ISIN
          type: string
          description: The Share Class ISIN - primary Share Class identifier.
          maxLength: 32
        cusip:
          title: CUSIP
          type: string
          description: The Share Class CUSIP.
          maxLength: 32
        sedol:
          title: SEDOL
          type: string
          description: The Share Class SEDOL.
          maxLength: 32
        shareBalanceAmount:
          title: Share Balance Amount
          type: number
          format: double
          description: The current shareholder share balance.
        shareBalanceValue:
          title: Share Balance Value
          type: number
          format: double
          description: The current shareholder share value.
        valuationPrice:
          title: Valuation Price
          type: number
          format: double
          description: The current Valuation Price.
        tradeDate:
          title: Trade Date
          type: string
          format: date
          description: The trade date the transaction actually received on the system. If a trade missed cut-off this date is the next available business date after the Booking Date.
        settledBalanceAmount:
          title: Settled Balance Amount
          type: number
          format: double
          description: The settled balance of the holding.
        estimatedBalanceAmount:
          title: Estimated Balance Amount
          type: number
          format: double
          description: The estimated balance of the holding e.g. the unsettled holding amount.
        group1Units:
          title: Group 1 Units
          type: number
          format: double
          description: The number of units that a shareholder holds that fall under the Group 1 category.
        group2Units:
          title: Group 2 Units
          type: number
          format: double
          description: The number of units that a shareholder holds that fall under the Group 2 category.
      additionalProperties: false
    Get-Investor-Account-Holdings-Response:
      title: GetInvestorAccountHoldingsResponse
      type: object
      properties:
        fundManagerId:
          title: Fund Manager ID
          type: string
          description: Provides the unique identifier for Fund Manager
          maxLength: 32
        accountsHoldings:
          title: Accounts Holdings
          type: array
          items:
            $ref: '#/components/schemas/Accounts-Holdings'
      additionalProperties: false
  parameters:
    Fund-Manager-Id:
      name: fundManagerId
      in: path
      required: true
      description: The unique identifier for Fund Manager.
      schema:
        type: string
      example: FM001
    Trade-Date:
      name: tradeDate
      in: query
      required: true
      description: The trade date the transaction actually received on the system. If a trade missed cut-off this date is the next available business date after the Booking Date. Date in ISO format(YYYY-MM-DD)
      schema:
        type: string
        format: date
    Offset:
      name: offset
      in: query
      description: Offset records by a given number (optional).
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    Account-Id:
      name: accountId
      in: query
      description: The unique ID for a trading Account linked to an Investor.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: The maximum number of records to return.
      required: false
      schema:
        type: integer
        format: int32
        default: 5000
    Client-Id:
      description: Your unique identification, the same one you use for OAuth token generation, was shared with you by Citi during the CitiConnect API integration.
      name: client_id
      in: query
      required: true
      schema:
        type: string
      example: '54563213246'
  headers:
    pagination-metadata:
      description: '<br> current_page: current page number<br> total_page: Total number of pages available for your request<br> page_size: Total number of records available in the current page<br> has_more: Any more messages or records expected'
      schema:
        type: string
        title: Pagination Metadata
        xml:
          name: paginationMetadata
        examples:
        - current_page: 2
          total_pages: 10
          page_size: 100
          has_more: true
    x-request-id:
      description: Unique system-generated reference number generated by Citi. Use this number when reporting an issue to a Citi representative in case of any discrepancy.
      schema:
        type: string
        maxLength: 36
        minLength: 1
        title: APIGEE GUID
        examples:
        - 6c29faa6-8e39-4829-b8ce-0ffa32c1a96c
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Grant read-only access to IIS Funds TA apis