OneTapForms SDK Integration Guide

OneTapForms is a secure, biometric-authenticated data sharing platform that allows users to fill forms instantly using their verified profile data stored on their iOS device.

🆓 Free for Developers

The SDK is completely free to use! There are no fees, usage limits, or restrictions for developers.

Why Integrate OneTapForms?

Direct benefits for your business:

⚡ Faster form completion - Users complete forms in seconds, not minutes
📈 Higher conversion rates - Reduce form abandonment dramatically
🎯 Better UX - Eliminate typing errors and user friction
🔒 Verified data - Receive pre-verified, accurate information
💰 Zero cost - Free SDK, no integration fees, no per-use charges

Revenue comes from end users who subscribe to the OneTapForms service ($9-29/month) to securely store their profile data. Your users pay for the convenience, not you.

Quick Start (30 seconds)

Choose the installation method that matches your skill level:

Option 1: Script Tag (Easiest - No Build Tools Required)

Perfect for HTML websites, WordPress, or any site where you can add a script tag:

<!-- 1. Add the script to your page -->
<script src="https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js"></script>

<!-- 2. Add a button with data attributes -->
<button
  data-onetapforms
  data-client-id="YOUR_CLIENT_ID"
  data-purpose="Complete your profile"
  data-bundles="basic,contact">
  Fill with OneTapForms
</button>

<!-- 3. Handle the result -->
<script>
document.querySelector('[data-onetapforms]')
  .addEventListener('onetapforms:complete', function(e) {
    console.log('Token:', e.detail.token);
    // Send token to your server to get user data
  });
</script>

That's it! The SDK automatically shows a QR modal when the button is clicked.

Option 2: npm Install (For React, Vue, Next.js, etc.)

npm install @createlex/onetapforms-sdk

import { OneTapForms } from '@createlex/onetapforms-sdk';

const onetap = new OneTapForms({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET'
});

await onetap.request({
  purpose: 'Job Application',
  bundles: ['basic', 'contact'],
  onQRReady: (qrUrl) => {
    // Show QR code to user
    document.getElementById('qr').src = qrUrl;
  },
  onComplete: ({ token }) => {
    // Exchange token for data on your server
    fetch('/api/exchange', {
      method: 'POST',
      body: JSON.stringify({ token })
    });
  }
});

Widget Mode Reference (Script Tag)

Data Attributes

Attribute	Required	Description
`data-onetapforms`	Yes	Marks element as OneTapForms trigger
`data-client-id`	Yes	Your client ID
`data-client-secret`	No	Your client secret
`data-purpose`	No	Purpose shown to user (default: "Complete form")
`data-bundles`	No	Comma-separated bundles (default: "basic")
`data-form-id`	No	Auto-inject token into this form
`data-api-url`	No	Custom API URL

Events

Listen for these custom events on your button/element:

// Success - user approved the request
element.addEventListener('onetapforms:complete', (e) => {
  const { token, requestId } = e.detail;
  // Send token to your server
});

// Error - something went wrong
element.addEventListener('onetapforms:error', (e) => {
  const { error } = e.detail;
  console.error('Failed:', error.message);
});

Auto-Inject Token into Form

Use data-form-id to automatically add the token to a form:

<form id="myForm" method="POST" action="/submit">
  <input type="text" name="email" placeholder="Email">

  <button
    type="button"
    data-onetapforms
    data-client-id="YOUR_ID"
    data-form-id="myForm">
    Autofill with OneTapForms
  </button>

  <button type="submit">Submit</button>
</form>

<!-- Token is automatically added as: -->
<!-- <input type="hidden" name="onetapforms_token" value="..."> -->

Complete HTML Example

<!DOCTYPE html>
<html>
<head>
  <title>Job Application</title>
</head>
<body>
  <h1>Apply Now</h1>

  <form id="applicationForm" action="/apply" method="POST">
    <input name="name" placeholder="Full Name">
    <input name="email" placeholder="Email">
    <input name="phone" placeholder="Phone">

    <button
      type="button"
      data-onetapforms
      data-client-id="your_client_id"
      data-purpose="Job application at ACME Corp"
      data-bundles="basic,contact"
      data-form-id="applicationForm"
      style="background: #007AFF; color: white; padding: 12px 24px; border: none; border-radius: 8px; cursor: pointer;">
      Fill with OneTapForms
    </button>

    <button type="submit">Submit Application</button>
  </form>

  <script src="https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js"></script>
  <script>
    document.querySelector('[data-onetapforms]').addEventListener('onetapforms:complete', function(e) {
      alert('Form ready! Token received.');
      // Token is auto-injected into the form - submit when ready
    });
  </script>
</body>
</html>

npm API Reference

Constructor

import { OneTapForms } from '@createlex/onetapforms-sdk';

const onetap = new OneTapForms({
  clientId: 'your_client_id',       // Required
  clientSecret: 'your_secret',      // Recommended
  apiUrl: 'https://api.createlex.com', // Optional
  debug: true                       // Optional: enable logging
});

request(options)

Create a form completion request.

await onetap.request({
  // Content
  purpose: 'Complete your profile',   // Required
  bundles: ['basic', 'contact'],      // Optional
  fields: ['name', 'email'],          // Optional

  // Mode
  mode: 'auto',                       // 'auto' | 'qr' | 'redirect'
  returnUrl: 'https://...',           // For redirect mode

  // Callbacks
  onQRReady: (qrDataUrl) => {},       // QR code ready (desktop)
  onComplete: ({ token }) => {},      // User approved
  onError: (error) => {}              // Error occurred
});

handleCallback()

Handle redirect flow callback (mobile):

const result = onetap.handleCallback();
if (result) {
  const { token, requestId } = result;
  // Exchange token on server
}

cancelPolling()

Cancel active polling (cleanup):

onetap.cancelPolling();

showDownloadPrompt(options)

Encourage app downloads:

onetap.showDownloadPrompt({
  title: 'Complete Forms Faster!',
  message: 'Download OneTapForms for instant form completion.',
  buttonText: 'Download App'
});

getAppDownloadUrl()

Get App Store URL:

const url = onetap.getAppDownloadUrl();
// 'https://apps.apple.com/app/onetapforms'

Data Bundles

OneTapForms organizes user data into bundles. Request only what you need:

Bundle	Data Included
`basic`	First name, last name, email
`contact`	Phone number, address
`identity`	Government ID, verification status
`financial`	Bank account details
`health`	Medical information
`professional`	Resume, work history, certifications

Request Flow

Desktop Flow (QR Code)

Your website calls onetap.request()
SDK generates a QR code pointing to the OneTapForms approval URL
User scans QR code with their iPhone
OneTapForms app prompts for biometric authentication
User approves with Face ID/Touch ID
SDK receives completion callback with exchange token
Your server exchanges token for user data

Mobile Flow (Redirect)

Your mobile website calls onetap.request({ mode: 'redirect' })
SDK opens OneTapForms app via Universal Link
User approves with biometric authentication
OneTapForms redirects back to your returnUrl with token
Your server exchanges token for user data

Server-Side Token Exchange

Important: Always exchange tokens server-side to protect your credentials.

// Node.js example
const response = await fetch('https://api.createlex.com/api/onetapforms/exchange', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-ID': 'your_client_id',
    'X-Client-Secret': 'your_client_secret'
  },
  body: JSON.stringify({ token })
});

const { data } = await response.json();
// data contains: { name, email, phone, ... }

Response Format

{
  "userData": {
    "email": "[email protected]",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "phone": "+1234567890",
    "location": {
      "city": "San Francisco",
      "state": "CA",
      "country": "USA"
    }
  },
  "bundleSelected": "basic",
  "approvedAt": "2025-12-24T12:00:00Z"
}

Request Modes

Mode	When to Use	Behavior
`auto` (default)	Most cases	Mobile = redirect, Desktop = QR
`qr`	Desktop only	Shows QR code modal
`redirect`	Mobile only	Opens OneTapForms app

Getting Started

Get Credentials: Register at onetapforms.createlex.com/register to receive your clientId and clientSecret (free)
Install SDK: Via script tag or npm
Add Button: With data attributes or JavaScript
Handle Token: Exchange on your server for user data

CDN URLs

# Latest version (recommended for development)
https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.min.js

# Specific version (recommended for production)
https://cdn.jsdelivr.net/npm/@createlex/[email protected]/dist/onetapforms.umd.min.js

# Unminified (for debugging)
https://cdn.jsdelivr.net/npm/@createlex/onetapforms-sdk@latest/dist/onetapforms.umd.js

Security Considerations

Never expose your API key client-side - Always exchange tokens on your server
Validate return URLs - Only allow callbacks to your registered domains
Exchange tokens once - Tokens are one-time use and expire after exchange
Use HTTPS - All API calls must use HTTPS
Request minimal data - Only request bundles you actually need

Error Handling

onetap.request({
  // ... options
  onError: (error) => {
    switch (error.code) {
      case 'REQUEST_EXPIRED':
        // Request timed out, create a new one
        break;
      case 'USER_DECLINED':
        // User declined to share data
        break;
      case 'INVALID_CLIENT':
        // Check your clientId and clientSecret
        break;
      default:
        console.error('OneTapForms error:', error.message);
    }
  }
});

Package Information

npm Package: @createlex/onetapforms-sdk
Version: 1.2.0+
License: MIT
Install: npm install @createlex/onetapforms-sdk