openapi: 3.1.0
info:
title: Transfer Agency Investor
description: >
The Transfer Agency Investor API provides programmatic access to investor
data maintained on the Transfer Agency register. It allows applications to
retrieve up‑to‑date investor static information, supporting End‑of‑Day and
near real-time use cases. The API enhances data accuracy and client
experience while eliminating reliance on periodic file‑based delivery and
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/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:
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: >-
current_page: current page number
total_page: Total number of
pages available for your request
page_size: Total number of records
available in the current page
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
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
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
securitySchemes:
oAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: /authenticationservices/v3/oauth/token
scopes:
/authenticationservices/v1: Grant read-only access to IIS Funds TA apis
tags:
- name: Investors
description: Operations related to Investors