IRAS API Services Interface Specifications

IRAS API SERVICES

INTERFACE SPECIFICATIONS

Auto-Inclusion Scheme (AIS) For Employment Income

Last updated on : 3 November 2020

Version No: 1.2

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 1 of 21

IRAS API Services Interface Specifications

Version Control
Version History

Revision Date Version Change Log Summary

Number
16 Nov 2016 1.1 Baseline
03 Nov 2020 1.2 Removed extra spaces in Sample Json Object

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 2 of 21

IRAS API Services Interface Specifications

Table of Contents

1. Introduction .................................................................................................................. 4
2. Registration at API Portal ............................................................................................. 4
3. API Services ................................................................................................................ 5
3.1 AIS for Employment Income API Service ................................................................. 5
3.1.1 JSON Request for AIS for Employment Income API Service .................................. 7
3.1.2 JSON Responses for AIS for Employment Income API Service ........................... 11
3.1.2.1 Success Response .............................................................................. 13
3.1.2.2 Error Response: Content Validation...................................................... 14
3.1.2.3 Error Response: Header or Trailer ........................................................ 16
3.1.2.4 Error Response: Exceed Max Records ................................................. 17
3.1.2.5 Error Response: Server Error ............................................................... 18
4. Status Codes for API Response.................................................................................. 19
5. Sample Code (C#) ..................................................................................................... 20

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 3 of 21

IRAS API Services Interface Specifications

1. Introduction

The Inland Revenue Authority of Singapore (IRAS) provides application programming interface
(API) services to allow application developers to submit and retrieve tax related matters using
HTTP requests. Most of the APIs will be in the form of a RESTFUL web service which reduces
client/server coupling and thus enabling easier integration between IRAS’s service with external
developers.

There will be a variety of services available in due time, while some services require a simple
GET, others may be secured and require credentials that can be passed via HTTP header
parameters, as follows :

Client-Id String containing the client ID of the application invoking IRAS’ API. This
value will be provided to the application vendor by IRAS.

E.g. a1234b5c-1234-abcd-efgh-a1234b5cdef

Client-Secret String containing the client secret of the application invoking IRAS’ API. This
value will be provided to the application vendor by IRAS.

E.g. a12345bC67e8fG9a12345bC67e8fG9a12345bC67e8fG9

This document serves to help developers consume the API services provided by IRAS.

2. Registration at API Portal

Application developers are required to register for an account at https://apisandbox.iras.gov.sg/

to subscribe to IRAS API services for Sandbox Testing and an account at
https://apiservices.iras.gov.sg/ to subscribe to IRAS API services for Production.

A computer-generated email will be sent to the subscriber’s email account for activation.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 4 of 21

IRAS API Services Interface Specifications

3. API Services

IRAS will provide several API services for public consumption. The following sections describe
the request and response for each of the services.

The table below shows the list of API services currently available in IRAS.

S/No Name of API Description URL

Services
1 AIS for This API For Sandbox Testing:
Employment allows AIS https://apisandbox.iras.gov.sg/iras/aisubmission/submit
Income employers to
validate and For Actual Submission (Production):
submit the https://apiservices.iras.gov.sg/iras/aisubmission/submit
employment
income This service is available only when the AIS submission
information of portal is opened.
their
employees to AIS Employers can refer to IRAS’ website for the portal
IRAS. opening period:
https://www.iras.gov.sg/irashome/Businesses/Employe
rs/Auto-Inclusion-Scheme--AIS--for-Employment-
Income/

3.1 AIS for Employment Income API Service

This service allows employers to submit employee’s employment income (IR8A, IR8S, Appendix
8A and Appendix 8B). Each submission allows up to 800 records and cannot be more than 8 Mb
in data size.

Examples of Acceptable Submissions

• 800 IR8A records
• 500 IR8A records + 100 IR8S records + 50 Appendix 8A records + 50 Appendix 8B
records
• 100 IR8A records + 30 IR8S records + 10 Appendix 8A records

Examples of Rejected Submissions

• 801 IR8A records
• 201 IR8A records + 200 IR8S records + 200 Appendix 8A records + 200 Appendix 8B
records

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 5 of 21

IRAS API Services Interface Specifications

Submission Guideline
- If an employee has excess CPF contribution, Benefits-in-Kind and/or Stock Options Gains,
submit all the relevant form types (IR8A / IR8S / Appendix 8A / Appendix 8B) of this employee
within the same request.

- Ensure the amounts reflected in the IR8A and the supporting forms (IR8S / Appendix 8A /
Appendix 8B) tally.

- Do NOT submit duplicate data.

- Original data (i.e. Batch Indicator = O) must be submitted before Amendment data.

- When submitting Amendment data, only prepare the affected employees' records and provide
the difference in amounts. Leave other numeric fields not affected by the error blank.
If the amendment for the supporting forms (IR8S/ Appendix 8A/ Appendix 8B) affects the
amounts submitted for Form IR8A, an IR8A amendment data has to be submitted within the
same request as well.

Sandbox Testing
This service in the sandbox environment is designed to mimic the actual Production
environment so developers can test the API integration before submitting to the Production
environment. Test scenarios and entities will be published in the API portal for developers to use.
With effect from YA 2021, this service is no longer available for subscription for new software
developers.

After a successful sandbox submission, a reference number will be provided within the API
response.

Submit the reference number(s) for the test scenario applicable to [email protected].

IRAS will review the submitted data and respond within 10 working days.

Production
Approval is required to use this service.

Before approval can be granted, developers must participate in the Sandbox Testing.

After approval is granted, client application can POST a JSON request object to the production
URL.

HTTP Header parameters

Client-Id String containing the client ID of the application invoking IRAS’ API. This value
will be provided to the application vendor by IRAS.

Client-Secret String containing the client secret of the application invoking IRAS’ API. This
value will be provided to the application vendor by IRAS.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 6 of 21

IRAS API Services Interface Specifications

3.1.1 JSON Request for AIS for Employment Income API Service

Client invoking this service will be expected to submit the following JSON request object with the
following fields in the HTTP request. Note that the field names are case sensitive.

validateOnly Boolean Indicator to indicate whether to validate JSON message only.

If validateOnly = true, the API will peform validation of the employment
income information without submission.
If validateOnly = false, the API will peform validation of the employment
income information and submission to IRAS.

bypass Boolean Indicator to indicate whether to bypass warning message thrown and
proceed with submission.
If bypass = true, hit warning and proceed with submission.
If bypass = false, respond as error with no submission.

userID String containing the ID Number of the person doing the submission. ID
Number must be valid.

userIDType String containing the type of User ID Number. Acceptable type are “1” is for
NRIC, “2” is for FIN , “4” is for WP , “A” is for ASGD and “11” is for MIC

ir8aInput String containing the content of the IR8A

This will be the same as the one that is generated for IRAS’ Validation and
Submission Application.^#

ir8sInput String containing the content of the IR8S

This will be the same as the one that is generated for IRAS’ Validation and
Submission Application.^ #

a8aInput String containing the content of the Appendix 8A

This will be the same as the one that is generated for IRAS’ Validation and
Submission Application.^ #

a8bInput String containing the content of the Appendix 8B

This will be the same as the one that is generated for IRAS’ Validation and
Submission Application.^ #

inputType String to indicate if the content is a XML or TEXT format. Expected value
includes “XML” and “TEXT”.

clientID String containing the ID of the application invoking IRAS’ API. This value will
be provided to the application vendor by IRAS. This value will be the same as
the Client-Id in the HTTP header parameter.

^ Refer to the current file format published at

https://www.iras.gov.sg/IRASHome/Businesses/Employers/Auto-Inclusion-Scheme--AIS-
/Technical-File-Format/Specifications/

# At least one of the form inputs must be filled. All inputs must be of the same input type (TEXT /
XML).

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 7 of 21

IRAS API Services Interface Specifications

JSON request object schema

{
"properties": {
"validateOnly": {
"type": "boolean",
"description": "Validate Only Indicator"
},
"bypass": {
"type": "boolean",
"description": "Bypass Indicator"
},
"userID": {
"type": "string",
"description": "User ID"
},
"userIDType": {
"type": "string",
"description": "User ID Type"
},
“ir8aInput”: {
"type": "string",
"description": "ir8a XML or TEXT string"
},
"ir8sInput”: {
"type": "string",
"description": "ir8s XML or TEXT string"
},
"a8aInput”: {
"type": "string",
"description": "a8a XML or TEXT string"
},
"a8bInput”: {
"type": "string",
"description": "a8b XML or TEXT string"
},
"inputType": {
"type": "string",
"description": "XML or TEXT indicator"
},
"clientID": {
"type": "string",
"description": "Client ID"
}
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 8 of 21

IRAS API Services Interface Specifications

Sample JSON request object

{
"validateOnly": false,
"bypass": false,
"userID": "200312345A",
"userIDType": "8",
"ir8aInput": null,
"ir8sInput": null,
"a8aInput": "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"no\"?><A8A2015
xmlns=\"http://www.iras.gov.sg/A8A2015Def\">\r\n<A8AHeader>\r\n<ESubmissionSDSC
xmlns=\"http://tempuri.org/ESubmissionSDSC.xsd\">\r\n<FileHeaderST>\r\n<RecordType>0</Re
cordType>\r\n<Source>6</Source>\r\n<BasisYear>2015</BasisYear>\r\n<OrganizationID>8</Or
ganizationID>\r\n<OrganizationIDNo>200312345A</OrganizationIDNo>\r\n<AuthorisedPersonN
ame>TOMMY
LEE</AuthorisedPersonName>\r\n<AuthorisedPersonDesignation/>\r\n<EmployerName>ABC
PTE
LTD</EmployerName>\r\n<Telephone/>\r\n<AuthorisedPersonEmail/>\r\n<BatchIndicator>O</B
atchIndicator>\r\n<BatchDate>20150101</BatchDate>\r\n<DivisionOrBranchName/>\r\n</FileHe
aderST>\r\n</ESubmissionSDSC>\r\n</A8AHeader>\r\n<Details>\r\n<A8ARecord>\r\n<ESubmis
sionSDSC
xmlns=\"http://tempuri.org/ESubmissionSDSC.xsd\">\r\n<A8A2015ST>\r\n<RecordType
xmlns=\"http://www.iras.gov.sg/A8A2015\">1</RecordType>\r\n<IDType
xmlns=\"http://www.iras.gov.sg/A8A2015\">1</IDType>\r\n<IDNo
xmlns=\"http://www.iras.gov.sg/A8A2015\">S1234657A</IDNo>\r\n<NameLine1
xmlns=\"http://www.iras.gov.sg/A8A2015\">SAMPLE 1</NameLine1>\r\n<NameLine2
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<ResidenceAddressLine1
xmlns=\"http://www.iras.gov.sg/A8A2015\">123</ResidenceAddressLine1>\r\n<ResidenceAddre
ssLine2
xmlns=\"http://www.iras.gov.sg/A8A2015\">Novena</ResidenceAddressLine2>\r\n<ResidenceAd
dressLine3 xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<OccupationFromDate
xmlns=\"http://www.iras.gov.sg/A8A2015\">20150301</OccupationFromDate>\r\n<OccupationTo
Date xmlns=\"http://www.iras.gov.sg/A8A2015\">20150529</OccupationToDate>\r\n<NoOfDays
xmlns=\"http://www.iras.gov.sg/A8A2015\">90</NoOfDays>\r\n<NoOfEmployeeSharePremises
xmlns=\"http://www.iras.gov.sg/A8A2015\">2</NoOfEmployeeSharePremises>\r\n<AVOfPremise
s
xmlns=\"http://www.iras.gov.sg/A8A2015\">4931.50</AVOfPremises>\r\n<ValueFurnitureFittingI
nd
xmlns=\"http://www.iras.gov.sg/A8A2015\">F</ValueFurnitureFittingInd>\r\n<ValueFurnitureFittin
g
xmlns=\"http://www.iras.gov.sg/A8A2015\">2465.75</ValueFurnitureFitting>\r\n<RentPaidToLan
dlord xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<TaxableValuePlaceOfResidence
xmlns=\"http://www.iras.gov.sg/A8A2015\">7397.25</TaxableValuePlaceOfResidence>\r\n<Total
RentPaidByEmployeePlaceOfResidence
xmlns=\"http://www.iras.gov.sg/A8A2015\">2000.00</TotalRentPaidByEmployeePlaceOfResiden
ce>\r\n<TotalTaxableValuePlaceOfResidence
xmlns=\"http://www.iras.gov.sg/A8A2015\">5397.25</TotalTaxableValuePlaceOfResidence>\r\n<
UtilitiesTelPagerSuitCaseAccessories
xmlns=\"http://www.iras.gov.sg/A8A2015\">250.00</UtilitiesTelPagerSuitCaseAccessories>\r\n<
Driver xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<ServantGardener
xmlns=\"http://www.iras.gov.sg/A8A2015\">1200.00</ServantGardener>\r\n<TaxableValueUtilitie
sHouseKeeping
xmlns=\"http://www.iras.gov.sg/A8A2015\">1450.00</TaxableValueUtilitiesHouseKeeping>\r\n<A
ctualHotelAccommodation
xmlns=\"http://www.iras.gov.sg/A8A2015\">2500.00</ActualHotelAccommodation>\r\n<AmountP
aidByEmployee
Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 9 of 21
IRAS API Services Interface Specifications

xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<TaxableValueHotelAccommodation
xmlns=\"http://www.iras.gov.sg/A8A2015\">2500.00</TaxableValueHotelAccommodation>\r\n<C
ostOfLeavePassageAndIncidentalBenefits
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<NoOfLeavePassageSelf
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<NoOfLeavePassageSpouse
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<NoOfLeavePassageChildren
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<OHQStatus
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<InterestPaidByEmployer
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<LifeInsurancePremiumsPaidByEmployer
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<FreeOrSubsidisedHoliday
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<EducationalExpenses
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<NonMonetaryAwardsForLongService
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<EntranceOrTransferFeesToSocialClubs
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<GainsFromAssets
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<FullCostOfMotorVehicle
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<CarBenefit
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<OthersBenefits
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<TotalBenefitsInKind
xmlns=\"http://www.iras.gov.sg/A8A2015\">9347.25</TotalBenefitsInKind>\r\n<Filler
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n<FieldReserved
xmlns=\"http://www.iras.gov.sg/A8A2015\"/>\r\n</A8A2015ST>\r\n</ESubmissionSDSC>\r\n</A8
ARecord>\r\n</Details>\r\n</A8A2015>",
"a8bInput": null,
"inputType": "XML",
"clientID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 10 of 21

IRAS API Services Interface Specifications

Sample JSON request object

{
"validateOnly": false,
"bypass": false,
"userID": "197200994H",
"userIDType": "8",
"ir8aInput": null,
"ir8sInput": "",
"a8aInput": "0620158200312345A TOMMY LEE FINANCE MANAGER
ABC PTE LTD
O20150101 A8A
\r\n11S1234567A SAMPLE 1 123
NOVENA
201503012015052909002000493150F0002465750000000000007397250002000000005397250
00025000000000000000120000000145000000250000000000000000250000000000000000000
00000000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000934725
\r\n",
"a8bInput": "",
"inputType": "TEXT",
"clientID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

3.1.2 JSON Responses for AIS for Employment Income API Service

For API services that process or persist data, a JSON response object will be returned to the
client after service is invoked in the HTTP response. Clients invoking these API services will be
required to consume this JSON response object to retrieve the status and output. The schema of
the response object varies across services and will be covered in detail in each specific service
in the later sections.

Depending on the request to this service, the following different responses can be expected from
the service based on the input provided to it from the request.

statusCode A string representing the status of the service output returned to the client. The
default value is 200 (OK). For a listing of valid status codes, see Status Codes
section below.

msgError A string containing general error message.

ir8a An array containing the output, warning, error related to the ir8a form submitted.

ir8s An array containing the output, warning, error related to the ir8s form submitted.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 11 of 21

IRAS API Services Interface Specifications

a8a An array containing the output, warning, error related to the a8a form submitted.

a8b An array containing the output, warning, error related to the a8b form submitted.

Detailed description of the output, warning and error are listed the table below.
output An array containing pipe delimited string/s containing the Submission Reference
Number and the processed information of the submission, as shown in sample
below. Client is expected to store the Submission Reference Number for future
reference.

The output is delimited in the following order:

• Submission Reference Number
• Organisation Name
• Organisation Reference Number
• Basis Year + 1
• File Type - “O” for original submission, “A” for amendment
• Date and time of submission in ddMMyyHHmm format
• User ID
• Number of Records
error An array list of error messages. Each array item will contain a JSON error object
with the following fields:
• error – a string containing the error message or number.
• RecordField – a string containing the field that caused the error.
• RecordIdentifier – a string containing the ID of the record or row that
caused the error
• RecordType – a string containing the type of record that caused the error,
record type will be specific to each service.
(0 = Header,1 = Detail, 2 = Trailer)
warning An array list of warning messages. Each array item will contain a JSON error
object with the following fields:
• error – a string containing the warning message or number.
• RecordField – a string containing the field that caused the error.
• RecordIdentifier – a string containing the ID of the record or row that
caused the error
• RecordType – a string containing the type of record that caused the error,
record type will be specific to each service.
(0 = Header,1 = Detail, 2 = Trailer)

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 12 of 21

IRAS API Services Interface Specifications

3.1.2.1 Success Response

A successful call to the service means that the AIS submission is accepted. A JSON response
object that contains the following fields will be returned in the HTTP response.

statusCode A string containing the value “200”, representing STATUS_OK.

msgError Empty
ir8a An array containing the output, warning, error related to the ir8a form submitted.
ir8s An array containing the output, warning, error related to the ir8s form submitted.
a8a An array containing the output, warning, error related to the a8a form submitted.
a8b An array containing the output, warning, error related to the a8b form submitted.

Sample JSON response object

{
"statusCode": “200”,
"msgError": “”,
"ir8a": {
"output":"ES12345678ir8a1234567890|SAMPLE PTE.
LTD.|200312345A|2016|O|0102161600|200312345A|30|99999|999",
"warnings":[{}],
"errors":[{}]
},
"ir8s": {
"output":"",
"warnings":[{}],
"errors":[{}]
},
"a8a": {
"output":"",
"warnings":[{}],
"errors":[{}]
},
"a8b": {
"output":"",
"warnings":[{}],
"errors":[{}]
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 13 of 21

IRAS API Services Interface Specifications

OR

If bypass=true, warning message will be shown and submission is allowed.

{
"statusCode": “200”,
"msgError": “”,
"ir8a": {
"output":"ES12345678ir8a1234567890|SAMPLE PTE.
LTD.|200312345A|2016|O|0102161600|200312345A|30|99999|999",
"warnings":[{
"recordType": 1,
"recordField": "IDNo",
"recordIdentifier": "S1234567A",
"error": "ir8s is required"
}],
"errors":[ ]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

3.1.2.2 Error Response: Content Validation

When the records in the content has failed validations, the call to the service is unsuccessful. A
JSON response object that contains the following fields will be returned in the HTTP response.

statusCode A string containing the value “400”, representing STATUS_BAD_REQUEST.

msgError String which may contain a simplified error message or an error number.
ir8a An array containing the output, warning, error related to the ir8a form submitted.
ir8s An array containing the output, warning, error related to the ir8s form submitted.
a8a An array containing the output, warning, error related to the a8a form submitted.
a8b An array containing the output, warning, error related to the a8b form submitted.

Sample JSON response object

{
"statusCode": “400”,
"msgError": “”,
"ir8a": {
"output":"ES12345678ir8a1234567890|SAMPLE PTE.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 14 of 21

IRAS API Services Interface Specifications

LTD.|200312345A|2016|O|0102161600|200312345A|30|99999|999",
"warnings":[ ],
"errors":[ ]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

If bypass=false, warning message will be shown and submission will not be allowed.
{
"statusCode": “400”,
"msgError": “”,
"ir8a": {
"output":"ES12345678ir8a1234567890|SAMPLE PTE.
LTD.|200312345A|2016|O|0102161600|200312345A|30|99999|999",
"warnings":[{
"recordType": 1,
"recordField": "IDNo",
"recordIdentifier": "S1234567A",
"error": "ir8s is required"
}],
"errors":[ ]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 15 of 21

IRAS API Services Interface Specifications

3.1.2.3 Error Response: Header or Trailer

When the Header or Trailer in the content has failed validations, the call to the service is
unsuccessful. A JSON response object that contains the following fields will be returned in the
HTTP response.

statusCode A string containing the value “400”, representing STATUS_BAD_REQUEST.

msgError String which may contain a simplified error message or an error number.
ir8a An array containing the output, warning, error related to the ir8a form submitted.
ir8s An array containing the output, warning, error related to the ir8s form submitted.
a8a An array containing the output, warning, error related to the a8a form submitted.
a8b An array containing the output, warning, error related to the a8b form submitted.

Sample JSON response objects

{
"statusCode": “400”,
“msgError”: “”,
"ir8a": {
"output":"",
"warnings":[{}],
"errors":[{
"recordType": “2”,
"recordField": "BasisYear",
"recordIdentifier": "200312345A",
"error": "Invalid"
}]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 16 of 21

IRAS API Services Interface Specifications

3.1.2.4 Error Response: Exceed Max Records

When the number of records submitted is more than 800, the call to the sevice is unsuccessful. A
JSON response object that contains the following fields will be returned in the HTTP response.
There will be only one error record in an error array, as shown in sample below.

statusCode A string containing the value “413”, representing

STATUS_REQUEST_TOO_LARGE.

msgError String which may contain a simplified error message or an error number.
ir8a An array containing the output, warning, error related to the ir8a form submitted.
ir8s An array containing the output, warning, error related to the ir8s form submitted.
a8a An array containing the output, warning, error related to the a8a form submitted.
a8b An array containing the output, warning, error related to the a8b form submitted.

Sample JSON response object

{
"statusCode": “413”,
“msgError”: “NoOfRecords Exceed 800”,
"ir8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 17 of 21

IRAS API Services Interface Specifications

3.1.2.5 Error Response: Server Error

When an exception occurs during the processing of the request, a JSON response object that
contains the following fields will be returned in the HTTP response.

statusCode A string containing the value “500”, representing STATUS_SERVER_ERROR.

msgError String which may contain a simplified error message or an error number.

Sample JSON response object

{
"statusCode": “500”,
"msgError": “Internal Server Error Occurred. Please try again later.”,
"ir8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"ir8s": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8a": {
"output":"",
"warnings":[ ],
"errors":[ ]
},
"a8b": {
"output":"",
"warnings":[ ],
"errors":[ ]
}
}

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 18 of 21

IRAS API Services Interface Specifications

4. Status Codes for API Response

The statusCode field will always contain an integer representing the processed state of the
request. The list of possible status codes and what they represent are listed below.

Status Status Code Remarks

STATUS_OK 200 The request completed successfully.

STATUS_NO_CONTENT 204 The server has fulfilled the request, but

there is no new information to send back.

STATUS_MOVED 301 The requested service has been

assigned to a new permanent Uniform
Resource Identifier (URI), and any future
references to this service should be done
using one of the returned URIs.

STATUS_REDIRECT 302 The requested service resides

temporarily under a different URI.

STATUS_NOT_MODIFIED 304 The requested did not make any

modification.

STATUS_BAD_REQUEST 400 The request could not be processed by

the server due to invalid inputs.

STATUS_DENIED 401 The requested service requires user

authentication/authorisation.

STATUS_GONE 410 The requested service is no longer

available at the server, and no forwarding
address is known.

STATUS_REQUEST_TOO_LARGE 413 The server cannot process the request

because the submitted entity is larger
than the server is able to process.

STATUS_SERVER_ERROR 500 The server encountered an unexpected

condition that prevented it from fulfilling
the request.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 19 of 21

IRAS API Services Interface Specifications

5. Sample Code (C#)

using System;
using System.Net;
using System.IO;
using System.Text;

// jsonData – contains data from Section 3.1.1 of this document

public static void callWebAPI(string jsonData)
{
//Step 0 : Call ServerCertificateValidationCallback
ServicePointManager.ServerCertificateValidationCallback += (sender, cert, charin,
sslPolicyErrors) => true;

// Step 1: Construct URL

String url = "https://192.168.86.71/sit-apd/sb/ais-sit/submit";

try
{
var httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
httpWebRequest.ContentType = "application/json;";
httpWebRequest.Method = "POST";

//Step 2: Enter the Client-Id given by IRAS

httpWebRequest.Headers["Client-Id"] = "a4434a0b-1514-4dc6-b4f7-db5316bfd647";
//Step 3: Enter the Client-Secret given by IRAS
httpWebRequest.Headers["Client-Secret"] =
"qO3eB0gC2eF5cV7tR1oY6tG5wL8nX6cR5rN0tH1hF3pF6dB6wL";

// Step 4: Call API using POST

using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
streamWriter.Write(jsonData);
streamWriter.Flush();
streamWriter.Close();
}

// Step 4a: Output response

var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
var result = streamReader.ReadToEnd();
//print the received reponse
Console.WriteLine(result);
}
}
catch (WebException e)
{
if (!string.IsNullOrEmpty(e.Message))
{
// Step 4b: Print general errors
Console.WriteLine("Exception - ");
Console.WriteLine(e.Message);

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 20 of 21

IRAS API Services Interface Specifications

if (e.Response != null)
{
// Step 4c: Print Output response exception
Stream receiveStream = e.Response.GetResponseStream();
StreamReader readStream = new StreamReader(receiveStream, Encoding.UTF8);
// print the error received from Server
Console.WriteLine("Response error received - ");
Console.WriteLine(readStream.ReadToEnd());
}
}
}

The information provided is intended for better general understanding and is not intended to comprehensively address
all possible issues that may arise. The contents are correct as at 3 Nov 2020 and are provided on an “as is” basis
without warranties of any kind. IRAS shall not be liable for any damages, expenses, costs or loss of any kind however
caused as a result of, or in connection with your use of this document.

While every effort has been made to ensure that the above information is consistent with existing policies and practice,
should there be any changes, IRAS reserves the right to vary our position accordingly.

Inland Revenue Authority of Singapore (Nov 2020, Version 1.2) Page 21 of 21