• 3.1.0 (16 September 2019)

  • New data items available:
    • cpfemployers
    • partialuinfin
  • New 'subentity' parameter in person API that allows traceability to platform's client who will be receiving the person data.
  • Provide clarity on the handling of housingtype & hdbtype

• 3.0.2 (10 May 2019)

  • Upper case all desc values for:
    • Driving Licence : Comstatus, PDL and QDL Validity
    • Children Birth Records: Sex
    • Sponsored Children Records: Sex, Residential Status
    • Person: Sex, Residential Status

• 3.0.1 (15 Apr 2019)
  • Removed serialno from pdl and qdl under drivinglicence as it is not in use.
  • Updated description for Understanding the Data Structure

• 3.0.0 (31 Mar 2019)

  IMPORTANT NOTE: response format for person API has substantial changes from the previous version. Please refer to Understanding the Data Structure for details.

  • APIs updated to v3:
    • Test:
      • /com/v3/authorise
      • /com/v3/token
      • /com/v3/person/{uinfin}/
      • /com/v3/person-sample/{uinfin}/
    • Production:
      • /com/v3/authorise
      • /com/v3/token
      • /com/v3/person/{uinfin}/
  • Response changes from JWE to JWE wrapping JWS
  • Security header (changes in Authorization header parameters)
    • Streamline header parameters to app_id, nonce, signature_method (RS256), signature, timestamp
  • Standardisation of 'code', 'desc' and 'value' of all data items.
  • New data items available:
    • employmentsector
    • passtype
    • hdbownership
    • sponsoredchildrenrecords
    • vehicles
    • drivinglicence
  • Rename data items:
    • workpassstatus -> passstatus
    • workpassexpirydate -> passexpirydate
  • Changes to the following data item to include "type" discriminator to discriminate local and foreign address. Format is significantly different between the two.
    • regadd
    • billadd
    • mailadd
  • Deprecated vehno attribute
  • Updated scheduled downtimes: sandbox and test enviroments will no longer have any scheduled downtimes.

• 2.2.1 (28 Dec 2018)

  • QR only login:
    • changes to support QR only login. login_type parameter must be provided in the authorise API call.

• 2.2.0 (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 v2.2.0, 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 v2.2.0, 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

  • Added link to MyInfo demo app under Support section for easy reference.

• 2.1.1 (21 September 2018)

  • updated error codes and descriptions for token and person APIs for better clarity when troubleshooting.

• 2.1.0 (01 July 2018)

  • "relationship" data item is deprecated
  • New data items available:
    • childrenbirthrecords
    • marriagecertno
    • countryofmarriage
    • workpassstatus
    • workpassexpirydate

• 2.0.0 (20 April 2018)

  • Base URL changed from:
    • myinfo.api.gov.sg to myinfosg.api.gov.sg (Production) and myinfosgstg.api.gov.sg (Staging)
  • APIs updated to v2:
    • Staging:
      • /test/v2/authorise
      • /test/v2/token
      • /test/v2/person/{uinfin}/
    • Production:
      • /v2/authorise
      • /v2/token
      • /v2/person/{uinfin}/
  • Updated responses for v2 Person APIs:
    • Response format will be JSON Web Encryption (JWE) instead of JSON Web Signature (JWS).

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.

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

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

The RESTful APIs are provided in both testing and live environments, and are 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' URLs is 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 = /com

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

• /{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 Person-Sample and Person API will return test data described in https://api.singpass.gov.sg/library/myinfo/developers/resources-personas.

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 Person-Sample API.
• Authorization Bearer access token is required in Person API.

2. Test Environment

The test enviroment is used for testing your application with the full security measures required in production. The Person API will return test data described in https://api.singpass.gov.sg/library/myinfo/developers/resources-personas.

Note:

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

Test Environment

• none

Sandbox Environment

• none

MyInfo'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 APIs using prior versions of TLS and/or unsupported ciphersuites will result in connectivity errors. MyInfo's 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 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 SingPass 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 (Person)

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

Access to all server-to-server APIs will be authenticated by MyInfo's API gateway. Prior to calling the APIs, 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's API gateway on internet:

• OAuth 2.0 using RS256 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:

PKI_SIGN app_id="{app_id}",
nonce="{random_nonce}",
signature_method="RS256",
signature="{base64_url_percent_encoded_signature}",
timestamp="{unix_epoch_in_milliseconds}"

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

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

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

• {signature_method} is the signature algorithm of the authenticating gateway.

  • Value of signature_method = RS256

• {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

Sample header with authorization parameters

Below is an example of an Authorization header for the sample application. Make sure you list the parameters in the sequence shown below.

  Authorization: PKI_SIGN
  app_id="STG2-MYINFO-SELF-TEST",
  nonce="150590021034800",
  signature_method="RS256",
  signature="EEm+HEcNQajb5FkVd82zjojk+daYZXxSGPCOR2GHZeoyjZY1PK+aFMzHfWu7eJZYMa5WaEwWxdOdq5hjNbl8kHD7bMaOks7FgEPdjE++TNomfv7SMktDnIvZmPYAxhjb/C9POU2KT6tSlZT/Si/qMgD1cryaPwSeMoM59UZa1GzYmqlkveba7rma58uGwb3wZFH0n57UnouR6LYXDOOLkqi8uMZBuvRUvSJRXETAj2N0hT+4QJiN96Ct6IEQh/woZh0o74K5Ol9PpDSM08qC7Lj6N/k694J+hbBQVVviGn7/6mDkfbwdMDuoKs4t7NpqmAnwT+xaQSIZcexfrAVQYA==",
  timestamp="1505900210349"

Sample Code in NodeJS

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

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

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

    // A) Construct the Authorisation Token Parameters
    var defaultAuthHeaders = {
      "app_id": appId, // App ID assigned to your application
      "nonce": nonceValue, // secure random number
      "signature_method": "RS256",
      "timestamp": timestamp // Unix epoch time
    };

    // 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(defaultAuthHeaders, 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 strAuthHeader = "PKI_SIGN app_id=\"" + appId + // Defaults to 1st part of incoming request hostname
      "\",timestamp=\"" + timestamp +
      "\",nonce=\"" + nonceValue +
      "\",signature_method=\"RS256\"" +
      ",signature=\"" + signature +
      "\"";

    return strAuthHeader;
  };

NOTE: 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 jwspayload = jwt.verify(jws, fs.readFileSync(publicCert, 'utf8'), {
        algorithms: ['RS256'],
        ignoreNotBefore: true
      });
      return jwspayload;
    }
    catch(error) {
      throw("Error with verifying and decoding JWS");
    }
  }

NOTE: Person APIs in Test and Production environments only

The response payload for the Person API (for test and production environments) is first signed, then encrypted:

• Signing is done using JWS (JSON Web Signature) format
• Encryption is done using JWE (JSON Web Encryption) Compact Serialization format

Encryption protects the data at rest while a signed payload means, if necessary, you will be able to pass this signed payload to a 3rd party where they can verify the payload's integrity with our public certificate.

In order to read the payload, you have to perform the following steps in order:

1. Decrypt the payload with your application's private key.
2. Validate the decrypted payload signature with our public key.

After doing the above steps, your application will be able to extract the payload in JSON format.

STEP 1: Decryption

• 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";
    })
  }

STEP 2: Verification of Signature

The decrypted payload is signed according to JWS (JSON Web Signature) format, similar to the access token.

• signature algorithm used is RS256.

Sample Code in NodeJS

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

MyInfo Person data follows a specific structure that you need to understand to traverse the data effectively. This section will explain the structure in detail.

The diagram below illustrates how the data is represented logically:

Each top-level data item can either be a data item object or an array of data item objects. Each data item object will consist of the following properties:

• classification (Data classification of data field. Default 'C' - Confidential)
• source (see below)
• lastupdated (Last updated date of data field. See "full-date" here)
• unavailable (in certain situations - see below)
• additional data properties containing data values or arrays

Data Source

The source property indicates the source of data. Possible values are:

• '1' - Government-verified
• '2' - User provided
• '3' - Field is Not Applicable to Person
• '4' - Verified by SingPass

Note: All Government-verified fields must be non-editable on your digital service form (some exceptions apply - see individual field descriptions).

In each data item, there can be multiple data properties or arrays of data properties.

Each data property will contain either:

• a value property, or
• a pair of code and desc properties, or
• an array of data properties, or
• other data properties

Note:

• value property can be strings, numbers, or dates.
• code and desc pairs will contain the code and its matching description.
• value is mutually exclusive from (code + desc); i.e. if there is a value, there will not be any code or desc.
• Where there is code, there will always be a desc - no value will be present.

Exceptions: For these cases, the values will be directly in the property and not in a value, code or desc subproperty:

• for data item metadata properties; e.g. classification, source, lastupdated, and unavailable
• for discriminator properties; e.g. type in address formats

Sometimes, a requested data item is not applicable to the person. Examples include:

• a foreigner will never have a regadd data item.
• a singapore citizen or permanent resident will never have passtype data item.

For a full list, refer to the "Data Catalog" section of MyInfo API Data in our portal.

Note: When a requested data item is not applicable to the person, the source property will be 3. In such cases, please ignore the data item completely.

Data Item Not Applicable

When a requested data item is not applicable to the entity:

• for data item objects, the source property will be 3
• for data item arrays, an empty array will be returned

In such cases, please ignore the data item completely.

Data Property Not Applicable

• When a data property is not applicable to the person, it will not appear in the schema of that particular entity type.
• Please check the Person schema to identify which data properties are not applicable to the person type.

In other situations, a requested data item might not have any data for that data item from the data source; i.e. data is unavailable. Examples include:

• when a person does not have any CPF contributions in the last 15 months
• when a person does not have any IRAS Notice of Assessments in the last 3 years
• when a person does not have any vehicles registered under them

Note: When a requested data item is unavailable:

• for data item objects, the data item will have the property unavailable with value true.
  In such cases, no additional properties (other than classification, source, and lastupdated) will be provided for the data item.
• for arrays of data items, an empty array will be returned.

Please display as "Not Available" in your form.

Data Item Unavailable

• for data item objects, the data item will have the property unavailable with value true.
  In such cases, no additional properties (other than classification, source, lastupdated) will be provided for the data item.
• for data item arrays, an empty array will be returned.

Please display as "Not Available" in your form.

Data Property Unavailable

• for data property objects, the value or code/desc will be empty value ("") or NaN.
• for arrays of data properties, an empty array will be returned.

The RESTful APIs used 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 NDI {api} Portal for the following supporting materials where relevant:

• MyInfo demo app
• 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.

RESTful API Definitions