Citi Investors API

openapi: 3.2.0
info:
  title: Transfer Agency Investor Investors API
  description: The Transfer Agency Investor API provides programmatic access to investor 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: Investors
  description: Operations related to Investors
paths:
  /v1/investors/{fundManagerId}:
    get:
      tags:
      - Investors
      summary: Retrieve comprehensive investor profiles and associated data
      description: Retrieve comprehensive investor profiles and associated data.
      operationId: getInvestors
      parameters:
      - $ref: '#/components/parameters/Client-Id'
      - $ref: '#/components/parameters/Inverstor-Status'
      - $ref: '#/components/parameters/Inverstor-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-Investors-Response'
              example:
                fundManagerId: FM001
                investors:
                - id: INV001
                  type: Institutional
                  name: Acme Investments
                  firstName: 'null'
                  middleName: 'null'
                  lastName: 'null'
                  title: 'null'
                  status: Active
                  registerAddressLine1: 123 Main Street
                  registerAddressLine2: Suite 400
                  registerAddressLine3: 'null'
                  registerAddressLine4: 'null'
                  registerAddressLine5: 'null'
                  registerAddressTown: Anytown
                  registerAddressPostCode: '12345'
                  registerAddressCountry: USA
                  correspondenceAddressLine1: 456 Oak Avenue
                  correspondenceAddressLine2: PO Box 789
                  correspondenceAddressLine3: 'null'
                  correspondenceAddressLine4: 'null'
                  correspondenceAddressLine5: 'null'
                  correspondenceAddressTown: Springfield
                  correspondenceAddressPostCode: '67890'
                  correspondenceAddressCountry: USA
                  emailAddress: info@acmeinvestments.com
                  amlStatus: Compliant
                  riskLevel: Medium
                  legalEntityType: Corporate
                  fullDealingRestrictionsIndicator: false
                  purchaseRestrictionsIndicator: false
                  redemptionRestrictionsIndicator: false
                  transferInRestrictionsIndicator: false
                  transferOutRestrictionsIndicator: false
                  exchangeInRestrictionsIndicator: false
                  exchangeOutRestrictionsIndicator: false
                  settlementRestrictionsIndicator: false
                  activationDate: '2023-01-15'
                  deactivationDate: '2025-01-15'
                  birthDate: '1990-01-01'
                  countryOfBirth: 'null'
                  cityOfBirth: 'null'
                  deceasedStatus: Alive
                  deathDate: '2026-12-12'
                  deathNotificationDate: '2026-12-12'
                  additionalSupportRequiredFlag: false
                  additionalSupportEffectiveDate: '2023-02-15'
                  additionalSupportIndicator: Deviation
                  countryOfTaxResidency: USA
                  crsClassification: Reportable Person
                  crsSelfCertReceived: true
                  crsPreExistingClient: true
                  crsUndocumented: false
                  crsDormantIndicator: false
                  gdprObfuscationStatus: Not Obfuscated
                  gdprObfuscationExclusion: 'No'
                  fatcaClassification: Active NFFE
                  fatcaSelfCertReceived: true
                  fatcaExempt: false
                  tin: '123456789'
                  giin: ABCDEFG.12345.XX.678
                  nonDigitalInvestor: 'No'
                  professionalFlag: 'Yes'
                  investorDecisionMakerCountry: USA
                  kycId: 123456
                  accountIds:
                  - ACC001
                  - ACC002
        '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:
    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
    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'
    Offset:
      name: offset
      in: query
      description: Offset records by a given number (optional).
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    Inverstor-Id:
      name: investorId
      in: query
      required: false
      description: The unique identifier for Investor.
      schema:
        type: string
  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'
  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
  schemas:
    Investor:
      title: Investor
      type: object
      properties:
        id:
          title: Investor ID
          description: Provides the unique identifier for Investor.
          type: string
          maxLength: 32
        type:
          title: Investor Type
          description: Indicates the Investor type i.e. Individual, Institutional.
          type: string
          maxLength: 32
          enum:
          - Individual
          - Institutional
        name:
          title: Investor Name
          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.
          type: string
          maxLength: 256
        firstName:
          title: Investor First Name
          description: The individual investor's first name(s).
          type: string
          maxLength: 32
        middleName:
          title: Investor Middle Name
          description: The individual investor's middle name.
          type: string
          maxLength: 32
        lastName:
          title: Investor Last Name
          description: The individual investor's surname.
          type: string
          maxLength: 32
        title:
          title: Title
          description: The individual investor's Title.
          type: string
          maxLength: 32
        status:
          title: Investor Status
          description: Indicated whether an investor is Active, Inactive or Closed.
          type: string
          enum:
          - Active
          - Inactive
          - Closed
        registerAddressLine1:
          title: Investor Register Address Line 1
          description: Register Address Line 1.
          type: string
          maxLength: 200
        registerAddressLine2:
          title: Investor Register Address Line 2
          description: Register Address Line 2.
          type: string
          maxLength: 200
        registerAddressLine3:
          title: Investor Register Address Line 3
          description: Register Address Line 3.
          type: string
          maxLength: 200
        registerAddressLine4:
          title: Investor Register Address Line 4
          description: Register Address Line 4.
          type: string
          maxLength: 200
        registerAddressLine5:
          title: Investor Register Address Line 5
          description: Register Address Line 5.
          type: string
          maxLength: 200
        registerAddressTown:
          title: Investor Register Address Town
          description: Register Address Town.
          type: string
          maxLength: 200
        registerAddressPostCode:
          title: Investor Register Address Post Code
          description: Register Address Postcode.
          type: string
          maxLength: 16
        registerAddressCountry:
          title: Investor Register Address Country
          description: Register Address Country, in ISO3166 alpha-3.
          type: string
          maxLength: 32
        correspondenceAddressLine1:
          title: Investor Correspondence Address Line 1
          description: Correspondence Address Line 1.
          type: string
          maxLength: 200
        correspondenceAddressLine2:
          title: Investor Correspondence Address Line 2
          description: Correspondence Address Line 2.
          type: string
          maxLength: 200
        correspondenceAddressLine3:
          title: Investor Correspondence Address Line 3
          description: Correspondence Address Line 3.
          type: string
          maxLength: 200
        correspondenceAddressLine4:
          title: Investor Correspondence Address Line 4
          description: Correspondence Address Line 4.
          type: string
          maxLength: 200
        correspondenceAddressLine5:
          title: Investor Correspondence Address Line 5
          description: Correspondence Address Line 5.
          type: string
          maxLength: 200
        correspondenceAddressTown:
          title: Investor Correspondence Address Town
          description: Correspondence Address Town.
          type: string
          maxLength: 200
        correspondenceAddressPostCode:
          title: Investor Correspondence Address Post Code
          description: Correspondence Address Postcode.
          type: string
          maxLength: 16
        correspondenceAddressCountry:
          title: Investor Correspondence Address Country
          description: Correspondence Address County, in ISO3166 alpha-3.1.
          type: string
          maxLength: 32
        emailAddress:
          title: Email Address
          description: The Investor Email address.
          type: string
          maxLength: 256
        amlStatus:
          title: AML Status
          description: Indicates the AML compliancy status of the Investor.
          type: string
          enum:
          - Compliant
          - Non-Compliant
        riskLevel:
          title: Investor Risk Level
          description: The Risk Level refers to a classification or categorization assigned to a party (individual or organization) based on their assessed level of risk in the context of financial transactions, regulatory compliance, or business relationships. This risk level helps financial institutions evaluate and manage potential risks associated with the party, such as fraud, money laundering, or credit risk.
          type: string
          enum:
          - High
          - Medium
          - Low
        legalEntityType:
          title: Legal Entity Type
          description: Defines the type of legal entity of the investor.
          type: string
          enum:
          - Individual
          - Corporate
          - Financial Institution
          - Trust
          - Foundation
          - Investment Fund
          - Pension Scheme
          - Public Body
          - Other Legal Arrangements
        fullDealingRestrictionsIndicator:
          title: Full Dealing Restrictions Indicator
          description: Indicates if all transactions are blocked for an Investor across all their accounts.
          type: boolean
        purchaseRestrictionsIndicator:
          title: Purchase Restrictions Indicator
          description: Indicates if only purchase type transactions are blocked across all their accounts.
          type: boolean
        redemptionRestrictionsIndicator:
          title: Redemption Restrictions Indicator
          description: Indicates if only redemption type transactions are blocked across all their accounts.
          type: boolean
        transferInRestrictionsIndicator:
          title: Transfer In Restrictions Indicator
          description: Indicates if only transfer in type transactions are blocked across all their accounts.
          type: boolean
        transferOutRestrictionsIndicator:
          title: Transfer Out Restrictions Indicator
          description: Indicates if only transfer out type transactions are blocked across all their accounts.
          type: boolean
        exchangeInRestrictionsIndicator:
          title: Exchange In Restrictions Indicator
          description: Indicates if only exchange in type transactions are blocked across all their accounts.
          type: boolean
        exchangeOutRestrictionsIndicator:
          title: Exchange Out Restrictions Indicator
          description: Indicates if only exchange out type transactions are blocked across all their accounts.
          type: boolean
        settlementRestrictionsIndicator:
          title: Settlement Restrictions Indicator
          description: ' Indicates if only settlement type transactions are blocked.'
          type: boolean
        activationDate:
          title: Activation Date
          description: The Party Activation Date refers to the date on which a party (individual or organization) becomes active or authorized to participate in financial transactions or activities .within a specific system, account, or service. This date marks the start of the party's operational or transactional relationship.
          type: string
          format: date
        deactivationDate:
          title: Deactivation Date
          description: The Party Deactivation Date refers to the date on which a party (individual or organization) is no longer authorized or active to participate in financial transactions or activities within a specific system, account, or service. This date marks the end of the party's operational or transactional relationship.
          type: string
          format: date
        birthDate:
          title: Birth Date
          description: Individual investor's Date of Birth.
          type: string
          format: date
        countryOfBirth:
          title: Country Of Birth
          description: Individual investor's Country of Birth, in ISO3166 alpha-3.
          type: string
          maxLength: 32
        cityOfBirth:
          title: City Of Birth
          description: Individual investor's City of Birth.
          type: string
          maxLength: 32
        deceasedStatus:
          title: Deceased Status
          description: Indicates the deceased status of an individual investor.
          type: string
          enum:
          - Alive
          - Deceased
          - Deceased Pending
        deathDate:
          title: Death Date
          description: The individual investor's date of death.
          type: string
          format: date
        deathNotificationDate:
          title: Death Notification Date
          description: The individual investor's date of death notification date i.e. the date on which Citi have been advised of the death of the investor prior to Citi receiving the formal documents that allow Citi to change the Deceased Status of the Investor.
          type: string
          format: date
        additionalSupportRequiredFlag:
          title: Additional Support Required Flag
          description: Indicates if additional support is required for this Investor.
          type: boolean
        additionalSupportEffectiveDate:
          title: Additional Support Effective Date
          description: Date from when additional support began.
          type: string
          format: date
        additionalSupportIndicator:
          title: Additional Support Indicator
          description: Indicates the type of additional support.
          type: string
          maxLength: 32
          enum:
          - Assistive Technology Guidance / Technical Assistance
          - Potential Move to in-house
          - Deviation
        countryOfTaxResidency:
          title: Country Of Tax Residency
          description: The individual investor's Country of Tax Residence, in ISO3166 alpha-3.
          type: string
          maxLength: 32
        crsClassification:
          title: CRS Classification
          description: The CRS Classification to be applied to the Investor. Used to drive downstream CRS reporting as certain classifications are exempt from reporting.
          type: string
          maxLength: 32
        crsSelfCertReceived:
          title: CRS Self-Cert Received
          description: The CRS Classification to be applied to the Investor. Used to drive downstream CRS reporting as certain classifications are exempt from reporting.
          type: boolean
        crsPreExistingClient:
          title: CRS Pre-Existing Client
          description: Indicates if the investor is a pre-existing entity or not from the view of CRS reporting guidelines. Can only apply to non-Individual type Investors.
          type: boolean
        crsUndocumented:
          title: CRS Undocumented
          description: Indicates if the investor is a undocumented or not from the view of CRS reporting guidelines.
          type: boolean
        crsDormantIndicator:
          title: CRS Dormant Indicator
          description: Indicates if the investor is a dormant or not from the view of CRS reporting guidelines.
          type: boolean
        gdprObfuscationStatus:
          title: GDPR Obfuscation Status
          description: The Obfuscation Status Id refers to a unique identifier or code that indicates whether a party's details (such as name, address, or other sensitive information) have been intentionally obfuscated or masked. This is typically done to protect privacy, comply with data protection regulations, or meet specific operational requirements.
          type: string
          maxLength: 32
          enum:
          - Obfuscated
          - Not Obfuscated
          - To Be Obfuscated
        gdprObfuscationExclusion:
          title: GDPR Obfuscation Exclusion
          description: The Excluded From Obfuscation Flag is a indicator that specifies whether a party's details (such as name, address, or other sensitive information) are exempt from obfuscation or masking. This flag ensures that certain parties' information remains fully visible, even in scenarios where obfuscation is applied to other parties.
          type: string
          maxLength: 32
        fatcaClassification:
          title: FATCA Classification
          description: The FATCA entity classification ID e.g. FFI, etc.
          type: string
          maxLength: 32
          enum:
          - Active NFFE
          - Affiliate of publicly traded NFFE
          - Certified DC FFI - other
          - Certified DC FFI/sponsored entity
          - Certified deemed-compliant FFI with only low-value accounts
          - Certified deemed-compliant non-profit organization
          - Entity wholly owned by exempt beneficial owners
          - Excepted Foreign Financial Institution
          - Excepted inter-affiliate FFI
          - Excepted NFFE - other
          - Excepted nonfinancial holding company
          - Excepted Territory NFFE
          - Exempt beneficial owner
          - Individual
          - Nonparticipating FFI
          - Nonparticipating FFI with exempt beneficial owners
          - Non-reporting IGA FFI
          - Not applicable - merchant submitting this form solely
          - Participating FFI
          - Participating FFI - other
          - Participating FFI reporting model 2 FFI
          - Passive NFFE reported FFI
          - Passive NFFE with no substantial U.S. owners
          - Passive NFFE with substantial U.S. owners
          - Passive NFFE/no substantial US owner
          - Publicly traded NFFE
          - Register DC FFI reporting model 1 FFI
          - Registered DC FFI - other
          - Registered DC FFI - sponsored entity
          - Registered deemed-compliant FFI
          - Section 501 entities
          - Sponsored direct reporting NFFE
          - Territory FI not treated as US person
          - Territory financial institution
          - Undocumented preexisting obligation
          - Unknown recipient
          - US reportable account
        fatcaSelfCertReceived:
          title: FATCA Self-Cert Received
          description: Indicates if a self-cert has been received from the Investor for FATCA purposes.
          type: boolean
        fatcaExempt:
          title: FATCA Exempt
          description: Indicates if an Investor is except from the FATCA reporting requirements.
          type: boolean
        tin:
          title: TIN
          description: The investor's tax identification number.
          type: string
          maxLength: 32
        giin:
          title: GIIN
          description: The investor's Global Intermediary Identification Number.
          type: string
          maxLength: 32
        nonDigitalInvestor:
          title: Non-Digital Investor
          description: Indicates if the Investor is non-digital.
          type: string
          maxLength: 32
        professionalFlag:
          title: Professional Flag
          description: Flag on whether Investor is deemed a professional.
          type: string
          maxLength: 32
        investorDecisionMakerCountry:
          title: Investor Decision Maker Country
          description: The Investor Decision Maker Country, in ISO3166 alpha-3..
          type: string
          maxLength: 32
        kycId:
          title: KYC ID
          description: KYC ID.
          type: integer
        accountIds:
          title: Account IDs
          type: array
          items:
            type: string
      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
    Get-Investors-Response:
      title: GetInvestorsResponse
      type: object
      properties:
        fundManagerId:
          title: Fund Manager ID
          type: string
          description: Provides the unique identifier for Fund Manager
          maxLength: 32
        investors:
          title: Investors
          type: array
          items:
            $ref: '#/components/schemas/Investor'
      additionalProperties: false
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /authenticationservices/v3/oauth/token
          scopes:
            /authenticationservices/v1: Grant read-only access to IIS Funds TA apis