AIS-API 2.0 technical format/ specifications
From 18 Aug 2025, all AIS submissions via API must be made via AIS-API 2.0. To prepare for this transition, all payroll software vendors or AIS employers/ payroll service providers who are using an in-house payroll system/ software can refer to the following technical format/ specifications for AIS-API 2.0. For existing AIS-API developers, you may also wish to refer to the summary of major changes introduced in AIS-API 2.0 to understand the key enhancements.AIS Application Programming Interface (API) 2.0 Service Specifications
- The server/ software/ application must have a Callback URL to redirect users to the payroll software after Corppass login and consent. The Callback URL must use Fully Qualified Domain Name (FDQN), and meet all of the following requirements:
- Must be able to accept parameters,
- Must not contain IP address, port number, Hash (#) or Wildcard (*) characters, and
- Must not be the same URL for Sandbox and Production environments
- Must be able to accept parameters,
Supporting AIS-API 2.0 on APEX |
---|
CorpPass Authentication - OAuth on APEX |
API Services Interface Specifications for “Submission of Employment Income Records 2.0 (AIS-API 2.0)” (PDF, 462KB) |
List of recommended controls (PDF, 140KB) - to be updated in Jul 2025 |
APEX AIS API Onboarding Guide |
FAQ on AIS-API Migration to APEX and Upcoming Activities (PDF, 264KB) |
- partnering IRAS to facilitate your clients’ AIS submissions via the AIS-API 2.0, or
- interested in integrating the AIS-API 2.0 with your in-house payroll software to make AIS submissions for your own employees/ clients,
Major changes introduced in AIS-API 2.0
There are major changes introduced in AIS-API 2.0. Existing AIS-API developers can refer to a summary of the key changes below:1. Submission format
2. Submission size
3. New ‘Revision’ method to amend past records
A new ‘Revision’ option for amendment submissions will be introduced to simplify the submission of past records. This allows your payroll software to generate amendment records with revised data to overwrite previous submissions of the affected record(s).
This is in addition to the existing amendment method where amendment records are submitted based on the difference in the initial and final amounts.
4. Back years records
5. IR8A and Appendices
6. IR8A
All amount fields will only accept value in Number (9).
- If decimals exist for income fields, to round down the amount to the nearest dollar.
- If decimals exist for deduction fields, to round up the amount to the nearest dollar.
The following data items will not be required:
- Citizenship
- Formatted Address (Block/ House No., Street name, Level No., Unit No., Postal Code)
- Cessation Provision Indicator
- Gratuity/ Notice Pay/ Ex-gratia payment/ Others indicator
- Period of Gross Commission payment
- Commission Payment Type
- Breakdown for Allowances items: Transport, Entertainment and Others
- Approval obtained from IRAS for loss of office compensation
- Approval date on compensation for loss of office
- Pension (combine ‘Pension’ with ‘Retirement benefits’)
7. Appendix IR8S
Form IR8S will not be required.
Please note that interest on refund of employee’s CPF contribution remains taxable. Any refund claim amount must be submitted under the item ‘Allowances’ in the IR8A form.
8. Appendix 8A
All amount fields will only accept values in Decimal (7,2) . If the total Benefits-in-kind amount contains decimals, drop the decimals when populating into the corresponding field in IR8A.
9. Appendix 8B
The maximum number of Employee Equity-Based Remuneration Scheme (EEBR) records allowed per employee will be increased to 30, up from 15.
Number of shares, Exercise price and OMV per share at exercise date will only accept values in Decimal (9,5).
All the Gross Amount of Gains fields will only accept values in Decimal (9,2).
If the Total Gains and Profits amount from Share Options for S10(1)(b) and S10(1)(g) contain decimals, drop the decimals when populating the amount into the corresponding field in IR8A.
ERIS has been phased out after Year of Assessment (YA) 2024 as announced in Budget Statement 2013. The following data items will not be required:
- Section B: Equity Remuneration Incentive Scheme (ERIS) SMEs Section fields
- Section C: Equity Remuneration Incentive Scheme (ERIS) All Corporations Section fields
- Section D: Equity Remuneration Incentive Scheme (ERIS) Start-ups Section fields
For enquiries on the Technical Format/ Specifications, email us at [email protected].
Frequently asked questions
Will there be changes to the technical format when IRAS makes changes to the Form IR8A and/ or appendices?
Tax changes and new government initiatives may result in changes to the technical format/ specifications. We will publish the changes on our website by Aug every year and inform all AIS payroll software vendors via email.
Are there any requirements for API integration?
Yes, our API endpoints have to be triggered from a Server-to-Server connection. Your server/ software/ application must be able to:
- Support the following protocols: HTTP/2, TLS 1.2/1.3, and
- Trigger HTTP/GET and HTTP/POST requests.
A Callback URL is also required to redirect users to the payroll software after Corppass login and consent. The Callback URL must use Fully Qualified Domain Name (FDQN), and meet all of the following requirements:
- Must be able to accept parameters,
- Must not contain IP address, port number, Hash (#) or Wildcard (*) characters, and
- Must not be the same URL for sandbox and production environments.
There are differences between the hardcopy forms and the requirements stated in the technical format/ specifications. Which template should I follow to customise the printouts from my software?
AIS employers do not need to issue Form IR8A and/ or appendices to their employees. However, if an electronic copy of the form(s) is requested/ required by the AIS employers i.e. the payroll software users, the payroll software may cater for this feature by mimicking the fields in the official copy of the income tax forms (https://go.gov.sg/iras-formir8a) to customise the printouts. The payroll software should be able to capture these fields’ input based on the format specifications, and generate the printout accordingly.
For clients who are in the Auto-Inclusion Scheme (AIS), the following statement must be displayed at the top header of the form(s):
“This statement can only be issued by an employer in the Auto-Inclusion Scheme (AIS) and is for your retention. The information in this statement will be automatically included in your income tax return, so you need not declare them in your tax form. You can check if your employer is in the AIS at IRAS website, https://go.gov.sg/iras-ais-search.”
Must the files be encrypted as a security feature?
No. IRAS’ applications use the Secure Socket Layers (SSL) technology, which is the industry standard protocol for secure, web-based communications and transactions. SSL creates a secure communication channel between the server and the consumer’s browser. SSL provides message privacy by encrypting all information exchanged between the web server and the consumer’s browser.