SMS Link

Overview

SMS Link confirms device possession by sending a one-time link to the user's registered phone number via SMS. The user must tap the link on their mobile device. A tap on desktop or a timeout results in denial. Device and network risk signals are assessed simultaneously.

SMS Link is the possession step in Identity Verification and Identity Binding workflows, and the challenge step in Continuous Re-Authentication. It is also available as a standalone MFA step.

Level of Assurance

Medium — phone possession confirmed via SMS link tap on mobile device.

User Friction Level

Very Low — single SMS tap on mobile. Most users complete in under 30 seconds.

End User Requirements

Access to the mobile phone number on file; ability to receive SMS; must tap the link on a mobile device (not desktop).

Speed

Real-time (seconds for delivery; user-dependent for tap)

Supported Countries

Broad international SMS coverage. Contact your ID Dataweb team for country-specific availability.

Use Cases & Fraud Prevention

• Phone possession step in MobileMatch + SMS Link workflows.
• MFA challenge in Continuous Re-Authentication — triggered when session risk is elevated.
• Step-up for high-value transactions or account changes.
• Account takeover prevention — confirms physical device possession at the moment of the event.
• Passive session risk runs alongside possession check — flagging compromised sessions in parallel.

How It Works

When SMS Link is triggered, the platform sends a one-time link via SMS to the user's registered phone number. The link is single-use and expires after the configured timeout window. The user taps the link on their mobile device — the platform detects whether the tap came from a mobile device or not.

• Mobile tap within timeout → approve
• Desktop open, non-mobile tap, or timeout → deny

Configuration Options

Template Variations

• SMS Link — default; collects device signals on tap
• SMS OTP (legacy) — 6-digit code entry; available for backward compatibility

Optional Add-ons

• SIM Swap checker — flags recent SIM port on the SMS Link API key before the link is sent
• Recycled Number checker — flags recently recycled or deactivated numbers
• Trust Device — skip SMS Link for previously verified devices for a configurable period

Integration: Gateway (OIDC)

Standard OIDC flow. See Gateway (OIDC) Integration. The SMS link delivery and tap detection are handled by the hosted UI.

Step-by-step Setup

• SMS Link is included automatically in Identity Verification, Identity Binding, and Continuous Re-Authentication workflows — no separate setup required.
• Optional: enable Login Hint to prefill the user's phone number.
• QR code delivery available as an alternative to SMS for desktop sessions — contact your ID Dataweb team to enable.

Integration: ID Dataweb API

SMS Link uses a three-step flow: deliver the link to the user's device, poll until the tap is detected, then call /slverify for the final decision. One decision to make before you integrate: how the link reaches the user.

API Prerequisites

When to use what

Custom Text (explanationHTML)

Any Send Link request can include an explanationHTML field — a string of HTML that replaces the default text on the SMS Link screen the user sees when they tap the link. This is a POST variant of Send Link (the basic Send Link is a GET).

When to use it: Custom text is useful any time you want to give the user context about why they are being asked to tap, or add a trust signal that confirms they are interacting with a legitimate request.

Two common patterns:

• Random code match — generate a short random code in your application and display it to the user on your screen. Pass the same code in explanationHTML on the SMS Link screen. The user visually confirms the codes match before tapping — this prevents a fraudster from sending a rogue SMS Link and tricking the user into approving it.

• Trust signal — include the user's name, your company name, or transaction context (e.g. "John, please confirm your identity to complete your password reset"). This reassures the user they are responding to a legitimate request from a known source.

1. Deliver the link

Call one of the endpoints to initiate an SMS Link session. All return an asi — save it for steps 2 and 3.

sequenceDiagram
    participant App as Your Application
    participant IDW as ID Dataweb API
    participant User as End User

    Note over App,IDW: forwardApiKey from preceding step = SMS Link step key

    App->>IDW: GET /doccapture/sendlink<br/>POST /doccapture/sendlink (custom text)<br/>GET /doccapture/getlink<br/>POST /async-ui/qr-code
    IDW-->>App: asi
    IDW->>User: SMS delivered (Send Link only)
    Note over App,User: Get Link: you deliver the URL<br/>QR Code: you render the image on screen
    User->>IDW: Taps link on mobile device

const response = await fetch('https://api.preprod.iddataweb.com/v1/doccapture/sendlink?' + new URLSearchParams({
  dialCode: '1',
  telephone: '1234567890',
  apikey: FASTTAP_STEP_KEY,
  credential: userCredential,
  appID: 'Your Application Name'
}), {
  method: 'GET',
  headers: { 'Authorization': `Bearer ${accessToken}` }
});

{
  "responseCode": "string",
  "errorDescription": "string",
  "asi": "string",
  "status": "SUCCESS"
}

2. Poll for tap

Polling is the only retrieval method for SMS Link — there is no redirect, because the tap itself is the completion event. Poll /doccapture/results every 3–5 seconds until status is success, then proceed to /slverify. Do not poll faster than every 3 seconds — rate limiting applies.

sequenceDiagram
    participant App as Your Application
    participant IDW as ID Dataweb API
    participant User as End User

    User->>IDW: Taps SMS Link on mobile device
    loop Poll every 3–5 seconds
        App->>IDW: GET /doccapture/results?asi=...
        IDW-->>App: status: pending | success
    end
    Note over App: status = success → proceed to /slverify

async function waitForTap(asi, accessToken) {
  while (true) {
    const res = await fetch(`https://api.preprod.iddataweb.com/v1/doccapture/results?asi=${asi}`, {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    const data = await res.json();
    if (data.status === 'success') return;
    await new Promise(r => setTimeout(r, 4000)); // 3–5 seconds between polls
  }
}

3. Call /slverify

The same regardless of which delivery method you used. Pass the asi from step 1 to get the final policyDecision.

const response = await fetch('https://api.preprod.iddataweb.com/v1/slverify', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apikey: FASTTAP_STEP_KEY,
    credential: userCredential,
    asi: asi,
    userAttributes: [
      { attributeType: 'InternationalTelephone', values: { dialCode: '1', telephone: '1234567890' } }
    ]
  })
});

{
  "errorCode": "string",
  "errorDescription": "string",
  "transaction_id": "string",
  "acquiredAttributes": [],
  "userAssertionList": [],
  "policyDecision": "approve | deny",
  "forwardApiKey": "string"
}

Step-by-step Setup

• Use the forwardApiKey from the preceding step (PII Validation or Session Risk) as FASTTAP_STEP_KEY.
• Choose your delivery method and call the corresponding endpoint. Save the returned asi.
• Poll GET /doccapture/results every 3–5 seconds until status is success.
• Call POST /slverify with the asi to retrieve the final policyDecision.
• On policyDecision = approve, use forwardApiKey for the next step if the workflow continues.

Policy Components & Assertions

Device and network risk assertions from Session Risk also apply to this step's session context. A test.device = Fail means the link was opened on a non-mobile device or the session timed out.

Error Handling & Troubleshooting

• Link tapped on desktop = deny: Expected behavior — instruct users to tap on their phone, not a computer.
• Link expired: Timeout reached before tap. Adjust the timeout window for your use case, or allow the user to request a new link.
• SIM Swap add-on enabled: A recent SIM port triggers denial before the link is sent — expected behavior, do not override.
• Do not poll faster than every 3 seconds — the results endpoint has rate limiting.
• SMS not received: Verify the dial code and phone number are correct. Check SMS delivery coverage for the user's country.

Testing in Preproduction

Testing Options

• Gateway (Try Now): Admin Console — complete an Identity Verification or Continuous Re-Authentication flow. Tap the link on mobile for approve; open on desktop for deny.
• API: Contact your ID Dataweb team for the SMS Link Postman Collection with the preproduction endpoint.

Test Credentials and Values

Step-by-step How to Test

• Approve: Complete the preceding step, receive the SMS, tap the link on a mobile device.
• Deny (desktop): Copy the link from the SMS and open it in a desktop browser.
• Deny (timeout): Receive the SMS and do not tap — wait for the session to expire.

Interpreting Results

policyDecision = approve when test.device = Pass (link tapped on mobile within timeout).
policyDecision = deny when test.device = Fail (desktop tap, timeout, or SIM Swap block).
Check acquiredAttributes for device and network risk signals.

Related Resources

→ Identity Verification | → Continuous Re-Authentication | → PII Validation | → Session Risk | → Gateway (OIDC) Integration