Statements
Overview
The Statements API allows you to retrieve account statements in a variety of globally supported file formats to assist in everyday cash management, account reconciliation, and treasury processes.
Statements show all incoming and outgoing transactions booked to an account over a particular date up to the close of the previous business day, together with opening and closing account balance positions. The API call will retrieve the list of transactions for multiple accounts based on a specific account identifier and statement identifier.
There are two versions of the Statements API. The first version is the legacy version, which is still available for use, and the second version is the latest version with additional features and improvements. The latest version is recommended for new implementations. Within this overview the differences are noted where applicable.
What will this help me with?
Improved Cash Visibility — View accurate and real-time cash positions to understand available liquidity instantly. This allows for more informed decision-making regarding investments, borrowing, and other financial activities.
Enhanced Forecasting — Improve the accuracy of cash flow forecasting by using the most current information. This helps in planning for future cash needs, managing working capital, and setting more accurate financial targets.
Operational Efficiency — Reduce the need for manual reconciliation and reporting, saving time and reducing errors. This streamlines treasury operations and allows the team to focus on strategic activities rather than administrative tasks.
How it works
Version 2
Version 1
Make a request
You will make a call to the Statement Initiation endpoint, where you will select the account or template name, date range, format, etc. NOTE: A template is a file export profile that must be set up in CitiDirect BE, and can be used to group accounts, in place of sending individual account numbers in the request. For help setting up a template, please contact your Citi representative.
Statement initiation requires some time to be processed to allow successful retrieval. It will depend on the statement size – best practice is to set the retrieval interval every 15 seconds until you receive a 200 successful response. It may take from 15 seconds to a few minutes before the statement is generated.
Availability
Formats
Version 2
Version 1
The Statements API request and response returns JSON and XML format. For the custom XML format response, the Statement File will be returned as follows:
End-of-day Statements
- camt.053.001.02
- SWIFT MT940
Intraday Statements
- camt.052.001.02
- SWIFT MT942
Statement size
- The maximum statement size that may be retrieved using the Statements API is 10MB
- 10MB is approximately 10-12K transactions in MT formats, and approximately 2K transactions in CAMT format (given the many xml tags)
Intraday vs. End of Day statements
- For Intraday statements, the start date and end date should be the current date
- If previous dates are provided, they will be ignored, and the API will return a statement for the current day
- Intraday statement retrieval is incremental, which means that after you initiate the call, the return statement will reflect the beginning of the day until the time the call was made
- For End of Day statements, the start date and end date should be any past date
Branch operating hours and statements
Statement availability is determined by the branch operating hours. As an example, branch hours in Hong Kong and the United Kingdom are not the same hours due to their respective time zones.
Cut-off and processing periods
- Each branch has a cut-off and processing period. Transactions occurring during this time will appear during the following available intraday or end of day statement
- Local branch hours determine when the cut-off and processing periods start. For most branches, the cut-off and processing periods start after the branch or local clearing has closed for the day
- Branch and API requestor in the same time zone
- Accounts in more than one time zone
- Each branch has a cut-off and processing period where the statement information will not be available for a couple of hours
- Local branch hours determine when this cut-off and processing period will commence. As an example, most of these will occur after the branch or local clearing has closed
- If the system calling the Balance data is in another time zone from the account location, then the system design must cater for the account location cut-off period and branch hours
- When the cut-off period has been reached, no intraday balance would be available
- However, the end of day balance would be available, but the request must be for the previous day
Date range
Statements can be generated for the past 90 days only.
Countries
Available in any country where Citi operates. Please speak with your Citi Representative for additional details.
Testing considerations
Mock Statement IDs for API Explorer
Please use the Statement IDs below in API Explorer Statement Retrieval call.
Adding statement retrieval delays to avoid timeouts
Once you receive a response with the Statement ID, we recommend that you systematically introduce a delay when invoking the Statement Retrieval API. The length of the delay should depend on the volume of statement data that you expect to be returned based on the supplied criteria.
For a broader set of results covering several accounts and multiple days of data, the statement generation process may take up to several minutes to complete. In such cases, we advise that additional wait time is introduced, to allow the process to fully retrieve all intended entries without timing out the request.
Security requirements
Citi uses access tokens to authenticate and authorize API requests from your application. To receive an access token from Citi you will first send an API request to our OAuth endpoint using your API credentials: client ID and secret key. Please visit the Authentication guide for more details.