Citi Funds Transfer Agency APIs

openapi: 3.1.0
info:
  title: Transfer Agency Account
  description: >
    The Transfer Agency Account API provides programmatic access to
    account-level data maintained on the  Transfer Agency register. It enables
    applications to retrieve up-to-date account static information,  supporting
    End‑of‑Day and near real-time data use cases. The API delivers a current
    snapshot of account  details and status, eliminating reliance on periodic
    file-based data delivery and manual reconciliation.

    Download our SDKs:

    * [Python
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=python&apiTitle=all&isClientSecReq=true)

    * [Java
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=java&apiTitle=all&isClientSecReq=true)

    * [.Net
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=dotnet&apiTitle=all&isClientSecReq=true)

    * [Ruby
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=ruby&apiTitle=all&isClientSecReq=true)

    * [NodeJS
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=nodejs&apiTitle=all&isClientSecReq=true)

    * [Go
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=go&apiTitle=all&isClientSecReq=true)

     * [CLI Tool
    SDK](https://developer.citi.com/sandboxApi/admin/v1/downloadZipFile?language=ccapi-cli&apiTitle=all&isClientSecReq=true)

    Note: You must be logged in to download the SDKs.
  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
paths:
  /v1/accounts/{fundManagerId}:
    get:
      tags:
        - Accounts
      summary: Access all fund accounts, including balances and status.
      description: Access all fund accounts, including balances and status.
      operationId: getAccounts
      parameters:
        - $ref: '#/components/parameters/Client-Id'
        - $ref: '#/components/parameters/Account-Id'
        - $ref: '#/components/parameters/Fund-Manager-Id'
        - $ref: '#/components/parameters/Account-Status'
        - $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-Account-Response'
              example:
                fundManagerId: FM123
                accounts:
                  - id: ACC789
                    jointAccountStatus: Primary
                    name: John Doe
                    firstName: John
                    middleName: M
                    lastName: Doe
                    status: Active
                    designation: Individual
                    amlStatus: Compliant
                    pep: 'No'
                    fullDealingRestrictionsIndicator: false
                    purchaseRestrictionsIndicator: false
                    redemptionRestrictionsIndicator: false
                    transferInRestrictionsIndicator: false
                    transferOutRestrictionsIndicator: false
                    exchangeInRestrictionsIndicator: false
                    exchangeOutRestrictionsIndicator: false
                    settlementRestrictionsIndicator: false
                    registerAddressLine1: 123 Main St
                    registerAddressLine2: Apt 4
                    registerAddressLine3: 'null'
                    registerAddressLine4: 'null'
                    registerAddressLine5: 'null'
                    registerAddressTown: Anytown
                    registerAddressPostCode: '12345'
                    registerAddressCountry: USA
                    correspondenceAddressLine1: 456 Oak Ave
                    correspondenceAddressLine2: 'null'
                    correspondenceAddressLine3: 'null'
                    correspondenceAddressLine4: 'null'
                    correspondenceAddressLine5: 'null'
                    correspondenceAddressTown: Springfield
                    correspondenceAddressPostCode: '67890'
                    correspondenceAddressCountry: USA
                    emailAddress: john.doe@example.com
                    activationDate: '2023-01-15'
                    deactivationDate: '2025-01-15'
                    dealerId: DL789
                    dealerName: Acme Investments
                    branchId: BR101
                    branchName: Main Branch
                    repId: RP202
                    repName: Jane Smith
                    dealerAddressLine1: 789 Pine Ln
                    dealerAddressLine2: 'null'
                    dealerAddressLine3: 'null'
                    dealerAddressLine4: 'null'
                    dealerAddressLine5: 'null'
                    dealerTown: Hometown
                    dealerPostCode: '54321'
                    dealerCountry: USA
                    nonDigitalInvestor: 'No'
                    investorIds:
                      - INV123
                      - INV456
        '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:
  parameters:
    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'
    Fund-Manager-Id:
      name: fundManagerId
      in: path
      required: true
      description: The unique identifier for Fund Manager.
      schema:
        type: string
      example: FM001
    Inverstor-Id:
      name: investorId
      in: query
      required: false
      description: The unique identifier for Investor.
      schema:
        type: string
    Inverstor-Status:
      name: investorStatus
      in: query
      required: false
      description: Indicated whether an investor is Active, Inactive or Closed.
      schema:
        type: string
        enum:
          - ACTIVE
          - INACTIVE
          - CLOSED
    Account-Id:
      name: accountId
      in: query
      description: The unique ID for a trading Account linked to an Investor.
      schema:
        type: string
    Account-Status:
      name: accountStatus
      in: query
      required: false
      description: Indicates if the account is Active, Inactive or Closed.
      schema:
        type: string
        enum:
          - ACTIVE
          - INACTIVE
          - CLOSED
    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
    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
    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
    Offset:
      name: offset
      in: query
      description: Offset records by a given number (optional).
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    Limit:
      name: limit
      in: query
      description: The maximum number of records to return.
      required: false
      schema:
        type: integer
        format: int32
        default: 5000
  headers:
    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
    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
  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'
  examples:
    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
    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
    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
    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
    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
  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
    Account:
      title: Account
      type: object
      properties:
        id:
          title: Account ID
          type: string
          description: Provide the unique ID for a trading Account linked to an Investor.
          maxLength: 35
        jointAccountStatus:
          title: Joint Account Status
          type: string
          description: Indicates if the investor is primary / secondary owner.
          enum:
            - Primary
            - Secondary
        name:
          title: Account Name
          type: string
          description: >-
            A party refers to an individual, institution, or entity involved in
            a financial transaction, agreement, or contractual relationship. In
            banking, parties can include account holders, investors, banks, fund
            managers, and regulatory bodies. Each party has defined roles,
            rights, and responsibilities.
          minLength: 1
          maxLength: 256
        firstName:
          title: Account First Name
          type: string
          description: The individual investor's first name(s).
          minLength: 1
          maxLength: 32
        middleName:
          title: Account Middle Name
          type: string
          description: The individual investor's middle name.
          minLength: 1
          maxLength: 32
        lastName:
          title: Account Last Name
          type: string
          description: The individual investor's surname.
          minLength: 1
          maxLength: 32
        status:
          title: Account Status
          type: string
          description: Indicates if the account is Active, Inactive or Closed.
          enum:
            - Active
            - InActive
            - Closed
        designation:
          title: Account Designation
          type: string
        amlStatus:
          title: Account AML Status
          type: string
          description: Indicates if the Account is AML compliant or not.
          enum:
            - Compliant
            - Non-Compliant
        pep:
          title: PEP
          type: string
          description: Indicates whether individual is a Politically Exposed Person or not.
          minLength: 1
          maxLength: 32
        fullDealingRestrictionsIndicator:
          title: Full Dealing Restrictions Indicator
          description: >-
            The unique identifier of the Full Dealing Restriction Type.
            Indicates if all transactions are blocked for an Investor across for
            the account.
          type: boolean
        purchaseRestrictionsIndicator:
          title: Purchase Restrictions Indicator
          type: boolean
          description: >-
            The unique identifier of the Purchase Restriction Type.Indicates if
            only purchase type transactions are blocked for the account.
        redemptionRestrictionsIndicator:
          title: Redemption Restrictions Indicator
          type: boolean
          description: >-
            The unique identifier of the Redemption Restriction Type.Indicates
            if only redemption type transactions are blocked for the account.
        transferInRestrictionsIndicator:
          title: Transfer In Restrictions Indicator
          type: boolean
          description: >-
            Indicates if only transfer in type transactions are blocked across
            all their accounts.
        transferOutRestrictionsIndicator:
          title: Transfer Out Restrictions Indicator
          type: boolean
          description: >-
            Indicates if only transfer out type transactions are blocked across
            all their accounts.
        exchangeInRestrictionsIndicator:
          title: Exchange In Restrictions Indicator
          type: boolean
          description: >-
            Indicates if only exchange in type transactions are blocked across
            all their accounts.
        exchangeOutRestrictionsIndicator:
          title: Exchange Restrictions Indicator
          type: boolean
          description: >-
            Indicates if only exchange out type transactions are blocked across
            all their accounts.
        settlementRestrictionsIndicator:
          title: Settlement Restrictions Indicator
          type: boolean
          description: >-
            The unique identifier of the Settlement Restriction Type. Indicates
            if only settlement type transactions are blocked for the account.
        registerAddressLine1:
          title: Account Register Address Line 1
          type: string
          description: Register Address Line 1.
          maxLength: 200
        registerAddressLine2:
          title: Account Register Address Line 2
          type: string
          description: Register Address Line 2.
          maxLength: 200
        registerAddressLine3:
          title: Account Register Address Line 3
          type: string
          description: Register Address Line 3.
          maxLength: 200
        registerAddressLine4:
          title: Account Register Address Line 4
          type: string
          description: Register Address Line 4.
          maxLength: 200
        registerAddressLine5:
          title: Account Register Address Line 5
          type: string
          description: Register Address Line 5.
          maxLength: 200
        registerAddressTown:
          title: Account Register Address Town
          type: string
          description: Register Address Town.
          maxLength: 200
        registerAddressPostCode:
          title: Account Register Address Post Code
          type: string
          description: Register Address Post Code.
          maxLength: 16
        registerAddressCountry:
          title: Account Register Address Country
          type: string
          description: Register Address Country, in ISO3166 alpha-3.
          maxLength: 32
        correspondenceAddressLine1:
          title: Account Correspondence Address Line 1
          type: string
          description: Correspondence Address Line 1.
          maxLength: 200
        correspondenceAddressLine2:
          title: Account Correspondence Address Line 2
          type: string
          description: Correspondence Address Line 2.
          maxLength: 200
        correspondenceAddressLine3:
          title: Account Correspondence Address Line 3
          type: string
          description: Correspondence Address Line 3.
          maxLength: 200
        correspondenceAddressLine4:
          title: Account Correspondence Address Line 4
          type: string
          description: Correspondence Address Line 4.
          maxLength: 200
        correspondenceAddressLine5:
          title: Account Correspondence Address Line 5
          type: string
          description: Correspondence Address Line 5.
          maxLength: 200
        correspondenceAddressTown:
          title: Account Correspondence Address Town
          type: string
          description: Correspondence Address Town.
          maxLength: 200
        correspondenceAddressPostCode:
          title: Account Correspondence Address Post Code
          type: string
          description: Correspondence Address Post Code.
          maxLength: 16
        correspondenceAddressCountry:
          title: Account Correspondence Address Country
          type: string
          description: Correspondence Address Country, in ISO3166 alpha-3.
          maxLength: 32
        emailAddress:
          title: Email Address
          type: string
          description: The investor's email address.
          maxLength: 256
        activationDate:
          title: Account Activation Date
          type: string
          format: date
          description: The Account activation date.
        deactivationDate:
          title: Account Deactivation Date
          type: string
          format: date
          description: The Account deactivation date.
        dealerId:
          title: Dealer ID
          type: string
          description: The Dealer ID linked to the Account.
          maxLength: 32
        dealerName:
          title: Dealer Name
          type: string
          description: >-
            Party Name is the official name of a person, organization, or
            institution that is a participant in a financial transaction. It is
            used to uniquely identify the party and ensure accurate
            communication and processing of financial messages.
          maxLength: 80
        branchId:
          title: Branch ID
          type: string
          description: The Branch ID linked to the Account.
          maxLength: 32
        branchName:
          title: Branch Name
          type: string
          description: >-
            Party Name is the official name of a person, organization, or
            institution that is a participant in a financial transaction. It is
            used to uniquely identify the party and ensure accurate
            communication and processing of financial messages.
          maxLength: 80
        repId:
          title: Rep ID
          type: string
          description: The Rep ID linked to the Account.
          maxLength: 32
        repName:
          title: Rep Name
          type: string
          description: Provide the name of the Rep.
          maxLength: 80
        dealerAddressLine1:
          title: Dealer Address Line 1
          description: Dealer Address Line 1.
          type: string
          maxLength: 200
        dealerAddressLine2:
          title: Dealer Address Line 2
          description: Dealer Address Line 2.
          type: string
          maxLength: 200
        dealerAddressLine3:
          title: Dealer Address Line 3
          description: Dealer Address Line 3.
          type: string
          maxLength: 200
        dealerAddressLine4:
          title: Dealer Address Line 4
          description: Dealer Address Line 4.
          type: string
          maxLength: 200
        dealerAddressLine5:
          title: Dealer Address Line 5
          description: Dealer Address Line 5.
          type: string
          maxLength: 200
        dealerTown:
          title: Dealer Town
          description: Dealer Address Town.
          type: string
          maxLength: 200
        dealerPostCode:
          title: Dealer Post Code
          description: Dealer Address Post Code.
          type: string
          maxLength: 16
        dealerCountry:
          title: Dealer Country
          description: Dealer Address Country, in ISO3166 alpha-3.
          type: string
          maxLength: 32
        nonDigitalInvestor:
          title: Non-Digital Investor
          description: Indicates if the Investor is non-digital.
          type: string
          maxLength: 32
        investorIds:
          title: Investor IDs
          description: Provides the unique identifier for the Investor
          type: array
          items:
            type: string
      additionalProperties: false
    Get-Account-Response:
      title: GetAccountsResponse
      type: object
      properties:
        fundManagerId:
          title: Fund Manager ID
          type: string
          description: Provides the unique identifier for Fund Manager
          maxLength: 32
        accounts:
          title: Accounts
          type: array
          items:
            $ref: '#/components/schemas/Account'
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Grant read-only access to Transfer Agency Funds apis
tags:
  - name: Accounts
    description: Operations related to Accounts