Version and service purpose
The 1 October 2026 version 1.4 describes submission of donation records using Corppass and the APEX platform. Its baseline dates to October 2024; September 2025 added tax-agent selection, December 2025 changed response codes to strings, April 2026 revised examples, and October 2026 updated recordId and donor-ID descriptions, removed sample code and refreshed onboarding links. It is an integration specification, not a general determination that every donation qualifies for a tax deduction.
Developer onboarding and authorisation
Developers need Corppass. Their organisation’s Admin or Sub-Admin must assign the APEX Cloud e-Service. Register applications, generate API keys, create an OAuth 2.1 client and subscribe the application to the API. Update the first-login email address for downtime and change notices. Obtain the Corppass token through OAuth 2.1 with scope DonationSub. At authorisation, tax_agent=y means acting for a business client; tax_agent=n means the organisation’s own tax matters.
Sandbox first, approved production next
Sandbox subscription does not require IRAS approval. Use the IRAS test entity, an OAuth 2.1 Sandbox Client and scenarios in the Donation API Test Guide. Production requires successful sandbox testing and IRAS approval, plus a production OAuth client. Production is for the stated service only; testing there breaches the terms and can lead to suspension or termination. Both IRAS API and APEX terms apply.
Endpoints, transport and headers
Use POST https://sandbox.api.gov.sg/iras/donation-records/v1/Submit or https://public.api.gov.sg/iras/donation-records/v1/Submit for the appropriate environment. Server-to-server connections use TLS and IP whitelisting; the application must support HTTP/2, TLS 1.2/1.3 and HTTP GET/POST. Set x-apex-apikey to the subscribed application key, Authorization to Bearer plus the Corppass JWT, and Content-Type to application/json. The printed header example still shows an older /iras/prod/DonationCP/submit path and HTTP/1.1; these do not match the current endpoint table and transport requirement and should not be treated as the updated route.
Payload limits, atomic acceptance and retries
Each request is limited to 5,000 records and 2 MB. Exceeding either fails: 4,000 records above 2 MB and 5,001 records are rejected. Split 8,000 records into 5,000 and 3,000 requests, each within size limits. A payload has no partial acceptance: every record must pass. If a 3,500-record request succeeds but a separate 1,500-record request fails, correct and resubmit only the failed request. Each application is limited to 1,000 requests an hour; HTTP 429 with Assembly Rate Limit exceeded requires retry in the next hour.
Case, characters and field types
JSON names are case-sensitive and normally camelCase. Required properties must be present; optional exceptions are identified in the tables. Date strings follow ISO 8601, but dateOfDonation is expressly an eight-digit numeric YYYYMMDD. String lengths are maximums, and Number(n) describes up to n whole-number digits. Allowed characters are ASCII 32–127, ü, Ü, İ, LF and CR, en/em dashes and curly double/single quotes. Other characters can fail validation.
Organisation and submission object
orgAndSubmissionInfo contains the IPC identity, authorised person and totals. basisYear is the donation-received year, allowing three previous years, the current year and one future year. organisationIDType accepts 5,6,U,A,I; corresponding patterns are NNNNNNNNC, YYYYNNNNNC, TYYPQNNNNC/SYYPQNNNNC, ANNNNNNNC and NNNNNNNNNC. C denotes the check digit, N a digit and Y a year component. The submitting person accepts NRIC S/T, FIN F/G/M, ASGD or ITR. validateOnly=true checks without filing; false validates and files. The structure table below preserves field size and optionality.
| Field | Type/maximum | Requirement |
|---|---|---|
| validateOnly | Boolean | Required; true validates only, false submits |
| basisYear | Number(4) | Required; received year, previous 3/current/next 1 |
| organisationIDType | String(1) | Required;5/6/U/A/I |
| organisationIDNo | String(12) | Required; corresponding identity format |
| organisationName | String(60) | Required |
| batchIndicator | String(1) | Required;O/A |
| authorisedPersonIDNo | String(12) | Required;NRIC/FIN/ASGD/ITR |
| authorisedPersonName | String(30) | Required |
| authorisedPersonDesignation | String(30) | Optional |
| telephone | String(20) | Required;at least 8 digits |
| authorisedPersonEmail | String(50) | Required |
| numOfRecords | Number(7) | Required;integer record count |
| totalDonationAmount | Number(12) | Required;sum of donationAmount |
Donor records and special identity requirements
donationDonorDtl holds the donor records; despite the request table labelling it Object, the example uses an array. recordId is a unique running number starting at 1. idType accepts 1 NRIC,2 FIN,5 UEN-business,6 UEN-local company,A ASGD,I ITR,U UEN-others. Validate the corresponding identity format, including FIN prefix M. For VCC sub-fund entities use the IRAS-assigned ASGD number. individualIndicator is otherwise optional but is compulsory as IND or NON for A or I. Keep leading zeroes in a supplied numeric postal code.
| Field | Type/maximum | Requirement |
|---|---|---|
| recordId | Number(4) | Required;unique running number from1 |
| idType | String(1) | Required;1/2/5/6/A/I/U |
| idNumber | String(12) | Required;valid matching type;VCC sub-fund ASGD |
| individualIndicator | String(3) | Optional except A/I;IND/NON |
| name | String(80) | Required |
| addressLine1 | String(30) | Optional |
| addressLine2 | String(30) | Optional |
| postalCode | String(6) | Optional;digits,retain leading zero |
| donationAmount | Number(9) | Required;integer,original nonzero |
| dateOfDonation | Number(8) | Required;YYYYMMDD |
| receiptNum | String(20) | Required;receipt/unique reference |
| typeOfDonation | String(1) | Required;O/S/A/L/P/H |
| namingDonation | String(1) | Required;Z/N/F |
Donation amounts, categories and a rounding inconsistency
donationAmount is an integer with at most nine digits, not blank and without spaces. Original records cannot have zero. The source calls for rounding to the nearest dollar but gives 101.20→102, which is inconsistent with ordinary nearest-dollar rounding; the PDF does not settle that discrepancy, so confirm the required behaviour against the current test guide or IRAS before implementing it. Types are O cash,S shares/unit trusts,A artefacts,L land/buildings,P public sculpture,H the Overseas Humanitarian Assistance Tax Deduction Scheme. For S, donors must use NRIC, FIN, ASGD or ITR; A/I must also have IND. namingDonation is Z non-naming by default,N an IPC named after the donor or immediate living family member,F an IPC facility named after the donor.
Amendments overwrite the donor’s existing record
batchIndicator=O denotes an original and A an amendment. An amendment replaces previously submitted donation information for the particular donor. The example retains the donor ID, donation date and receipt reference but changes S$100 to S$50; the latest S$50 becomes IRAS’s recorded amount. numOfRecords must match the donor-record count and totalDonationAmount the sum of submitted donationAmount values. Do not use a new original merely to repeat a successfully accepted chunk.
Read the response code, not a caption or message alone
returnCode, acknowledgementCode and messageCode are strings. Code "10" means processed; "30" means not processed. A successful real filing carries an acknowledgement; successful validate-only returns an empty data object and is not a filing. A "10" can include warnings, such as a prior basis year, and still be accepted. The warning example even includes messageCode 850301 and Arguments Error: check returnCode and acknowledgement rather than that message alone. Several error examples are captioned success in the PDF although their actual returnCode is "30". Retain accepted acknowledgements and examine info.fieldInfoList for field-level failures; affected record IDs can be grouped as "3,5,7".
Diagnostic codes and inconsistencies to resolve
The six codes are 850300 null request,850301 invalid arguments,850302 service exception,850303 inactive service,850304 unauthorised credentials and850305 invalid sandbox test user. Field diagnostics name the field, message and affected record numbers. Version1.4 changes the request name to recordId, but its sample still uses recordID, quotes Boolean validateOnly as a string, and gives an ASGD example inconsistent with the format table. Other capitalisation varies between Info/info and recordId/recordID; the response description refers to donationDtl although the request object is donationDonorDtl. Because case and types matter, use the current specification and sandbox tests to resolve these inconsistencies rather than copying examples unchanged.
Official source
This article independently explains the substantive contents of the official PDF, including the relevant conditions, procedures and annexes. The linked document remains the authoritative source for its original wording, and later changes should be checked separately.
Read the official PDF ↗