Getting Started

Smile Shield is Smile API’s Device Profiling and Fingerprinting SDK. It collects device, network, session, and identity signals at important moments in the user journey and returns risk intelligence that can support lending and fraud-prevention decisions.

Shield is designed to provide two complementary categories of metrics:

Shield combines signals from the current device session with Smile’s network intelligence and returns a risk score, supporting reason codes, and detailed intelligence about the device, network, and submitted identity attributes.

Integration is lightweight: initialize the Shield SDK in your client application, collect the Shield session ID, and create an assessment from your server.

Integration Steps

Integrating Shield requires a small client-side SDK implementation and a server-side API call.

Prerequisites

Before starting the integration, ensure that:

• You have registered an account on the Smile Developer Portal.
• Shield has been enabled for your organization.
• You have your Sandbox API Key and API Secret.
• Your server can securely store API credentials and make authenticated API requests.
• You have selected where Shield profiling will run in your user journey.
• You have determined how your application will use Shield results in its decision logic.

1. Obtain a user token

Your backend must obtain a short-lived user token from Smile API. Pass this token to the client application when initializing the Shield SDK.

The token must be requested from your server so that your API credentials remain private.

See API Authentication and the Users API for more information.

2. Initialize the Shield SDK

Initialize the SDK in your web or mobile application using the user token.

When Shield starts, it creates a profiling session and returns a sessionId. Your client must send this sessionId to your backend.

3. Complete device profiling

Shield collects device, browser, network, and session signals and reports whether profiling completed successfully.

Wait for:

• profilingStatus = COMPLETED
• profilingResultCode = SUCCESS

A session that is still running, failed, or timed out cannot be assessed successfully.

4. Create an assessment

After profiling completes, your backend sends the sessionId and available applicant attributes to:

POST /shield/sessions/{sessionId}/assessments

Applicant attributes are optional individually, but providing more information produces a richer assessment. Address and phone information are particularly useful for identity-correlation and network-consistency checks.

5. Use the result in your decision process

The response contains an overall risk score, reason codes, and supporting device, network, identity, and session intelligence.

Use these results as inputs to your:

• Credit policy or scorecard
• Fraud rules engine
• Step-up verification flow
• Manual-review queue
• Monitoring and investigation tools

6. Test in Sandbox

Complete the full workflow in Sandbox before moving to Production:

Sandbox returns a standard mock assessment for any request that passes validation. It is suitable for testing authentication, request validation, callbacks, status handling, response parsing, and decision-system integration.

7. Move to Production

Before switching to Production:

• Replace Sandbox credentials with Production credentials.
• Change the API base URL to https://open.smileapi.io/v1.
• Confirm that Shield is enabled for the Production tenant.
• Verify consent and disclosure requirements.
• Confirm production quotas and rate limits.
• Test with a small number of controlled transactions.
• Monitor API failures, timeouts, and unexpected results.

Quickstart

Runnable samples for Web, Android, iOS, React Native, and Flutter are available in the Smile Quickstart repository.

The shield/ directory contains the Shield examples for each supported client.

Supported clients

Sandbox assessment values

The following values may be used to create a self-explanatory Sandbox request:

Any valid Sandbox request returns the same mock assessment.

Expected result:

{
  "status": "COMPLETED",
  "resultCode": "SUCCESS"
}

Other result codes include:

Client SDK

End-to-end flow

sequenceDiagram
    participant Mobile as Mobile App
    participant SDK as Shield SDK
    participant Server as Your backend
    participant Smile as Smile API Server

    Server->>Smile: 1. request a userToken
    Smile-->>Server: 2. return the accessToken
    Server-->>Mobile: 3. hand the userToken to the app
    Mobile->>SDK: 4. initialise and call start()
    SDK->>Smile: 5. create a Shield session
    Smile-->>SDK: 6. return the sessionId
    Smile-->>Server: 7. Webhook SHIELD_SESSION_PROFILING_STARTED
    Note over SDK: 8. loading screen shown, device signals collected
    SDK-->>Mobile: 9. onProfilingStarted(sessionId)
    SDK->>Smile: 10. report profiling finished (success or timeout)
    Smile-->>Server: 11. Webhook SHIELD_SESSION_PROFILING_FINISHED
    SDK-->>Mobile: 12. onProfilingFinished(profilingResultCode)
    Mobile-->>Server: 13. forward the sessionId
    Server->>Smile: 14. POST create assessment (applicant attributes)
    Smile-->>Server: 15. return the risk result

UI changes from Step 4 - 12

Web installation

Add the Shield JavaScript SDK to your page:

<script src="https://web.smileapi.io/shield/v1/shield.v1.js"></script>

Initialize a new Shield instance:

const shield = new SmileShield({
  userToken,
  ui: {
    layout: "popup",
    title: "Verifying your identity",
    description: "We're running a quick security check.",
    primaryColor: "#0B9758"
  },

  onProfilingStarted(info) {
    // info.sessionId   string    session id — send it to your backend
    // info.mode        string    'remote' (real profiling) or 'mock' (local UI work)
    // info.userId      string?   user the session belongs to, undefined when not supplied
    // info.startedAt   string    ISO 8601 start timestamp
  },
  onProfilingFinished(info) {
    // info.sessionId             string    same session id
    // info.durationMs            number    time from start() to completion, ms
    // info.userId                string?   user the session belongs to
    // info.profilingResultCode   string    'SUCCESS' completed, 'TIMEOUT' gave up waiting
    // info.finishedAt            string    ISO 8601 finish timestamp
  },
  onError(err) {
    // err.code      string    error code, see below
    // err.message   string    human readable message
    // err.detail    any?      original error object, for debugging only
  }
});

await shield.start();

Create a new SDK instance for every profiling attempt. If the user starts profiling again on the same page, call close() on the previous instance before creating another one.

Loading screen

The Shield loading screen is always displayed while profiling is in progress. It cannot be disabled.

You can customize:

SDK callbacks

Status and result codes

POST /shield/sessions/{sessionId}/assessments requires a session with:

profilingStatus = COMPLETED
profilingResultCode = SUCCESS

If the session is still profiling, the assessment request returns 409 Conflict.

If profiling failed or timed out, start a new Shield session before creating another assessment.

Understanding the Results

A Shield assessment returns an overall score together with the signals that influenced it.

Overall risk score

Each reason code may include:

• rank
• code
• description
• effect

Result groups

Early Payment Default metrics

Early Payment Default metrics can help enrich an existing underwriting or credit-risk process by identifying stability, consistency, and network signals associated with the applicant and device.

Potentially relevant inputs include:

• Device tenure and previous activity
• Frequency or velocity of device activity
• Identity-attribute consistency
• Phone and email tenure
• Address and IP consistency
• Network associations involving the device, phone, email, or IP

Use these metrics as additional features in a scorecard or policy. They do not replace affordability checks, income verification, bureau data, or other underwriting requirements.

Antifraud metrics

Antifraud metrics can help detect behavior that may require additional verification or manual review.

Examples include:

A single signal does not prove fraud. Evaluate signals together with the overall risk score, reason codes, transaction context, and other verification data.

Policy outcome

result.policyEngine provides a simplified policy-layer outcome:

Event Notifications

Shield can send webhook notifications when profiling begins and finishes.

Subscribe to the required events in the Developer Portal and ensure your webhook endpoint can process repeated or delayed deliveries safely.

See Webhooks for subscription and payload details.

Maintaining User Data

Shield processes device, network, session, and identity-related information. Your integration should clearly explain the profiling activity to the user and collect consent where required.

The assessment request supports a consent object containing:

When consentTemplateId is supplied, the stored template provides the relevant consent content.

Data retention

Shield assessment results are retained for 60 days. After 60 days, the assessment result is removed, but the Shield session and assessment records are kept.

If you need assessment results for longer than 60 days — for example, for audit, model validation, or dispute handling — store them in your own systems when you receive them.

Assessment records remain available for billing reconciliation after the result has been removed.

Before going live, confirm that your implementation addresses:

• User notice and consent
• Lawful basis for device profiling
• Data minimization
• Access controls
• Retention and deletion
• User-access or deletion requests
• Cross-account and shared-device analysis
• Storage of assessment results in your own systems
• Applicable local privacy and lending regulations

Chargeable Events

Shield is billed per assessment call.

Each successful request to the following endpoint counts as one assessment:

POST /shield/sessions/{sessionId}/assessments

Repeated assessments

Every assessment request is billed separately.

Cached results

When the same session and applicant attributes are submitted within the cache window of up to 24 hours, Smile may reuse a recent result to reduce latency.

Each request still creates an assessment record and is billed as a separate assessment, even when a cached result is reused.

The assessment indicates whether a cached result was used through hitCache.

Billing reconciliation

Use the following information for reconciliation:

• Assessment ID
• Assessment creation timestamp
• Your transactionId
• Session ID
• ShieldSession.assessmentCount
• hitCache

Use GET /shield/sessions/{sessionId}/assessments to list the assessments associated with a session.

Contact your Smile account manager to discuss quota changes or volume pricing.

Rate and Quota Limitations

Shield uses separate controls for product enablement, sessions, assessments, and general API traffic.

See Rate Limits and Quota Management for more information.

Shield API

Pre-Launch Checklist

Before enabling Shield in Production, confirm that:

• API credentials are stored only on the server.
• The SDK is initialized with a valid user token.
• A new SDK instance is created for every profiling attempt.
• Your backend waits for successful profiling before creating an assessment.
• Timeout, error, and NO_DATA cases are handled.
• Assessment requests include all available applicant attributes.
• The result is treated as an input rather than a final decision.
• Your decision logic distinguishes EPD and antifraud use cases.
• Thresholds have been validated against your own outcomes.
• User notice, consent, retention, and deletion requirements have been reviewed.
• Assessment results needed beyond 60 days are stored in your own systems.
• Webhook handling is idempotent.
• Production quotas and rate limits have been confirmed.
• Assessment IDs and transactionId values are logged for reconciliation.

FAQ