To successfully integrate Smile into your process, we suggest doing so through 3 steps:

Requirements gathering - explore your use case and what do you want to achieve with Smile data
Design - design your user journey and integration with Smile.
Implementation & Go-Live (this guide) - detailed steps to set up and get the integration launched

Step 1: Implement Smile Wink

If you want the users to connect their employment accounts while they are on your website or app, you need to integrate the Smile Wink Widget. See below an example configuration to start:

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="icon" href="smileicon32.webp" sizes="32x32">
    <link rel="icon" href="smileicon192.webp" sizes="192x192">
    <title>Smile Wink</title>
</head>

<body>
    <script src="https://web.smileapi.io/v2/smile.v2.js"></script>
    <script type="text/javascript">
        const smileLinkModal = new SmileLinkModal({
            /**
             * The Link API URI. Note: Sandbox and Production modes use different API URIs.
             */
            apiHost: 'https://link-sandbox.smileapi.io/v1',

            /**
             * User token(link token) passed from your backend service which is obtained from the Smile API.
             */
            userToken: '<usertoken>',

            /**
             * Use the template ID to determine how your widget looks like embedded in your app or website.
             * You can find and create the template ID in the Smile developer-portal.
             * https://developer-portal.smileapi.io/link/template
             */
            templateId: "<ID of wink template >",

            /**
             * Account login callback.
             */
            onAccountCreated: ({ accountId, userId, providerId }) => {
                console.log('Account created: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
            },

            /**
             * Account login success callback.
             */
            onAccountConnected: ({ accountId, userId, providerId }) => {
                console.log('Account connected: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
            },

            /**
             * Account revoke callback.
             */
            onAccountRemoved: ({ accountId, userId, providerId }) => {
                console.log('Account removed: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
            },

            /**
             * Token expired callback.
             */
            onTokenExpired: () => {
                console.log('Token expired');
            },

            /**
             * Smile link SDK close callback.If you want to know which button the user clicked to trigger the close event, you can pass parameters like this.
             * onClose:({reason})=>{}
             * If the value of reason is equal to "close", it means that the user clicked the close icon in the upper right corner of the page to close the SDK
             * If the value of reason is equal to "exit", it means that the user clicked the DONE button on the connection page to close the SDK
             */
            onClose: ({ reason }) => {
                console.log('Link closed, reason:', reason)
            },

            /**
             * Account connect error callback.
             */
            onAccountError: ({ accountId, userId, providerId, errorCode }) => {
                console.log('Account error: ', accountId, ' User ID:', userId, ' Provider ID:', providerId, 'Error Code:', errorCode)
            },

            /**
             * Uploads submit callback.
             */
            onUploadsCreated: ({ uploads, userId }) => {
                console.log('Uploads: ', uploads, ' User ID:', userId);
            },

            /**
             * Uploads revoke callback.
             */
            onUploadsRemoved: ({ uploads, userId }) => {
                console.log('Uploads: ', uploads, ' User ID:', userId);
            },

            /**
             * User event callback is used to capture all the user activities from Smile Wink SDK
             */
            onUIEvent: ({ eventName, eventTime, mode, userId, account, archive }) => {
                console.log('eventName:', eventName,
                    "eventTime:", eventTime,
                    "mode:", mode,
                    "userId:", userId,
                    "account:", account,
                    "archive:", archive);
            }
        });
        smileLinkModal.open()
    </script>
</body>

</html>

Notice that the apiHost configuration parameter in the example code points to https://link-sandbox.smileapi.io/v1. This ensures that the plugin starts in a sandbox environment (the Sandbox Mode) where you can use the sandbox test credentials shown below to test the implementation.

User tokens (Link tokens)

User tokens are temporary (expires in 5 hours) access keys that allow you to start the Smile Linking process.

Link initialization for new user :

Create a new Smile user by calling the /users endpoint with metadata, such as your user identifier in your product/system. You will receive a Smile userId. We recommend storing this Smile userId in your system for future reference and use
Create a new user token by calling the /tokens endpoint with their userId. You will receive their userToken
Provide the userToken in your Smile Wink initialization. Make sure the user tokens are requested server-side and your client_id and client_secret are never exposed on the front-end.

Link initialization for a returning user or for refreshing the Link token

Obtain a new user token by calling the /tokens endpoint with their userId that you have previously stored.
Provide the userToken in your Smile Wink initialization. Make sure user tokens are requested server-side and your client_id and client_secret are never exposed on the front-end.

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="icon" href="smileicon32.webp" sizes="32x32">
    <link rel="icon" href="smileicon192.webp" sizes="192x192">
    <title>Smile Wink</title>
</head>

<body>
    <script src="https://web.smileapi.io/v2/smile.v2.js"></script>
    <script type="text/javascript">
        const smileLinkModal = new SmileLinkModal({
            /**
             * The Link API URI. Note: Sandbox and Production modes use different API URIs.
             */
            apiHost: 'https://link-sandbox.smileapi.io/v1',

            /**
             * User token passed from your backend service which is obtained from the Smile API.
             */
            userToken: '<usertoken>', // Put your user token here.

            // .....
        });
        smileLinkModal.open()
    </script>
</body>

</html>

Step 2: Connect test accounts

To use the Sandbox, you can use the following example credentials:

User Name	Full Name	Email	Mobile Phone	Password	Verification Code
George	George Palomero Jr.	[email protected]	(+63) 9559991234	123456	1234
Ryan	Ryan Ng	[email protected]	(+62) 8119994321	654321	1234
Christina	Christina Tan	[email protected]	(+65) 99996789	YGUS1	1234
Anisha	Anisha Bhatia	[email protected]	(+91) 9511198765	123456	1234

Before proceeding to the next step, make sure to test your implementation. Click on one of the providers on the provider list, and use one of the sandbox credentials to connect the selected provider.

Step 3: Retrieve identity, employment and contribution data

For personal information verification, fetch the following fields from the /identities endpoint:

First name
Last name
Primary address

Issue a GET request to Smile OpenAPI:

GET https://https://open-sandbox.smileapi.io/v1/identities?sourceId=<accountId>

# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.

Here is an example response:

{
  "id": "i-123abc456def789abc123def456abc78",
  "fullName": "George Cimafranca Palomero, Jr",
  "firstName": "George",
  "middleName": "Cimafranca",
  "lastName": "Palomero",
  "suffix": "Jr",
  "gender": "Male",
  "dob": "1970-08-24",
  "maritalStatus": "Married",
  "countryResidence": "PH",
  "citizenship": "Citizen",
  "photoUrl": "https://cdn.smileapi.io/image/avatar/v20211115191600/george.jpg",
  "referenceId": null,
  "profileUrl": null,
  "emails": [
    {
      "address": "[email protected]",
      "type": "Primary"
    }
  ],
  "phones": [
    {
      "number": "+639559991234",
      "type": "Mobile"
    }
  ],
  "socialProfiles": [
    {
      "socialUrl": "https://www.facebook.com/gpalomero1234",
      "type": "Facebook"
    }
  ],
  "addresses": [
    {
      "fullAddress": "12 Maybunga St, Barangay Paraiso, Pasig City, NCR, 1600, PH",
      "line1": "12 Maybunga St",
      "line2": "Barangay Paraiso",
      "city": "Pasig City",
      "region": "NCR",
      "zip": "1600",
      "country": "PH",
      "latitude": "14.573454",
      "longitude": "121.085042",
      "type": "Primary"
    }
  ],
  "metadata": {
    "createdAt": "2022-08-19T07:29:08Z",
    "sourceId": "a-123abc456def789abc123def456abc78",
    "sourceType": "ACCOUNT",
    "userId": "tenantId-123abc456def789abc123def456abc78",
    "providerId": "abccorp"
  }
}

For employment information verification, fetch the following fields from the /employments endpoint:

Employer name
Job title
Start date
End date

Issue a GET request to Smile OpenAPI:

GET https://https://open-sandbox.smileapi.io/v1/employments?sourceId=<accountId>
curl --request GET \
     --url 'https://sandbox.smileapi.io/v1/identities?size=10&sourceId=<accountId>' \
     --header 'accept: application/json' \
     --header 'authorization: Basic <authorization>'
# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.

Here is an example response:

[{
    "id": "e-123abc456def789abc123def456abc78",
    "startDate": "2022-07-01",
    "name": "Security",
    "description": null,
    "jobTitle": "Security Guard",
    "department": null,
    "employeeNumber": "EMP-123456",
    "employer": "ABC Corporation",
    "status": "Permanent",
    "endDate": "2022-07-31",
    "metadata": {
        "createdAt": "2022-09-01T01:44:18Z",
        "sourceId": "a-123abc456def789abc123def456abc78",
        "sourceType": "ACCOUNT",
        "userId": "tenantId-123abc456def789abc123def456abc78",
        "providerId": "abccorp",
        "accountId": "a-123abc456def789abc123def456abc78"
    }
}, {
    "id": "e-123abc456def789abc123def456abc78",
    "startDate": "2022-06-01",
    "name": "Security",
    "description": null,
    "jobTitle": "Security Guard",
    "department": null,
    "employeeNumber": "CDE-98765",
    "employer": "CDE Corporation",
    "status": "Permanent",
    "endDate": "2022-06-30",
    "metadata": {
        "createdAt": "2022-09-01T01:44:18Z",
        "sourceId": "a-123abc456def789abc123def456abc78",
        "sourceType": "ACCOUNT",
        "userId": "tenantId-123abc456def789abc123def456abc78",
        "providerId": "cdecorp",
        "accountId": "a-123abc456def789abc123def456abc78"
    }
}]

For contribution information verification, fetch the following fields from the /contributions endpoint:

Employer name
Job title
Start date
End date

Issue a GET request to Smile OpenAPI:

GET https://https://open-sandbox.smileapi.io/v1/employments?sourceId=<accountId>

# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.

Here is an example response:

[{
    "id": "con-123abc456def789abc123def456abc78",
    "date": "2022-06-30",
    "currency": "PHP",
    "amount": 2250,
    "referenceId": null,
    "metadata": {
        "createdAt": "2022-08-24T05:14:37Z",
        "sourceId": "a-123abc456def789abc123def456abc78",
        "sourceType": "ACCOUNT",
        "userId": "tenantId-123abc456def789abc123def456abc78",
        "providerId": "sss_ph",
        "accountId": "a-123abc456def789abc123def456abc78"
    }
}, {
    "id": "con-123abc456def789abc123def456abc78",
    "date": "2022-05-31",
    "currency": "PHP",
    "amount": 2250,
    "referenceId": null,
    "metadata": {
        "createdAt": "2022-08-24T05:14:37Z",
        "sourceId": "a-123abc456def789abc123def456abc78",
        "sourceType": "ACCOUNT",
        "userId": "tenantId-123abc456def789abc123def456abc78",
        "providerId": "sss_ph",
        "accountId": "a-123abc456def789abc123def456abc78"
    }
}, {
    "id": "con-123abc456def789abc123def456abc78",
    "date": "2022-04-30",
    "currency": "PHP",
    "amount": 2250,
    "referenceId": null,
    "metadata": {
        "createdAt": "2022-08-24T05:14:37Z",
        "sourceId": "a-123abc456def789abc123def456abc78",
        "sourceType": "ACCOUNT",
        "userId": "tenantId-123abc456def789abc123def456abc78",
        "providerId": "sss_ph",
        "accountId": "a-123abc456def789abc123def456abc78"
    }
}]

For additional data fields, please refer to the Smile API reference.

Step 4: Setup webhooks

To receive regular updates on a user's accounts, identity, contribution and employment data, subscribe to webhooks.

Webhooks send notifications to your system every time something occurs, i.e., when an account is connected, removed, or updated.

To monitor changes to identity, contribution and employment data, Smile recommends subscribing to the following webhook events, then call the Smile OpenAPI to retrieve data accordingly.

Event	Event Type	Description
Task Started	TASK_STARTED	Sent when the data sync process for a user's account is started.
Task Finished	TASK_FINISHED	Sent when the data sync task process for a user's account is finished, contains which datapoints have been synced

Or you can subscribe to dedicated datapoint related events

Event	Event Type	Description
Contributions Data Added	CONTRIBUTIONS_ADDED	Sent when social security contributions data shared by a user is added.
Estimated Incomes Data Added	EINCOMES_ADDED	Payload when estimated income data has been derived from data shared by a user.
Transactions Data Added	TRANSACTIONS_ADDED	Sent when transactions data shared by a user is added.
...	...	...

Step 5: Go live and scale

After a successful implementation and multiple successful tests in Sandbox Mode, you can switch to the Production mode for your launch.

Change the apiHost

Firstly, change the apiHost in your Wink configuration from:

https://link-sandbox.smileapi.io/v1

to:

https://link.smileapi.io/v1

The same logic applies to any Open API requests that you have previously used, so /employments for example:

GET https://open-sandbox.smileapi.io/v1/employments?sourceId={accountId}

change to:

GET https://open.smileapi.io/v1/employments?sourceId={accountId}

Change the API Key pair

The API Key pair can be found in the API Keys section of the Developer Portal . Use a production key when switching to Production Mode.

Start slow

For your first Production accounts, you can test on yourself with your own accounts, or create an account with a freelance gig platform (i.e. Upwork) and connect that account.

Launch and scale

After testing with your personal accounts, you can test with your real users. We recommend starting with a small subset of your users to make sure that everything is working as expected. Then, advance the subset gradually to your full user base.