logo
Documentation Powered by ReDoc

MyInfo Business (0.2.5)

Download OpenAPI specification:Download

MyInfo Business REST APIs for retrieving Entity and Person data.

Note - this specification is subject to changes based on evolution of the APIs.

Release Notes

  • 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

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

  • 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

Releases and Compatibility

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.

Known Issues

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

Overview

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

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

Environments

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.

Available Environments

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.

Scheduled Downtimes

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.

Security

HTTPS Interface

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.

OAuth2.0

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:

OAuth

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.

Application Authentication

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

Request Signing

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;
  };

Token Validation

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

Payload Encryption (Entity-Person)

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

Data Item Structure

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

Field Name Description
value Value of data field (if applicable).
Refer to the schema in the specifications for details.
code Value of data field in code (if applicable).
Refer to the schema in the specifications for details.
desc Description code of data field (if applicable).
Refer to the schema in the specifications for details.
classification Data classification of data field. Default 'C' - Confidential.
source Source of data.
  • '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).
lastupdated Last updated date of data field. See "full-date" in http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14

Note: The above applies for data in the "person" object only, not the "entity" object in the response. See schema in specifications below for details.

Error Handling

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.

Support

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

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

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

Authentication

oauth2

The following are the available OAuth2 scopes for MyInfo Business APIs

Security scheme type: OAuth2
authorizationCode OAuth Flow
Authorization URL: /authorise
Token URL: /token
Scopes:
  • basic-profile -

    (Entity) Basic Entity Profile

  • previous-names -

    (Entity) Previous Names

  • previous-uens -

    (Entity) Previous UENs

  • addresses -

    (Entity) Addresses

  • financials -

    (Entity) Financials

  • capitals -

    (Entity) Capitals

  • appointments -

    (Entity) Appointments

  • shareholders -

    (Entity) Shareholders

  • grants -

    (Entity) Grants

  • name -

    (Person) Full Name

  • hanyupinyinname -

    (Person) Han Yu Pin Yin name

  • aliasname -

    (Person) Alias name

  • hanyupinyinaliasname -

    (Person) Han Yu Pin Yin Alias name

  • marriedname -

    (Person) Married name

  • sex -

    (Person) Sex

  • race -

    (Person) Race

  • secondaryrace -

    (Person) Secondary Race

  • dialect -

    (Person) Dialect

  • nationality -

    (Person) Nationality

  • dob -

    (Person) Date of Birth

  • birthcountry -

    (Person) Country of Birth

  • residentialstatus -

    (Person) Residential Status

  • passportnumber -

    (Person) Passport Number

  • passportexpirydate -

    (Person) Passport Expiry Date

  • regadd -

    (Person) Registered Address

  • mailadd -

    (Person) Mailing Address

  • billadd -

    (Person) Billing Address

  • housingtype -

    (Person) Housing Type

  • hdbtype -

    (Person) HDB Type

  • ownerprivate -

    (Person) Ownership of Private Property Status

  • email -

    (Person) Email Address

  • homeno -

    (Person) Home Contact Number

  • mobileno -

    (Person) Mobile Number

  • marital -

    (Person) Marital Status

  • marriagecertno -

    (Person) Certificate number of the latest marriage

  • countryofmarriage -

    (Person) Country of the latest marriage

  • marriagedate -

    (Person) Latest Marriage Date

  • divorcedate -

    (Person) Last Divorce Date

  • childrenbirthrecords -

    (Person) Details of Children Birth Records

  • edulevel -

    (Person) Highest Education Level

  • gradyear -

    (Person) Year of Graduation

  • schoolname -

    (Person) Name of School

  • occupation -

    (Person) Occupation

  • employment -

    (Person) Employer's Name

  • workpassstatus -

    (Person) Work pass status of a FIN holder

  • workpassexpirydate -

    (Person) Work pass expiry of a foreigner

  • householdincome -

    (Person) Household Income

  • assessableincome -

    (Person) Latest Assessable Income

  • assessyear -

    (Person) Year of Assessment (for Assessable Income)

  • noa(basic) -

    (Person) Notice Of Assessment (Basic)

  • noa -

    (Person) Notice Of Assessment

  • noahistory(basic) -

    (Person) History of Notice Of Assessment (Basic)

  • noahistory -

    (Person) History of Notice Of Assessment

  • cpfcontributions -

    (Person) Employer CPF Contributions

  • cpfbalances -

    (Person) CPF Balances

  • vehno -

    (Person) Vehicle Number

MyInfo Business

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

Entity-Person-Sample

Retrieves a sample Entity-Person data from MyInfo Business based on UEN and UIN/FIN.

This API does not use OAuth2.0 to perform authentication or authrisation, and does not require authorisation token and digital signature.

Note: Null value indicates that an attribute is unavailable.

path Parameters
uen
required
string <= 10 characters
Example: "T15LP0010D"

Required URL path parameter of the entity's unique entity number. This value can be obtained from the sub (uen_uinfin) in the decoded access_token.

uinfin
required
string <= 9 characters
Example: "S9203266C"

Required URL path parameter of the person's uinfin. This value can be obtained from the sub (uen_uinfin) in the decoded access_token.

query Parameters
txnNo
string

Transaction ID from requesting digital services for cross referencing.

attributes
required
Array of string
Example: "addresses,basic-profile,name,hanyupinyinname"

Comma separated list of attributes requested. Possible attributes are listed in the scopes of the OAuth2 Security Schema above.

client_id
required
string

Unique ID for your application.

Responses

200

OK.

Note:

  • Response Content-Encoding will be 'gzip'.
  • Response Content-Type will be 'application/jose', which is a JSON object conforming to the JWE standard (https://tools.ietf.org/html/rfc7516).
  • Your application should decrypt the signature with your application's private key.
  • After decrypting the signature, your application will be able to extract the payload in JSON format.
401

Unauthorized. This could be due to the scenarios below:

  • SCENARIO 1: Requested 'uen'/'uinfin' does not match the 'uen'/'uinfin' of the person of the entity who logged in. When requesting for data of Person A and Entity A, the CorpPass login and consent must be by Person A from Entity A as well.
  • SCENARIO 2: Requested attributes does not match the attributes consented by person. This happens if the list of attributes in your request are different from the attributes specified when calling the token endpoint.
  • SCENARIO 3: Request contains attributes that are not allowable for the digital service. This happens when you request for attributes that are not allowed for your application. The list of allowable attributes for your application are preconfigured during the onboarding process.

Details will be given in the error object returned.

403

Forbidden. Digital service is not registered with MyInfo Business.

MESSAGE: 'Digital Service is invalid'

404

Not Found. UIN/FIN and/or UEN does not exist in MyInfo Business.

MESSAGE: 'UIN/FIN and/or UEN is invalid.'

428

Profile Incomplete. User/Entity registered for MyInfo Business less than 1 working day.

MESSAGE: 'Profile Incomplete'

500

Error with request parameters or headers. Error details will be provided in the response body

get /biz/v1/entity-person-sample/{uen}/{uinfin}/
Sandbox
https://sandbox.api.myinfo.gov.sg/biz/v1/entity-person-sample/{uen}/{uinfin}/

Request samples

Copy
curl https://sandbox.api.myinfo.gov.sg/biz/v1/entity-person-sample/T15LP0010D/S9203266C

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "entity":
    {
    },
  • "person":
    {
    }
}

Authorise

This API triggers CorpPass login and obtain consent for the MyInfo Business to retrieve person and entity data from MyInfo Business. Once the user has authenticated and consented, an authorisation code (authcode) will be returned together with the state for verification via the callback URL defined. The authcode can then be used to retrieve an access token via the Token API.

Note: This API is public and should be implemented as a link or button on your online webpage.

query Parameters
authmode
string
Default: "CORPPASS"
Enum:"CORPPASS" "MOBILEID"

Mode of authentication used to obtain user consent. Default is "CORPPASS".

purpose
required
string

State the purpose for requesting the data. This will be shown to the user for his consent.

response_type
string
Default: "code"

Response type for authorisation code flow - must be "code".

attributes
required
Array of string
Example: "addresses,basic-profile,name,hanyupinyinname"

Comma separated list of attributes requested. Possible attributes are listed in the scopes of the OAuth2 Security Schema above.

state
required
string

Identifier to reconcile query and response. This will be sent back to you via the callback URL. Use a unique system generated number for each and every call.

redirect_uri
required
string

Your callback URL for MyInfo Business to return with the authorisation code.

client_id
required
string
Example: "STG-180099999K-TEST01"

Unique ID for your application.

Responses

302

Service will redirect all responses to 'redirect_uri' with additional parameters added as response results. Expected parameters include:

  • code: this is the authorisation code you will use when calling the token endpoint
  • state: this should be the same state passed in your initial URL.
  • error: if there are any errors encountered, the error code will be given in this parameter. If user did not give consent, error value will be 'access_denied', and refer to error_description parameter for the reason.
  • error_description: if error is 'access_denied' i.e. user did not give consent, the description will be 'Resource Owner did not authorize the request'.

Error Codes

  • '404' - User/Entity not found or not registered with MyInfo Business.
  • '428' - Profile Incomplete. User/Entity registered for MyInfo Business less than 1 working day.
  • '500' - Unknown or other server side errors.
  • '503' - MyInfo Business under maintenance. Error description will also be given in error_description parameter. Note: If user closes the browser window prematurely, there will be no callback to the 'redirect_uri'. Therefore it is important for you to check the 'state' to verify that the transaction is the same.
get /biz/v1/authorise
Sandbox
https://sandbox.api.myinfo.gov.sg/biz/v1/authorise
Test
https://test.api.myinfo.gov.sg/biz/v1/authorise
Production
https://api.myinfo.gov.sg/biz/v1/authorise

Request samples

Copy
function callAuthoriseApi() {
  var authoriseUrl = authApiUrl + "?client_id=" + clientId +
    "&attributes=" + attributes +
    "&purpose=" + purpose +
    "&state=" + state +
    "&redirect_uri=" + redirectUrl;

  window.location = authoriseUrl;
}

Token

This API generates an access token when presented with a valid authcode obtained from the Authorise API. This token can then be used to request for the person and entity data that were consented.

header Parameters
Authorization
required
string

Add token constructed containing the RSA digital signature of the base string. Refer to Security > Request Signing on how this token should be generated.

Note: This header is not required when calling Sandbox API.

Request Body schema: application/x-www-form-urlencoded
code
required
string

The authcode given by the authorise API.

grant_type
string
Default: "authorization_code"

Grant type for getting token (default "authorization_code")

client_secret
required
string

Secret key given to your application during onboarding.

client_id
required
string

Unique ID for your application.

redirect_uri
required
string

Your callback URL for MyInfo or MyInfo Business to validate.

Responses

200

OK. returning a JSON object which contains the authorisation access token (JWT) that will be used to retrieve the data from MyInfo Business.

400

AuthCode error - missing, invalid, expired, revoked

500

Unexpected error. Error message will be in the response body

post /biz/v1/token
Sandbox
https://sandbox.api.myinfo.gov.sg/biz/v1/token
Test
https://test.api.myinfo.gov.sg/biz/v1/token
Production
https://api.myinfo.gov.sg/biz/v1/token

Request samples

Copy
// function to prepare request for TOKEN API
function createTokenRequest(code) {
  var cacheCtl = "no-cache";
  var contentType = "application/x-www-form-urlencoded";
  var method = "POST";
  var request = null;

  // preparing the request with header and parameters
  // assemble params for Token API
  var strParams = "grant_type=authorization_code" +
    "&code=" + code +
    "&redirect_uri=" + _redirectUrl +
    "&client_id=" + _clientId +
    "&client_secret=" + _clientSecret;
  var params = querystring.parse(strParams);


  // assemble headers for Token API
  var strHeaders = "Content-Type=" + contentType + "&Cache-Control=" + cacheCtl;
  var headers = querystring.parse(strHeaders);

  // Sign request and add Authorization Headers
  var authHeaders = generateAuthorizationHeader(
    _tokenApiUrl,
    params,
    method,
    contentType,
    _authLevel,
    _clientId,
    _privateKeyContent,
    _clientSecret,
    _realm
  );

  if (!_.isEmpty(authHeaders)) {
    _.set(headers, "Authorization", authHeaders);
  }

  var request = restClient.post(_tokenApiUrl);

  // Set headers
  if (!_.isUndefined(headers) && !_.isEmpty(headers))
    request.set(headers);

  // Set Params
  if (!_.isUndefined(params) && !_.isEmpty(params))
    request.send(params);

  return request;
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "token_type": "Bearer",
  • "id_token": "string",
  • "access_token":
    {
    }
}

Entity-Person

This API returns person and entity data from MyInfo Business when presented with a valid access token obtained from the Token API.

Note: Null value indicates that an attribute is unavailable.

Authorizations:
oauth2
path Parameters
uen
required
string <= 10 characters
Example: "T15LP0010D"

Required URL path parameter of the entity's unique entity number. This value can be obtained from the sub (uen_uinfin) in the decoded access_token.

uinfin
required
string <= 9 characters
Example: "S9203266C"

Required URL path parameter of the person's uinfin. This value can be obtained from the sub (uen_uinfin) in the decoded access_token.

query Parameters
txnNo
string

Transaction ID from requesting digital services for cross referencing.

attributes
required
Array of string
Example: "addresses,basic-profile,name,hanyupinyinname"

Comma separated list of attributes requested. Possible attributes are listed in the scopes of the OAuth2 Security Schema above.

client_id
required
string
Example: "STG-180099999K-TEST01"

Unique ID for your application.

header Parameters
Authorization
required
string

Add authorization token constructed containing the RSA digital signature of the base string. Refer to Security > Request Signing on how this token should be generated. Also include the access token (JWT) from /token API in your header prefixed with 'Bearer'.

Note: Only the Bearer token is required when calling Sandbox API.

Responses

200

OK.

Note:

  • Response Content-Encoding will be 'gzip'.
  • Response Content-Type will be 'application/jose', which is a JSON object conforming to the JWE standard (https://tools.ietf.org/html/rfc7516).
  • Your application should decrypt the signature with your application's private key.
  • After decrypting the signature, your application will be able to extract the payload in JSON format.
401

Unauthorized. This could be due to the scenarios below:

  • SCENARIO 1: Requested 'uen'/'uinfin' does not match the 'uen'/'uinfin' of the person of the entity who logged in. When requesting for data of Person A and Entity A, the CorpPass login and consent must be by Person A from Entity A as well.
  • SCENARIO 2: Requested attributes does not match the attributes consented by person. This happens if the list of attributes in your request are different from the attributes specified when calling the token endpoint.
  • SCENARIO 3: Request contains attributes that are not allowable for the digital service. This happens when you request for attributes that are not allowed for your application. The list of allowable attributes for your application are preconfigured during the onboarding process.

Details will be given in the error object returned.

403

Forbidden. Digital service is not registered with MyInfo Business.

MESSAGE: 'Digital Service is invalid'

404

Not Found. UIN/FIN and/or UEN does not exist in MyInfo Business.

MESSAGE: 'UIN/FIN and/or UEN is invalid.'

428

Profile Incomplete. User/Entity registered for MyInfo Business less than 1 working day.

MESSAGE: 'Profile Incomplete'

500

Error with request parameters or headers. Error details will be provided in the response body

get /biz/v1/entity-person/{uen}/{uinfin}/
Sandbox
https://sandbox.api.myinfo.gov.sg/biz/v1/entity-person/{uen}/{uinfin}/
Test
https://test.api.myinfo.gov.sg/biz/v1/entity-person/{uen}/{uinfin}/
Production
https://api.myinfo.gov.sg/biz/v1/entity-person/{uen}/{uinfin}/

Request samples

Copy
// function to prepare request for PERSON API
function createPersonRequest(uinfin, validToken) {
  var url = _personApiUrl + "/" + uinfin + "/";
  var cacheCtl = "no-cache";
  var method = "GET";
  var request = null;
  // assemble params for Person API
  var strParams = "client_id=" + _clientId +
    "&attributes=" + _attributes;
  var params = querystring.parse(strParams);

  // assemble headers for Person API
  var strHeaders = "Cache-Control=" + cacheCtl;
  var headers = querystring.parse(strHeaders);
  var authHeaders;

  // Sign request and add Authorization Headers
  authHeaders = generateAuthorizationHeader(
    url,
    params,
    method,
    "", // no content type needed for GET
    _authLevel,
    _clientId,
    _privateKeyContent,
    _clientSecret,
    _realm
  );

  if (!_.isEmpty(authHeaders)) {
    _.set(headers, "Authorization", authHeaders + ",Bearer " + validToken);
  }
  else {
    // NOTE: include access token in Authorization header as "Bearer " (with space behind)
      _.set(headers, "Authorization", "Bearer " + validToken);
  }

  // invoke token API
  var request = restClient.get(url);

  // Set headers
  if (!_.isUndefined(headers) && !_.isEmpty(headers))
    request.set(headers);

  // Set Params
  if (!_.isUndefined(params) && !_.isEmpty(params))
    request.query(params);

  return request;
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "entity":
    {
    },
  • "person":
    {
    }
}