Overview

const res = await fetch('https://api.livface.com/v1/sessions', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.LIVEFACE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ challenge_count: 5 }),
})
const { session_id } = await res.json()

import { LivenessView } from 'liveface'

<LivenessView
  apiUrl="https://api.livface.com"
  sessionId={session_id}
  onComplete={(result) => {
    if (result.passed) navigation.replace('Success')
  }}
/>

const { status, score, id_document } = await fetch(
  `https://api.livface.com/v1/sessions/${sessionId}`,
  { headers: { 'x-api-key': process.env.LIVEFACE_API_KEY } }
).then(r => r.json())

if (status === 'passed' && score > 0.8) {
  // mark user verified
}

curl https://api.livface.com/v1/sessions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"challenge_count": 5}'

Keep your API key on the server

{
  "session_id":         "3f7a1b2c-e4d5-...",
  "challenges":         ["BLINK","SMILE","TURN_LEFT","OPEN_MOUTH","RAISE_EYEBROWS"],
  "current_challenge":  "BLINK",
  "challenge_index":    0,
  "total_challenges":   5,
  "expires_in_seconds": 300,
  "hosted_url":         "https://livface.com/check?s=3f7a1b2c-..."
}

{
  "session_id":        "3f7a1b2c-...",
  "status":            "passed",
  "score":             0.97,
  "liveness_verified": true,
  "id_verified":       true,
  "id_match_score":    0.91,
  "id_document": {
    "issue_date":  "2021-03-10",
    "expiry_date": "2029-03-10",
    "valid":       true
  },
  "completed_at": "2026-06-25T15:00:00.000Z"
}

const { status, score, id_verified, id_document } = await fetch(
  `https://api.livface.com/v1/sessions/${sessionId}`,
  { headers: { 'x-api-key': process.env.LIVEFACE_API_KEY } }
).then(r => r.json())

if (status !== 'passed') return res.status(400).json({ error: 'Verification failed' })
if (!id_document?.valid) return res.status(400).json({ error: 'ID document expired' })
await db.users.update({ id: userId }, { kyc_verified: true })

Optional feature

{
  "ok": true,
  "message": "ID photo accepted",
  "id_document": {
    "issue_date":  "2021-03-10",
    "expiry_date": "2029-03-10",
    "valid":       true
  }
}

HTTP 422
{
  "error":       "ID document has expired",
  "expiry_date": "2024-01-15",
  "id_expired":  true
}

Sending the full card photo

{ "frame_b64": "base64-encoded-jpeg..." }

{
  "challenge_passed":  false,
  "face_detected":     true,
  "session_status":    "pending",
  "current_challenge": "BLINK",
  "confidence":        0.42
}

{
  "challenge_passed":  true,
  "session_status":    "passed",
  "score":             0.97,
  "liveness_verified": true,
  "id_verified":       true,
  "id_match_score":    0.91,
  "id_document": {
    "issue_date":  "2021-03-10",
    "expiry_date": "2029-03-10",
    "valid":       true
  }
}

import { WebView } from 'react-native-webview'

<WebView
  source={{ uri: hostedUrl }}
  onMessage={(e) => {
    const { type, passed, session_id } = JSON.parse(e.nativeEvent.data)
    if (type === 'liveness_result') {
      // verify server-side with GET /v1/sessions/:id
    }
  }}
/>

npx expo install expo-camera
npm install liveface

app.json — camera permission

import { LivenessView } from 'liveface'

export function VerifyScreen({ sessionId }: { sessionId: string }) {
  return (
    <LivenessView
      apiUrl="https://api.livface.com"
      sessionId={sessionId}
      onComplete={(result) => {
        if (result.passed) navigation.replace('Success')
        else console.log('Failed:', result.reason)
      }}
    />
  )
}

<LivenessView
  apiUrl="https://api.livface.com"
  sessionId={sessionId}
  idImageB64={base64IdPhoto}   // full card photo, no data:... prefix
  onComplete={(result) => {
    console.log(result.idVerified)              // face matched
    console.log(result.idMatchScore)            // 0.0 – 1.0
    console.log(result.idDocument?.expiryDate)  // '2029-03-10'
    console.log(result.idDocument?.valid)       // true
  }}
/>

<LivenessView
  apiUrl="https://api.livface.com"
  sessionId={sessionId}
  primaryColor="#6366f1"      // ring, spinner, step dots  (default: #4ade80)
  backgroundColor="#0f0f0f"   // background before camera loads
  onComplete={handleComplete}
/>

<LivenessView
  apiUrl="https://api.livface.com"
  sessionId={sessionId}
  onComplete={handleComplete}

  // Replace the progress ring
  renderRing={({ filledRatio, faceDetected }) => (
    <MyRing progress={filledRatio} active={faceDetected} />
  )}

  // Replace the bottom instruction card
  renderStatusCard={({ status, progressCount, progressTotal }) => (
    <MyStatusCard label={status} step={progressCount} total={progressTotal} />
  )}

  // Replace the pass/fail overlay — call onRetry() to restart
  renderResult={({ phase, result, onRetry }) => (
    <MyResultScreen passed={phase === 'passed'} onRetry={onRetry} />
  )}

  // Extra layer above everything (branding, close button, etc.)
>
  <SafeAreaView style={StyleSheet.absoluteFill} pointerEvents="box-none">
    <TouchableOpacity style={styles.close} onPress={navigation.goBack}>
      <Text>✕</Text>
    </TouchableOpacity>
  </SafeAreaView>
</LivenessView>

import { CameraView } from 'expo-camera'
import { useLiveness } from 'liveface'

export function CustomVerifyScreen({ sessionId }: { sessionId: string }) {
  const {
    cameraRef,
    phase,          // 'idle' | 'uploading_id' | 'running' | 'passed' | 'failed'
    status,         // current instruction string
    progressCount,  // challenges completed
    progressTotal,  // total challenges
    faceDetected,
    result,
    start,
    reset,
  } = useLiveness({
    apiUrl: 'https://api.livface.com',
    sessionId,
    onComplete: (r) => console.log(r),
  })

  return (
    <View style={{ flex: 1 }}>
      <CameraView ref={cameraRef} style={StyleSheet.absoluteFill} facing="front" />
      <Text style={styles.label}>{status}</Text>
      {phase === 'idle'   && <Button title="Start" onPress={start} />}
      {phase === 'failed' && <Button title="Try again" onPress={reset} />}
    </View>
  )
}

interface LivenessResult {
  passed:            boolean
  sessionId:         string
  score?:            number
  livenessVerified?: boolean
  idVerified?:       boolean
  idMatchScore?:     number
  reason?:           string   // 'spoof_detected' | 'id_mismatch' | 'session_expired'
}

dependencies:
  livface: ^1.0.0

Platform permissions

import 'package:livface/livface.dart';

class VerifyScreen extends StatelessWidget {
  final String sessionId;
  const VerifyScreen({required this.sessionId, super.key});

  @override
  Widget build(BuildContext context) {
    return LivenessView(
      apiUrl:    'https://api.livface.com',
      sessionId: sessionId,
      onComplete: (result) {
        if (result.passed) {
          Navigator.pushReplacementNamed(context, '/success');
        }
      },
    );
  }
}

LivenessView(
  apiUrl:       'https://api.livface.com',
  sessionId:    sessionId,
  idImageBytes: await File(idPhotoPath).readAsBytes(),  // full card photo
  onComplete: (result) {
    print('Face matched: ${result.idVerified}');
    print('Match score:  ${result.idMatchScore}');
  },
)

LivenessView(
  apiUrl:          'https://api.livface.com',
  sessionId:       sessionId,
  primaryColor:    const Color(0xFF6366F1),   // ring and accent
  backgroundColor: const Color(0xFF0F0F0F),
  onComplete:      handleComplete,
)

LivenessView(
  apiUrl: 'https://api.livface.com',
  sessionId: sessionId,
  onComplete: handleComplete,

  // Replace the progress ring
  ringBuilder: (context, filledRatio, faceDetected) =>
      MyRing(progress: filledRatio, active: faceDetected),

  // Replace the bottom instruction card
  statusBuilder: (context, status, done, total) =>
      MyStatusCard(label: status, done: done, total: total),

  // Replace the result overlay (onRetry is null when passed == true)
  resultBuilder: (context, result, onRetry) =>
      MyResultScreen(result: result, onRetry: onRetry),

  // Extra layer above everything
  overlay: Align(
    alignment: Alignment.topRight,
    child: SafeArea(
      child: IconButton(
        icon: const Icon(Icons.close, color: Colors.white),
        onPressed: () => Navigator.pop(context),
      ),
    ),
  ),
)

import 'package:livface/livface.dart';
import 'package:camera/camera.dart';

final client = LivenessClient('https://api.livface.com');

final result = await client.run(
  () async {
    final xfile = await cameraController.takePicture();
    return File(xfile.path).readAsBytes();
  },
  RunOptions(
    sessionId:    sessionId,
    onStatus:     (msg)            => setState(() => _label = msg),
    onProgress:   (done, total, _) => setState(() => _progress = done / total),
  ),
);

{
  "event":             "session.completed",
  "session_id":        "3f7a1b2c-...",
  "passed":            true,
  "score":             0.97,
  "liveness_verified": true,
  "id_verified":       true,
  "id_match_score":    0.91,
  "id_document": {
    "issue_date":  "2021-03-10",
    "expiry_date": "2029-03-10",
    "valid":       true
  },
  "timestamp": "2026-06-25T12:00:00.000Z"
}

app.post('/webhooks/liveface', express.raw({ type: '*/*' }), (req, res) => {
  const sig      = req.headers['x-liveness-signature']
  const expected = 'sha256=' + require('crypto')
    .createHmac('sha256', process.env.LIVEFACE_WEBHOOK_SECRET)
    .update(req.body).digest('hex')

  if (!require('crypto').timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.sendStatus(401)

  const { event, passed, id_document } = JSON.parse(req.body)
  if (event === 'session.completed' && passed) {
    // id_document.valid confirms the ID hasn't expired
  }
  res.sendStatus(200)
})