Citi Transactions API

openapi: 3.2.0
info:
  title: Transfer Agency Transactions API
  description: The Transfer Agency Transactions API provides programmatic access to transaction activity recorded 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: Transactions
  description: Operations related to Transactions
paths:
  /v1/transactions/{fundManagerId}:
    get:
      tags:
      - Transactions
      summary: Obtain detailed records of all fund transactions, including type, date, and…
      description: Obtain detailed records of all fund transactions, including type, date, and value.
      operationId: getTransactions
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Account-Id'
      - $ref: '#/components/parameters/From-Trade-Date'
      - $ref: '#/components/parameters/To-Trade-Date'
      - $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-Transactions-Response'
              example:
                fundManagerId: FM123
                accountsTransactions:
                - accountId: ACC456
                  transactions:
                  - fundCode: FC789
                    shareClassCode: SCC012
                    shareClassName: ShareClassA
                    isin: US1234567890
                    cusip: '123456789'
                    sedol: B123456
                    transactionType: Purchase
                    tradeDate: '2023-01-15'
                    actualSettlementDate: '2023-01-20'
                    contractualSettlementDate: '2023-01-29'
                    reconciliationDate: '2023-05-15'
                    bookingDate: '2023-01-15T00:00:00Z'
                    dealerId: DLR789
                    branchId: BRN012
                    repId: REP456
                    transactionId: TXN789
                    transactionStatus: Rejected
                    transactionRejectReason: Invalid Data
                    sourceTransactionId: STXN123
                    transactionFailureReason: System Error
                    orderReference: ORD123
                    shareAmount: 100.5
                    dealPrice: 10.25
                    grossAmount: 1025
                    netAmount: 1020
                    feeOrLoadAmount: 5
                    dealerLoadAmount: 2.5
                    fundLoadAmount: 2.5
                    adlAmount: 0.5
                    brokerCredit: 1
                    taxAmount: 2
                    transactionReceivingMediumType: File
                    largeDealIndicator: true
                    transactionCurrency: USD
                    settlementCurrency: USD
                    settlementFxRate: 1
                    inSpecieTransferFlag: false
        '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:
  schemas:
    Transactions-Response:
      title: TransactionsResponse
      type: object
      properties:
        fundCode:
          title: Fund Code
          type: string
          description: The unique identifier for a Fund.
          maxLength: 35
        shareClassCode:
          title: Share Class Code
          type: string
          description: The unique identifier for the Share Class.
          maxLength: 32
        shareClassName:
          title: Share Class Name
          type: string
          description: The long form Shareclass name.
          maxLength: 32
        isin:
          title: ISIN
          type: string
          description: The Shareclass ISIN - primary shareclass identifier.
          maxLength: 32
        cusip:
          title: CUSIP
          type: string
          description: The Shareclass CUSIP.
          maxLength: 32
        sedol:
          title: SEDOL
          type: string
          description: The Shareclass SEDOL.
          maxLength: 32
        transactionType:
          title: Transaction Type
          type: string
          description: The unique identifier of the Transaction Type.
          maxLength: 32
        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.
        actualSettlementDate:
          title: Actual Settlement Date
          type: string
          format: date
          description: The date the transaction actually settled on.
        contractualSettlementDate:
          title: Contractual Settlement Date
          type: string
          format: date
          description: The expected date the transaction is due to settle on.
        reconciliationDate:
          title: Reconciliation Date
          type: string
          format: date
          description: The date on which the trade was reconciled for cash.
        bookingDate:
          title: Booking Date
          type: string
          format: date-time
          description: The date / time the transaction was booked. ISO UTC Date time format (YYYY-MM-DDThh:mm:ssZ).
        dealerId:
          title: Dealer ID
          type: string
          description: The Dealer ID linked to the transaction.
          maxLength: 32
        branchId:
          title: Branch ID
          type: string
          description: The Branch ID linked to the transaction.
          maxLength: 32
        repId:
          title: Rep ID
          type: string
          description: The Rep ID linked to the transaction.
          maxLength: 32
        transactionId:
          title: Transaction Id
          type: string
          description: Citi system generated transaction ID.
          maxLength: 32
        transactionStatus:
          title: Transaction Status
          type: string
          description: The status of the transaction i.e. processed, rejected, etc.
          maxLength: 32
        transactionRejectReason:
          title: Transaction Reject Reason
          type: string
          description: Transaction Reject Reason.
          maxLength: 256
        sourceTransactionId:
          title: Source Transaction ID
          type: string
          description: Unique Transaction fund Share Class ID (different for EXIN / EXOUT transactions).
          maxLength: 32
        transactionFailureReason:
          title: Transaction Failure Reason
          type: string
          description: Transaction Failure Reason.
          maxLength: 256
        orderReference:
          title: Order Reference
          type: string
          description: External order reference usually provided by the dealer for a trade.
          maxLength: 36
        shareAmount:
          title: Share Amount
          type: number
          description: The transaction share amount.
          format: double
        dealPrice:
          title: Deal Price
          description: The transaction price/NAV.
          type: number
          format: double
        grossAmount:
          title: Gross Amount
          description: The transaction gross amount.
          type: number
          format: double
        netAmount:
          title: Net Amount
          description: The transaction net amount.
          type: number
          format: double
        feeOrLoadAmount:
          title: Fee Or Load Amount
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        dealerLoadAmount:
          title: Dealer Load Amount
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        fundLoadAmount:
          title: Fund Load Amount
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        adlAmount:
          title: ADL Amount
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        brokerCredit:
          title: Broker Credit
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        taxAmount:
          title: Tax Amount
          description: The charge/deduction amount that has been applied to the trade.
          type: number
          format: double
        transactionReceivingMediumType:
          title: Transaction Receiving Medium Type
          description: The unique identifier of the Transaction Receiving Medium Type. The transaction medium i.e. how it was received into GTAS e.g. NSCC, 20022, Fax, etc.
          type: string
          enum:
          - File
          - Manual
          maxLength: 32
        largeDealIndicator:
          title: Large Deal Indicator
          description: Indicates if the transaction is to be flagged as a large deal or not.
          type: boolean
        transactionCurrency:
          title: Transaction Currency
          description: The currency of the transaction, in ISO4217. This is the shareclass currency.
          type: string
          maxLength: 32
        settlementCurrency:
          title: Settlement Currency
          description: The settlement currency associated with the transaction, in ISO4217. This is the payment currency.
          type: string
          maxLength: 32
        settlementFxRate:
          title: Settlement FX Rate
          description: The FX rate associated with the transaction.
          type: number
          format: double
        inSpecieTransferFlag:
          title: In Specie Transfer Flag
          description: The In Specie Flag in a transaction typically indicates whether the transaction involves an in specie transfer.
          type: boolean
      additionalProperties: false
    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-Transactions:
      title: AccountsTransactions
      type: object
      properties:
        accountId:
          title: Account ID
          type: string
          description: Provide the unique ID for a trading Account linked to an Investor.
          maxLength: 35
        transactions:
          title: Transactions
          type: array
          items:
            $ref: '#/components/schemas/Transactions-Response'
      additionalProperties: false
    Get-Transactions-Response:
      title: GetTransactionsResponse
      type: object
      properties:
        fundManagerId:
          title: Fund Manager ID
          type: string
          description: Provides the unique identifier for Fund Manager
          maxLength: 32
        accountsTransactions:
          title: Accounts Transactions
          type: array
          items:
            $ref: '#/components/schemas/Accounts-Transactions'
      additionalProperties: false
  responses:
    Bad-Request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-Response'
          examples:
            Bad-Request-Example:
              $ref: '#/components/examples/Bad-Request-Example'
    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'
    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'
    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'
  parameters:
    To-Trade-Date:
      name: toTradeDate
      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
    Fund-Manager-Id:
      name: fundManagerId
      in: path
      required: true
      description: The unique identifier for Fund Manager.
      schema:
        type: string
      example: FM001
    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'
    From-Trade-Date:
      name: fromTradeDate
      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
    Account-Id:
      name: accountId
      in: query
      description: The unique ID for a trading Account linked to an Investor.
      schema:
        type: string
    Offset:
      name: offset
      in: query
      description: Offset records by a given number (optional).
      required: false
      schema:
        type: integer
        format: int32
        default: 0
  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
  examples:
    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
    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
    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
    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
    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
    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
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Grant read-only access to IIS Funds TA apis