Getting Started

Smile Signals provides a powerful Risk Screening solution by delivering real-time risk signals using a person's mobile number or email address, from a wide variety of activities and events, to keep up to date in today's fast-paced financial landscape where accurate and timely risk assessment is crucial for making informed decisions.

The suite of Signals APIs can provide access to hundreds of risk signals, allowing you to pick and choose the signals that make sense for your use case and market segment.

Choose from the current suite of Signals:

About Billing

Charges apply only to Create requests for each product

• For example, for Footprints, only the POST /alpha/footprints request is counted for billing. List and Get requests are not charged.

Billing Logic for Create Requests

• Assume the POST response JSON is represented as a response object. The table below outlines the billing logic for different billing models.

{
  "code": "OK",
  "message": "xxx",
  "requestId": "<requestId>",
  "data": {
    "id": "xxxx",
    "status": "COMPLETED", 
    "resultCode": "SUCCESS",
    "resultMessage": "xxxxx",
    "requestMeta": {},
    "items": []
  }
}

Notes:

• data.status and data.resultCode are the fields used for billing evaluation
• For the Per Request billing model, resultCode may be either SUCCESS or NO_DATA

About Synchronous and Asynchronous API

Smile API supports two request processing modes: Synchronous and Asynchronous. Developers can choose the appropriate response mechanism based on their business requirements.

Synchronous Requests

For synchronous requests, the API returns the complete processing result directly after the request is successfully handled. No additional configuration is required.

Process flow:

• The client sends an API request
• Smile API completes the resource processing
• The API response directly returns the processing result

Asynchronous Requests

Asynchronous requests do not return the processing result immediately. Instead, the final result is delivered via Webhook events after the resource has been fully processed.

• Prerequisites for Asynchronous Requests
  • You must subscribe to the relevant Webhook events in the Smile Developer Portal(please refer to the list of currently available Signals packages).
  • For supported Webhook events and detailed specifications, please refer to the Webhooks Documentation.
  • Ensure that your system is capable of receiving and processing Webhook callback requests.
• Asynchronous Request Flow
  • The client sends an API request
  • Upon successful request submission, the API immediately returns the current resource ID (e.g. verificationId)
  • Smile processes the resource asynchronously in the background
  • Once processing is complete, Smile delivers the final result to your Webhook endpoint via the subscribed Webhook event
• Notes
  • In asynchronous mode, a successful API response does not indicate that the resource processing has been completed
  • Always rely on the Webhook event notification as the final processing result
  • It is recommended to implement status tracking and idempotent handling based on the returned resource ID

Integration Steps

Integrating Smile API’s risk screening services into your system can be completed in just a few simple steps. We recommend following the process below to complete integration and validation.

1. Prerequisites

Before starting the integration, please ensure that:

• You have registered an account on the Smile Developer Portal
• You have basic experience with API integration and HTTP requests
• Your system can securely store and manage API credentials (API Key / API Secret)

2. Obtain API Credentials

All Smile API requests must include authorization information in the HTTP request headers. Smile uses Basic Authentication (Basic Auth) for request authentication.

• Steps:
  • Log in to the Smile Developer Portal
  • Create and obtain your API Key and API Secret
  • Encode API Key:API Secret using Base64 and include it in the request header For detailed authentication instructions, please refer to: API Authentication.

3. Test APIs in the Sandbox Environment

Smile provides a Sandbox environment for development and functional testing. It is strongly recommended to complete Sandbox testing before going live.

• The Sandbox environment supports the full API workflow
• All responses return mock data and do not affect real business operations
• Suitable for validating:
  • API connectivity
  • Request parameter formats
  • Request and response handling logic Please refer to the following documentation for Sandbox testing: Testing in Sandbox Mode.

4. Switch to the Production Environment

After completing Sandbox testing and validating your integration logic, you may switch to the Production environment.

• Please note the following when switching:
  • Use the Production API Key and API Secret
  • Update the request base URL to: https://open.smileapi.io/v1
• The Production environment returns real data, which directly impacts business decisions
• It is recommended to perform a small-scale test after switching to ensure the results meet business expectations.

5. Pre-Launch Checklist and Best Practices (Recommended)

Before going live, please ensure that:

• ✅ API Key / Secret are not hard-coded in frontend applications or public repositories
• ✅ API errors, timeouts, and failure responses are properly handled
• ✅ Logging and request tracing are implemented
• ✅ Reasonable request frequency limits and risk control strategies are configured according to business needs

About the Consent Object in the API

To meet compliance requirements, some API requests require a Consent object to indicate that the user has agreed to the relevant terms or declarations.

{
  "type": "Terms And Conditions",
  "version": 1,
  "consentedWith": "I agree to the terms and conditions.",
  "consentedAt": "2021-04-14T09:30:24Z",
  "consentTemplateId": null
}

1. Field Description

2. Required Field Rules

• consentedAt is always required, regardless of which consent method is used
• One of the following approaches is required (either one is sufficient; both are not needed):
  • Using consentTemplateId
    • consentTemplateId can be obtained after creating a Consent template in the Smile Developer Portal
    • Recommended when you want to centrally manage Consent content
    • When consentTemplateId is provided, type, version, and consentedWith are optional
  • Using the type + version + consentedWith Combination
    • In this approach, type, version, and consentedWith must all be provided
    • Field values can be freely defined by the integrator and are not strictly validated
    • Suitable for scenarios where Portal templates are not used or rapid integration is preferred

3. Validation and Compliance Notes

• The Consent object is primarily used to meet compliance requirements
• Smile API does not perform strict validation on Consent content
• You only need to ensure that:
  • Required fields are present
  • Field values are valid