Purpose and version history
Version1.2, updated1 November2021, describes the Corppass-authenticated commission-record API for software providers and commission-paying organisations. It validates/submits commission information for prefilling earners’ individual tax returns. Version1.0 began15 December2020;1.1 added the endpoint method on6 April2021;1.2 added FIN M-series validation. This is a historical interface specification, not confirmation that every endpoint or portal screen remains unchanged.
Developer accounts, organisation name and application
Create separate developer accounts for the sandbox and production API marketplaces and activate them through the generated email. After login, use Username > My Organization > Edit organization and identify the actual organisation followed by an underscore and ROC/UEN where applicable. Register an application through Apps > Register New Application. Its App Title is the name clients see when asked to consent. Subscribe under API Products to the relevant Submission of Commission Records (Corppass) product and select that application. The linked general API user guide supplies the detailed account steps.
Sandbox evidence and production approval
Test in the sandbox first and subscribe to the Corppass Authentication API as well. Sandbox subscription itself needs no IRAS approval, but use IRAS’ published scenarios/entities. Successful test submissions provide acknowledgement codes; send each scenario’s code to data_mgmt@iras.gov.sg for verification. Only after passing testing may developers subscribe for production and obtain IRAS approval. Production is for actual stated-service use: testing and other uses are prohibited and can cause suspension or termination under the API terms.
Server connection, endpoints and headers
Use a server-to-server connection supporting HTTP/2, TLS1.2/1.3 and HTTP GET/POST. The commission method is POST /CommissionCP/submit under the sandbox base https://apisandbox.iras.gov.sg/iras/sb or production base https://apiservices.iras.gov.sg/iras/prod. Headers are X-IBM-Client-Id, X-IBM-Client-Secret, access_token and Content-Type: application/json. Obtain the JWT access token through the separate Corppass Authentication specification. It may be blank for validateOnly=true, while client credentials still apply. The source header sample says HTTP/1.1, whereas its network requirements state HTTP/2; retain that distinction when consulting the applicable live gateway requirements.
Payload limits and field conventions
Each request is capped at5,000 records or2MB total, whichever is reached first. JSON is case-sensitive and property names use camelCase. Unless expressly optional, every property must be specified. General date strings use ISO8601, but dateOfBirth is explicitly an eight-digit numeric YYYYMMDD field. String validation permits English letters/digits, spaces and the listed punctuation: backtick, @, #, parentheses, hyphen, comma, full stop, slash, &, + and underscore. String(n) is a maximum character count; Number(n) specifies the whole-number size. Use the request’s explicit field types rather than converting all numbers to strings.
Validation mode and basis year
The request contains orgAndSubmissionInfo and commissionEarnerDtl. validateOnly must be boolean true or false: true validates without filing, false validates and submits. basisYear is the income-accrual year, not the year of assessment; YA2021 therefore uses2020. The specification permits two past years, the current year and one advance year relative to the service’s year. An original batch uses O and an amendment uses A. The declared record count and total gross commission describe the earner details in that request.
Organisation identifiers and submitter details
Organisation ID types are7 UEN-BUSINESS,8 UEN-LOCAL CO,U UEN-OTHERS,A ASGD and I ITR. The source’s organisation formats are NNNNNNNNC,YYYYNNNNNC,TYYPQNNNNC or SYYPQNNNNC,ANNNNNNNC and NNNNNNNNNC respectively; C denotes check digit, N numeric and Y year. The submitter may use1 NRIC,2 FIN or A ASGD, with NRIC S/T prefixes and FIN F/G/M prefixes. The organisation and authorised-person fields, maximum lengths and optional designation appear in the table. Telephone must contain at least eight digits.
| Field | Type/limit | Requirement |
|---|---|---|
| validateOnly | Boolean | true/false; validation versus submission |
| basisYear | Number(4) | Income year; two prior/current/one future |
| organisationIDType | String(1) | 7,8,U,A,I |
| organisationIDNo | String(12) | Matching organisation identifier |
| authorisedPersonIDType | String(1) | 1,2,A |
| authorisedPersonIDNo | String(12) | NRIC/FIN/ASGD |
| authorisedPersonName | String(30) | Submitter name |
| authorisedPersonDesignation | String(30) | Optional designation |
| organisationName | String(60) | Organisation name |
| telephone | String(20) | At least8 digits |
| authorisedPersonEmail | String(50) | |
| batchIndicator | String(1) | O original/A amendment |
| numOfRecords | Number(4) | Integer count |
| totalGrossCommission | Number(15) | Integer gross total |
Earner identifiers and conditional personal fields
recordID starts at1 and must be unique. Earner idType accepts1 NRIC,2 FIN,5 Malaysian identity card,6 passport,7 business UEN,8 local-company UEN,A ASGD,I ITR or U other UEN. The source lists Malaysian IDs as7/8 alphanumeric or12 numeric characters. For types1/2/5/6, nationality, sex, designation and birth date must be supplied; these personal fields are absent in the corporate example. The listed common nationality codes are301 Singapore citizen,304 Malaysian and336 China; other codes are in the separately attached list. The payload table calls commissionEarnerDtl an Object, but its request example clearly uses an array of earner objects.
| Field | Type/limit | Requirement |
|---|---|---|
| recordID | Number(4) | Unique;start1 |
| idType | String(1) | 1,2,5,6,7,8,A,I,U |
| idNumber | String(12) | Corresponding ID |
| name | String(80) | Earner name |
| nationality | Number(3) | Required for1/2/5/6 |
| sex | String(1) | F/M for1/2/5/6 |
| designation | Number(1) | 1–9 for1/2/5/6 |
| dateOfBirth | Number(8) | YYYYMMDD for1/2/5/6 |
| grossCommission | Number(12) | No decimals/spaces;not0 |
All nine designation codes and gross amounts
Designation codes are1 remisier,2 real estate agent,3 insurance agent,4 distributor,5 financial advisor,6 instructor,7 therapist,8 Singapore Pools retailer and9 other. Sex uses F or M. grossCommission must be numeric, without spaces or decimals, and not zero; the source’s S$150,000.55 example sends150000, discarding cents. The batch total is integer-only as well. The earner UEN-OTHERS description uses TyyPQnnnnC/SyyPQnnnnC, whereas the organisation table uses TYYPQNNNNC/SYYPQNNNNC; retain the printed formats and validate against the authoritative identifier rules rather than inferring a universal pattern from that inconsistent character count.
Common return codes and error diagnostics
returnCode10 means successful processing and30 means failure. data holds service-specific results and info holds diagnostics. messageCode850300 denotes null request,850301 invalid arguments,850302 generic service exception,850303 inactive service,850304 unauthorised credentials and850305 invalid sandbox test user. fieldInfoList identifies each affected field, message and recordID. Earner record IDs sharing an error may be grouped as a comma-separated string such as3,5,7; recordID appears only for errors in an earner object. The tables use both info and Info spellings despite stating camelCase, so implementations should follow the actual case-sensitive response schema.
Submission acknowledgement versus validation success
Successful validateOnly=false responses include data.acknowledgementCode, returnCode10 and an empty fieldInfoList. Validation-only success instead has data as an empty object and does not establish that a filing occurred. Failed calls show returnCode30 and diagnostics, for example incorrect ID/type or missing name, with affected records. Page15’s descriptions refer to stamp-certificate references and latitude coordinates; these are inconsistent with the commission service and its response examples. Treat acknowledgementCode as the commission submission acknowledgement demonstrated by the examples, not as geographic data.
Examples and the C# transport pattern
The request example contains an organisation header plus two earner entries: one individual with personal details and one company, with gross amounts2000 and3000 and batch total5000. Sample request and success response contain trailing commas, which are not valid strict JSON; use a JSON serializer rather than copying them literally. The C# illustration creates a POST request, sets JSON content type and the three credential/token headers, writes JSON to the request stream, reads the response and handles WebException including any returned error body. It is a transport illustration, not a substitute for sandbox approval, payload validation or the separate authentication flow. Its comment refers to section3.1.1 although this document’s request fields are in4.2.
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 ↗