• 0.2.5 (15 July 2019)

  • Updated description for entity appointments and shareholders category:
    • If appointment holder or shareholder does not fall in any of the listed categories, the field will return ""
      • 1 - Individual
      • 2 - Local Company
      • 3 - Foreign Company
      • 4 - Unregistered Local Entity
      • 5 - Limited Liability Partnerships
      • 6 - Unregistered Foreign Entity

• 0.2.4 (05 Dec 2018)

  • Base URL changes:

    • Production Environment: from myinfosg.api.gov.sg to api.myinfo.gov.sg
    • Test Environment: from myinfosgstg.api.gov.sg/test to test.api.myinfo.gov.sg
    • Sandbox Environment: from myinfosgstg.api.gov.sg/dev to sandbox.api.myinfo.gov.sg

  • Security header (.e. no longer needed in basestring)

    • Before v0.2.4, when crafting the basestring of the security header, an additional .e. is required in the domain name: e.g. myinfosgstg.api.gov.sg -> myinfosgstg.e.api.gov.sg.
      Note: This is no longer required
    • In v0.2.4, when crafting the basestring of the security header, the url in the basestring is the same as the one you call; e.g. api.myinfo.gov.sg
    • For more details, please refer to Security > Request Signing section for updated instructions.

  • Data items deprecated:

    • assessyear
    • assessableincome

  • New data items available:

    • noa(basic)
    • noa
    • noahistory(basic)
    • noahistory

• 0.2.3 (19 November 2018)
  • Updated Entity Type field to encompass more entity types.
  • Added Company Type and Business Constitution to give further breakdown to Company and Business entity types.

• 0.2.2 (9 November 2018)

  • Updated endpoint urls to end with /.

• 0.2.1 (29 August 2018)

  • Updated description for Nationality to include a note on known issue for Singapore PR (code value: SP).

• 0.2.0 (3 August 2018)

  • Added Entity-Person-Sample with no authentication for sandbox testing.
  • Re-ordered response schema from Entity-Person call such that Entity object is before Person object.

• 0.1.1 (24 July 2018)

  • Updated "sub" in access_token to have the format uen_uinfin
  • Updated description of uen and unifin path parameters of Entity-Person API indicating that value can be obtained from "sub" in decoded access_token.

• 0.1.0 (20 June 2018)

  • Initial Release for Pilot

The RESTful API adopts Semantic Versioning 2.0.0 for releases, and every new release of the API increments the version numbers in the following format:

{MAJOR}.{MINOR}.{PATCH}

1. {MAJOR} number introduces incompatible API changes with previous {MAJOR} number also resets {MINOR} to 0,
2. {MINOR} number introduces new functionalities or information that are backward compatible also resets {PATCH} to 0, and
3. {PATCH} number introduces bug fixes and remains backward compatible.

Pre-release or draft versions, when provided, are denoted by appended hypen - with a series of separate identifiers {LABEL}-{VERSION} following the {PATCH} number. Such releases are unstable and may not provide the intended compatibility with the specification in draft status.

Serving as notice, the RESTful API in version 2.X.X are incompatible with version 1.X.X releases.

Despite backward compatibility in {MINOR} or {PATCH} releases, API consumers are best to evaluate and determine their implementation does not disrupt use-case requirements.

• There is a known issue with the Nationality field, where the return value sometimes will be SP which refers to "Singapore Permanent Resident". This value will be moved to a separate "Residential Status" field in later releases.

The following diagram illustrates how the integration with MyInfo Business APIs work:

As shown above, your application will be interfacing with our API Gateway to integrate successfully with MyInfo Business.

The RESTful API provides both testing and live environments accessible over the Internet via HTTPS.

Consumers are to ensure firewall clearance on their edge network nodes for connecting to the APIs.

The convention used by API endpoints' URL are in the following format:

https://{ENV_DOMAIN_NAME}/{CONTEXT}/{VERSION}/{RESOURCE}

• {ENV_DOMAIN_NAME} indicates MyInfo's API domain names - respectively:

  • sandbox.api.myinfo.gov.sg, or
  • test.api.myinfo.gov.sg, or
  • api.myinfo.gov.sg, following

• /{CONTEXT}, indicates the context of the API call = /biz

• /{VERSION} indicates the endpoint's release {MAJOR} version number path - for this release = /v2

• /{RESOURCE} indicates the API resource path name.

Any additional query string parameters are appended as needed.

1. Sandbox Environment

The sandbox environment is used for your testing when developing your prototype. The Entity-Person-Sample and Entity-Person API will return test data previously shared by our officer via email. For test data matters, please contact us.

Note:

• Domain Name: sandbox.api.myinfo.gov.sg
• PKI digital signature is not required for all APIs.
• Authorization Bearer access token is not required in Entity-Person-Sample API.
• Authorization Bearer access token is required in Entity-Person API.

2. Test Environment

The test enviroment is used for testing your application with the full security measures required in production. The Entity-Person API will return test data previously shared by our officer via email. For test data matters, please contact us.

Note:

• Domain Name: test.api.myinfo.gov.sg
• PKI digital signature is required for Token and Entity-Person APIs.
  Refer to Security > Request Signing for the steps to sign your request.
• Authorization Bearer access token is required in Entity-Person API.

3. Production Environment

The production enviroment is the actual live environment with full security measures and live data.

Note:

• Domain Name: api.myinfo.gov.sg
• PKI digital signature is required for Token and Entity-Person APIs.
  Refer to Security > Request Signing for the steps to sign your request.
• Authorization Bearer access token is required in Entity-Person API.

The following are the scheduled downtimes for the various environments:

Production Environment

• CPFB data - Everyday 5:00am to 5:30am
• IRAS data - Every Wed, 2:00am to 6:00am, Every Sun, 2:00am to 8:30am
• Once a month, Sunday 12:00 am to 8:00 am (date to be advised)

Sandbox Environment

• Every Wednesday 3pm to 12am.

Test Environments

• Every Wednesday 3pm to 12am.

MyInfo Business's API gateway supports accessing of APIs via the following interfaces:

• HTTP version 1.1 connection over TLS (Transport Layer Security) version 1.1 or 1.2 standards, and ciphersuites:

  • using AES (Advanced Encryption Standard) and SHA (Secure Hash Algorithm),
  • on either GCM (Galois/Counter Mode) or CBC (Cipher Block Chaining) mode.

• Below is the list of recommended cipher suites that you may use:

  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_128_CBC_SHA

IMPORTANT: ensure your server supports TLS 1.1 or 1.2 and supports a cipher suite in the list above.

Accessing the RESTful API using prior versions of TLS or unsupported ciphersuites will result in connectivity errors. MyInfo Business' API gateway does not support 2-way TLS client nor mutual authentication.

API HTTP interface features:

1. JSON (JavaScript Object Notation) is the supported data media format and indicated in Content-Type header application/json, also
2. Content-Length header is omitted by having Transfer-Encoding header chunked emitted for streaming data, and
3. GZip (GNU Zip) response compression is supported by opt-in Accept-Encoding: gzip and indicated in Content-Encoding header gzip.

MyInfo Business APIs use OAuth2.0 authorisation code flow to perform authentication & authorisation.

The sequence diagram below illustrates the steps involved in integrating your application with our APIs:

The flow consists of 3 APIs:

1. Authorise

   • This will trigger the CorpPass login and consent page. Once successful, your application will receive the authorisation code via your callback url.

2. Token

   • Call this server-to-server API with a valid authorisation code to get the access token.

3. Protected Resource (Entity-Person)

   • Call this server-to-server API with a valid access token to get the entity and person data.

Access to all server-to-server APIs will be authenticated by MyInfo Business' API gateway. Prior to consumption of API, respective consumers are required to have:

• approval of access, onboarding process for the required API resources will be provisioned, and
• authentication credentials are then supplied and exchanged.

Authentication methods provided by MyInfo Business' API gateway on internet:

• OAuth 2.0 using SHA256withRSA digital signature (see "Request Signing" section below)
• Digital signature should be produced using a RSA private key with corresponding public certificate issued by one of the following compatible CAs:
  • digiCert
  • Entrust
  • Comodo
  • VeriSign
  • GlobalSign
  • GeoTrust
  • Thawte

NOTE: Test and Production Environments only

All server-to-server API requests are to be digitally signed, by including the following parameters and values in the Authorization header:

Apex_L2_Eg realm="{realm}",
apex_l2_eg_app_id="{app_id}",
apex_l2_eg_nonce="{random_nonce}",
apex_l2_eg_signature_method="SHA256withRSA",
apex_l2_eg_signature="{base64_url_percent_encoded_signature}",
apex_l2_eg_timestamp="{unix_epoch_in_milliseconds}",
apex_l2_eg_version="1.0"

Note: above sample is separated by lines for ease-of-reading, and new-line denotations are to be omitted in the actual request.

• {realm} is the logical name of your application.

• {app_id} is the APP ID credential supplied upon onboarding,

• {random_nonce} is an unique randomly generated text used for replay prevention,

• {signature_algorithm} is the signature algorithm of the authenticating API gateway.

  • Value of signature_algorithm = SHA256withRSA

• {base64_url_percent_encoded_signature} is the binary of the generated signature encoded in Base64 URL-safe format,

• {unix_epoch_in_milliseconds} is the UNIX epoch time in milliseconds, and

• apex_l2_eg_version="1.0" parameter is optional, and when emitted the value has to be 1.0.

Sample Code in NodeJS

  // generates the security headers for calling API Gateway
  function generateAuthorizationHeader(url, params, method, strContentType, authType, appId, keyCertContent, passphrase, realm) {

    if (authType == "L2") {
      return generateSHA256withRSAHeader(url, params, method, strContentType, appId, keyCertContent, passphrase, realm);
    } else {
      return "";
    }
  };

  // Signing Your Requests
  function generateSHA256withRSAHeader(url, params, method, strContentType, appId, keyCertContent, keyCertPassphrase, realm) {
    var nonceValue = nonce();
    var timestamp = (new Date).getTime();

    // A) Construct the Authorisation Token Parameters
    var defaultApexHeaders = {
      "apex_l2_eg_app_id": appId, // App ID assigned to your application
      "apex_l2_eg_nonce": nonceValue, // secure random number
      "apex_l2_eg_signature_method": "SHA256withRSA",
      "apex_l2_eg_timestamp": timestamp, // Unix epoch time
      "apex_l2_eg_version": "1.0"
    };

    // B) Forming the Base String
    // Base String is a representation of the entire request (ensures message integrity)

    // i) Normalize request parameters
    var baseParams = sortJSON(_.merge(defaultApexHeaders, params));

    var baseParamsStr = qs.stringify(baseParams);
    baseParamsStr = qs.unescape(baseParamsStr); // url safe

    // ii) concatenate request elements (HTTP method + url + base string parameters)
    var baseString = method.toUpperCase() + "&" + url + "&" + baseParamsStr;

    // C) Signing Base String to get Digital Signature
    var signWith = {
      key: fs.readFileSync(keyCertContent, 'utf8')
    }; // Provides private key

    // Load pem file containing the x509 cert & private key & sign the base string with it to produce the Digital Signature
    var signature = crypto.createSign('RSA-SHA256')
      .update(baseString)
      .sign(signWith, 'base64');

    // D) Assembling the Authorization Header
    var strApexHeader = "apex_l2_eg realm=\"" + realm + // Defaults to 1st part of incoming request hostname
      "\",apex_l2_eg_timestamp=\"" + timestamp +
      "\",apex_l2_eg_nonce=\"" + nonceValue +
      "\",apex_l2_eg_app_id=\"" + appId +
      "\",apex_l2_eg_signature_method=\"SHA256withRSA\"" +
      ",apex_l2_eg_version=\"1.0\"" +
      ",apex_l2_eg_signature=\"" + signature +
      "\"";

    return strApexHeader;
  };

NOTE: Entity-Person APIs only

Access Tokens are in JWT format. This JWT complies to the standard 'JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants' (https://tools.ietf.org/html/rfc7523). You will need to verify the token with our public cert (provided during application onboarding).

Sample Code in NodeJS

  // Sample Code for Verifying & Decoding JWS or JWT
  function verifyJWS(jws, publicCert) {
    // verify token
    // ignore notbefore check because it gives errors sometimes if the call is too fast.
    try {
      var decoded = jwt.verify(jws, fs.readFileSync(publicCert, 'utf8'), {
        algorithms: ['RS256'],
        ignoreNotBefore: true
      });
      return decoded;
    }
    catch(error) {
      throw("Error with verifying and decoding JWS");
    }
  }

NOTE: Entity-Person APIs in Test and Production environments only

The response payload for the Entity-Person API (for staging and production environments) is encrypted in JWE (JSON Web Encryption) Compact Serialization format.

• Encryption is done using your application's public key that you provided during onboarding. Decryption of the payload should be using the private key of that key-pair.
• Current encryption algorithms used:
  • RSA-OAEP (for content key wrapping)
  • AES256GCM (for content encrytion)

Sample Code in NodeJS

  // Sample Code for decrypting JWE
  // Decrypt JWE using private key
  function decryptJWE(header, encryptedKey, iv, cipherText, tag, privateKey) {

    return new Promise((resolve, reject) => {

      var keystore = jose.JWK.createKeyStore();

      var data = {
        "type": "compact",
        "ciphertext": cipherText,
        "protected": header,
        "encrypted_key": encryptedKey,
        "tag": tag,
        "iv": iv,
        "header": JSON.parse(jose.util.base64url.decode(header).toString())
      };
      keystore.add(fs.readFileSync(privateKey, 'utf8'), "pem")
        .then(function(jweKey) {
          // {result} is a jose.JWK.Key
          jose.JWE.createDecrypt(jweKey)
            .decrypt(data)
            .then(function(result) {
              resolve(JSON.parse(result.payload.toString()));
            })
            .catch(function(error) {
              reject(error);
            });
        });

    })
    .catch (error => {
      throw "Error with decrypting JWE";
    })
  }

In the response of Entity-Person API, each data item under the Person object comes with the following general structure:

The RESTful API(s) uses HTTP specification standard status codes to indicate the success or failure of each request. Except gateway errors, the response content will be in the following JSON format:

{
    "code": "integer (int32)",
    "message": "string"
}

Refer to the individual API definitions for the error codes you might encounter for each API.

Please refer to the links below for the following supporting materials where relevant:

• Code reference tables (for Entity object)
• Code reference tables
• Test accounts for test environments
• Reference user journey templates

For technical queries, contact support@myinfo.gov.sg. For business queries, contact partner@myinfo.gov.sg.

Entity-Person API resource operations to access corporate entity and person details.