Idswyft API Docs

https://idswyft.app/docs
Admin
Idswyft provides an API for identity verification through a multi-step asynchronous flow, enabling...
Tokens:11,679
Snippets:56
Trust Score:4.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Verification Session with Addons

Source: https://idswyft.app/docs

Starts a verification session and enables AML screening. Ensure the API key is correctly formatted.

```shell
curl -X POST https://api.idswyft.app/api/v2/verify/initialize \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "addons": { "aml_screening": true }
  }'
```

--------------------------------

### Initialize Verification Session

Source: https://idswyft.app/docs

Starts a new verification session for a user. Include your API key in the X-API-Key header. Use sandbox mode for development.

```shell
curl -X POST https://api.idswyft.app/api/v2/verify/initialize \
  -H "X-API-Key: ik_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "550e8400-e29b-41d4-a716-446655440000"}'
```

--------------------------------

### POST /api/v2/verify/initialize

Source: https://idswyft.app/docs

Starts a new verification session for a user. It returns a unique `verification_id` that is used for all subsequent operations within the session. Optional add-ons like AML screening can be enabled.

```APIDOC
## POST /api/v2/verify/initialize

### Description
Creates a new verification session for a user. Returns a `verification_id` that ties together all subsequent uploads and results. One session = one complete identity check.

### Method
POST

### Endpoint
`/api/v2/verify/initialize`

### Parameters
#### Request Body
- **user_id** (string) - Required - Your unique identifier for the user being verified.
- **sandbox** (boolean) - Optional - Set true to use sandbox mode. Defaults to false.
- **addons** (object) - Optional - Optional add-on features to enable for this session.
  - **addons.aml_screening** (boolean) - Optional - Enable AML/sanctions screening against OFAC, EU & UN lists. PEP screening also available via AML_PROVIDER=pep. Runs automatically after identity verification completes.

### Request Example
```json
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "addons": { "aml_screening": true }
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **verification_id** (string) - The unique identifier for the verification session.
- **status** (string) - The current status of the verification session (e.g., "AWAITING_FRONT").
- **current_step** (integer) - The current step in the verification process.
- **total_steps** (integer) - The total number of steps in the verification process.
- **message** (string) - A message describing the result of the operation.

#### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_FRONT",
  "current_step": 1,
  "total_steps": 5,
  "message": "Verification session initialized"
}
```
```

--------------------------------

### Verification Response - Completed

Source: https://idswyft.app/docs

This is an example of a successful verification response. It includes results for face matching, liveness detection, age estimation, velocity analysis, and geolocation. The `final_result` indicates the overall outcome.

```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "COMPLETE",
  "current_step": 5,
  "selfie_id": "selfie_abc789",
  "message": "Verification complete",

  "face_match_results": {
    "passed": true,
    "similarity_score": 0.94, 
    "threshold_used": 0.6 
  },
  
  "liveness_results": {
    "liveness_passed": true,
    "liveness_score": 0.96,
    "liveness_mode": "head_turn" 
  },
  
  "age_estimation": {
    "document_face_age": 33, 
    "live_face_age": 35, 
    "declared_age": 35, 
    "age_discrepancy": 0 
  },
  
  "velocity_analysis": {
    "ip_verifications_1h": 1, 
    "ip_verifications_24h": 2, 
    "user_verifications_24h": 1, 
    "avg_step_duration_ms": 8500, 
    "fastest_step_ms": 5200, 
    "flags": [], 
    "score": 0 
  },
  
  "geo_analysis": {
    "ip_country": "US", 
    "ip_region": "CA",
    "ip_city": "San Francisco",
    "document_country": "US", 
    "is_tor": false,
    "is_datacenter": false,
    "flags": [], 
    "score": 0 
  },
  
  "final_result": "verified" 
}
```

--------------------------------

### Get Live-Capture Selfie URL

Source: https://idswyft.app/docs

Returns a short-lived signed URL for the verification's live-capture selfie. This is useful for downstream face matching on your own systems. The URL is scoped to the authenticated API key and returns a 404 for unknown verification IDs.

```APIDOC
## GET /api/v2/verify/:id/selfie

### Description
Returns a short-lived **signed URL** for the verification's live-capture selfie — handy when you want to run a downstream face match on your own side. Scoped to the authenticated API key: a verification you don't own (or an unknown ID) returns `404` (never 403), so the endpoint can't be used to enumerate other developers' verification IDs. Returns only the selfie URL — no OCR, PII, or other documents.

### Endpoint
`/api/v2/verify/:id/selfie`

### Method
GET

### Parameters
#### Query Parameters
- **X-API-Key** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl -X GET https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/selfie \
  -H "X-API-Key: your-key"
```

### Response
#### Success Response (200)
- **verification_id** (string) - The unique identifier for the verification.
- **selfie_url** (string) - A short-lived signed URL pointing to the selfie image.
- **expires_in** (integer) - The time in seconds until the selfie URL expires.

### Response Example
```json
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "selfie_url": "https://storage.idswyft.app/selfies/…?token=…",
  "expires_in": 300
}
```
```

--------------------------------

### JavaScript: Complete ID Verification Flow

Source: https://idswyft.app/docs

This comprehensive JavaScript snippet demonstrates the entire ID verification process using the IDSWYFT API. It covers starting a session, uploading front and back documents, polling for OCR and cross-validation completion, submitting a live capture, and finally polling for the overall verification result. Ensure you replace 'your-api-key' with your actual API key and provide the correct file objects for documents and captures.

```javascript
const BASE = 'https://api.idswyft.app';
const KEY = 'your-api-key';
const headers = { 'X-API-Key': KEY };

// ─── 1. Start session ───────────────────────────────────────────
const { verification_id } = await fetch(`${BASE}/api/v2/verify/initialize`, {
 method: 'POST',
 headers: { ...headers, 'Content-Type': 'application/json' },
 body: JSON.stringify({ user_id: 'user-uuid' }),
}).then(r => r.json());

// ─── 2. Upload front document ───────────────────────────────────
const fd1 = new FormData();
fd1.append('document_type', 'drivers_license');
fd1.append('document', frontFile); // File from <input type="file">
await fetch(`${BASE}/api/v2/verify/${verification_id}/front-document`, { method: 'POST', headers, body: fd1 });

// ─── 3. Poll until OCR finishes ─────────────────────────────────
let r;
do {
 await new Promise(ok => setTimeout(ok, 2000));
 r = await fetch(`${BASE}/api/v2/verify/${verification_id}/status`, { headers }).then(r => r.json());
} while (!r.ocr_data);

// ─── 4. Upload back-of-ID (cross-validation auto-triggers) ──────
const fd2 = new FormData();
fd2.append('document_type', 'drivers_license');
fd2.append('document', backFile); // field name is 'document' (not 'back_of_id')
await fetch(`${BASE}/api/v2/verify/${verification_id}/back-document`, { method: 'POST', headers, body: fd2 });

// ─── 5. Poll until cross-validation finishes ────────────────────
do {
 await new Promise(ok => setTimeout(ok, 2000));
 r = await fetch(`${BASE}/api/v2/verify/${verification_id}/status`, { headers }).then(r => r.json());
} while (!r.cross_validation_results);

if (r.final_result === 'failed') throw new Error('Cross-validation failed: ' + r.failure_reason);

// ─── 6. Submit live capture (file upload) ────────────────────────
const fd3 = new FormData();
fd3.append('selfie', captureBlob, 'capture.jpg'); // Blob from canvas.toBlob()
await fetch(`${BASE}/api/v2/verify/${verification_id}/live-capture`, {
 method: 'POST',
 headers,
 body: fd3,
});

// ─── 7. Poll for final result ────────────────────────────────────
do {
 await new Promise(ok => setTimeout(ok, 2000));
 r = await fetch(`${BASE}/api/v2/verify/${verification_id}/status`, { headers }).then(r => r.json());
} while (!r.final_result);

console.log(r.final_result); // 'verified' | 'failed' | 'manual_review'
console.log(r.face_match_results?.similarity_score); // 0.0 – 1.0
console.log(r.ocr_data.name); // "Jane Smith"

```

--------------------------------

### Get Verification Results

Source: https://idswyft.app/docs

Retrieve the current status and final results of a verification session. This endpoint is useful for polling and tracking the progress of a verification.

```APIDOC
## GET /api/v2/verify/:id/status

### Description
Get the verification results for a given verification ID. This is the single source of truth for a verification session and can be used for polling at each processing stage and for reading the final result.

### Method
GET

### Endpoint
/api/v2/verify/:id/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the verification session.

### Response
#### Success Response (200)
Returns the full verification record including OCR data, cross-validation scores, liveness score, and face match score. The structure of the response is identical to the response of the POST /api/v2/verify/VERIFICATION_ID/live-capture endpoint, detailing all stages and results of the verification process.

### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "COMPLETE",
  "current_step": 5,
  "selfie_id": "selfie_abc789",
  "message": "Verification complete",
  "face_match_results": {
    "passed": true,
    "similarity_score": 0.94,
    "threshold_used": 0.6
  },
  "liveness_results": {
    "liveness_passed": true,
    "liveness_score": 0.96,
    "liveness_mode": "head_turn"
  },
  "age_estimation": {
    "document_face_age": 33,
    "live_face_age": 35,
    "declared_age": 35,
    "age_discrepancy": 0
  },
  "velocity_analysis": {
    "ip_verifications_1h": 1,
    "ip_verifications_24h": 2,
    "user_verifications_24h": 1,
    "avg_step_duration_ms": 8500,
    "fastest_step_ms": 5200,
    "flags": [],
    "score": 0
  },
  "geo_analysis": {
    "ip_country": "US",
    "ip_region": "CA",
    "ip_city": "San Francisco",
    "document_country": "US",
    "is_tor": false,
    "is_datacenter": false,
    "flags": [],
    "score": 0
  },
  "final_result": "verified"
}
```
```

--------------------------------

### Get Cross-Validation Results

Source: https://idswyft.app/docs

Retrieve cached cross-validation results. This endpoint is useful for querying results independently after the back document upload.

```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_LIVE",
  "documents_match": true,
  "cross_validation_results": {
    "verdict": "PASS",
    "has_critical_failure": false,
    "score": 0.95,
    "failures": []
  }
}
```

--------------------------------

### Head Turn Liveness Metadata - JSON

Source: https://idswyft.app/docs

This JSON structure is used to send liveness metadata for the 'head_turn' challenge. It includes frame data with base64 encoded images, timestamps, and phase information, along with overall start and end timestamps.

```json
{
  "challenge_type": "head_turn",
  "challenge_direction": "left",
  "frames": [
  { "frame_base64": "/9j/4AAQ...", "timestamp": 1000, "phase": "turn1_start" },
  { "frame_base64": "/9j/4BBR...", "timestamp": 4000, "phase": "turn1_peak" },
  { "frame_base64": "/9j/4CCG...", "timestamp": 7000, "phase": "turn1_return" },
  { "frame_base64": "/9j/4DDH...", "timestamp": 8200, "phase": "turn_start" },
  { "frame_base64": "/9j/4EEI...", "timestamp": 11200, "phase": "turn_peak" },
  { "frame_base64": "/9j/4FFJ...", "timestamp": 14200, "phase": "turn_return" }
  ],
  "start_timestamp": 0,
  "end_timestamp": 15000
}
```

--------------------------------

### Get Cross-Validation Results

Source: https://idswyft.app/docs

Retrieve the cached cross-validation results separately. Cross-validation runs automatically during the back document upload (Step 3), so this endpoint is only needed if you want to query the results independently.

```APIDOC
## POST /api/v2/verify/:id/cross-validation

### Description
Retrieve the cached cross-validation results separately. Cross-validation runs automatically during the back document upload (Step 3), so this endpoint is only needed if you want to query the results independently.

### Endpoint
`/api/v2/verify/:id/cross-validation`

### Method
POST

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **verification_id** (string) - The unique identifier for the verification.
- **status** (string) - The current status of the verification process.
- **documents_match** (boolean) - Indicates if the documents provided match.
- **cross_validation_results** (object) - Contains the results of the cross-validation.
  - **verdict** (string) - The overall verdict of the cross-validation (e.g., "PASS").
  - **has_critical_failure** (boolean) - Indicates if there was a critical failure during cross-validation.
  - **score** (number) - The confidence score of the cross-validation.
  - **failures** (array) - A list of any failures encountered during cross-validation.

### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_LIVE",
  "documents_match": true,
  "cross_validation_results": {
    "verdict": "PASS",
    "has_critical_failure": false,
    "score": 0.95,
    "failures": []
  }
}
```
```

--------------------------------

### Get Verification Status - cURL

Source: https://idswyft.app/docs

Poll this endpoint to retrieve the current status and final results of a verification session. It provides the complete record, including OCR data, cross-validation scores, liveness, and face match scores. Polling conditions are outlined to determine when to proceed to the next step.

```bash
curl -X GET https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/status \
  -H "X-API-Key: your-key"
```

--------------------------------

### Initialize Verification Session Response

Source: https://idswyft.app/docs

HTTP 201 response indicating successful initialization of a verification session. The response includes a verification ID and the current status.

```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_FRONT",
  "current_step": 1,
  "total_steps": 5,
  "message": "Verification session initialized"
}
```

--------------------------------

### Retrieve Live-Capture Selfie URL (cURL)

Source: https://idswyft.app/docs

Use this cURL command to fetch a short-lived signed URL for the verification's live-capture selfie. Replace 'your-key' with your actual API key and the verification ID with the target ID.

```bash
curl -X GET https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/selfie \
  -H "X-API-Key: your-key"
```

--------------------------------

### POST /api/v2/verify/:id/front-document

Source: https://idswyft.app/docs

Uploads the front face of an identity document. This step includes OCR extraction and image quality analysis. If the image quality is too poor, the session will be hard-rejected.

```APIDOC
## POST /api/v2/verify/:id/front-document

### Description
Upload the **front face** of the identity document (passport, driver's license, national ID). OCR extraction and image quality analysis (Gate 1) run during upload. The response includes `ocr_data` with extracted fields and confidence scores. If the image quality is too poor, the session is hard-rejected.

### Method
POST

### Endpoint
`/api/v2/verify/:id/front-document`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the verification session.

#### Request Body
- **document_type** (string) - Required - Type of the document: 'passport', 'drivers_license', 'national_id', or 'other'.
- **document** (File) - Required - The document image file (JPEG, PNG, WebP, or PDF). Max 10 MB.

### Request Example
```bash
curl -X POST https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/front-document \
  -H "X-API-Key: your-key" \
  -F "document_type=drivers_license" \
  -F "document=@front.jpg"
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **verification_id** (string) - The unique identifier for the verification session.
- **status** (string) - The current status of the verification session (e.g., "AWAITING_BACK").
- **current_step** (integer) - The current step in the verification process.
- **document_id** (string) - The identifier for the uploaded document.
- **message** (string) - A message describing the result of the operation.
- **ocr_data** (object) - Extracted data from the document.
  - **full_name** (string) - The full name extracted from the document.
  - **date_of_birth** (string) - The date of birth extracted from the document.
  - **id_number** (string) - The ID number extracted from the document.
  - **expiration_date** (string) - The expiration date extracted from the document.
  - **address** (string) - The address extracted from the document.
  - **confidence_scores** (object) - Confidence scores for the extracted OCR data.
    - **full_name** (number) - Confidence score for the full name.
    - **date_of_birth** (number) - Confidence score for the date of birth.

#### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_BACK",
  "current_step": 2,
  "document_id": "doc_abc123",
  "message": "Front document processed successfully",
  "ocr_data": {
    "full_name": "JANE SMITH",
    "date_of_birth": "1990-06-15",
    "id_number": "DL123456789",
    "expiration_date": "2030-06-15",
    "address": "123 Main St, Anytown, US",
    "confidence_scores": { "full_name": 0.97, "date_of_birth": 0.96 }
  }
}
```

#### Error Response Example (Hard Reject)
```json
{
  "success": false,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "HARD_REJECTED",
  "current_step": 1,
  "message": "Document quality too poor for processing.",
  "rejection_reason": "POOR_QUALITY",
  "rejection_detail": "Image too blurry for OCR extraction"
}
```
```

--------------------------------

### Upload Front Document Response

Source: https://idswyft.app/docs

HTTP 201 response after successfully processing the front document. Includes OCR data and confidence scores. If quality is poor, the status will be HARD_REJECTED.

```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_BACK",
  "document_id": "doc_abc123",
  "message": "Front document processed successfully",
   
  "ocr_data": {
  "full_name": "JANE SMITH",
  "date_of_birth": "1990-06-15",
  "id_number": "DL123456789",
  "expiration_date": "2030-06-15",
  "address": "123 Main St, Anytown, US",
  "confidence_scores": { "full_name": 0.97, "date_of_birth": 0.96 }
  }
   
  // If Gate 1 (quality) fails → status becomes "HARD_REJECTED":
  // "rejection_reason": "POOR_QUALITY",
  // "rejection_detail": "Image too blurry for OCR extraction"
}
```

--------------------------------

### Upload Front Document

Source: https://idswyft.app/docs

Uploads the front of an identity document. The document type must match the ID. Ensure the file is a supported format and within the size limit.

```shell
curl -X POST https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/front-document \
  -H "X-API-Key: your-key" \
  -F "document_type=drivers_license" \
  -F "document=@front.jpg"
```

--------------------------------

### Head-turn Liveness Verification

Source: https://idswyft.app/docs

Capture frames from the camera and send them to the server for liveness analysis. This method provides strong anti-spoofing capabilities.

```APIDOC
## POST /api/v2/verify/VERIFICATION_ID/live-capture

### Description
Capture frames from camera, server analyzes face for liveness.

### Method
POST

### Endpoint
https://api.idswyft.app/api/v2/verify/VERIFICATION_ID/live-capture

### Parameters
#### Request Body
- **selfie** (file) - Required - The captured selfie image.
- **liveness_metadata** (object) - Required - Metadata for liveness analysis.
  - **challenge_type** (string) - Required - Type of liveness challenge (e.g., "head_turn").
  - **challenge_direction** (string) - Required - Direction of the challenge (e.g., "left").
  - **frames** (array) - Required - Array of frame objects.
    - **frame_base64** (string) - Required - Base64 encoded frame.
    - **timestamp** (integer) - Required - Timestamp of the frame.
    - **phase** (string) - Required - Phase of the liveness challenge.
  - **start_timestamp** (integer) - Required - Start timestamp of the liveness session.
  - **end_timestamp** (integer) - Required - End timestamp of the liveness session.

### Request Example
```json
{
  "selfie": "@capture.jpg",
  "liveness_metadata": {
    "challenge_type": "head_turn",
    "challenge_direction": "left",
    "frames": [
      {"frame_base64":"<base64>","timestamp":1000,"phase":"turn1_start"},
      {"frame_base64":"<base64>","timestamp":4000,"phase":"turn1_peak"},
      {"frame_base64":"<base64>","timestamp":7000,"phase":"turn1_return"},
      {"frame_base64":"<base64>","timestamp":8200,"phase":"turn_start"},
      {"frame_base64":"<base64>","timestamp":11200,"phase":"turn_peak"},
      {"frame_base64":"<base64>","timestamp":14200,"phase":"turn_return"}
    ],
    "start_timestamp": 0,
    "end_timestamp": 15000
  }
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **verification_id** (string) - The unique identifier for the verification.
- **status** (string) - The current status of the verification.
- **current_step** (integer) - The current step in the verification process.
- **selfie_id** (string) - The ID of the captured selfie.
- **message** (string) - A message describing the verification outcome.
- **face_match_results** (object) - Results of the face match comparison.
  - **passed** (boolean) - Whether the face match passed.
  - **similarity_score** (number) - The similarity score between faces (0.0 - 1.0).
  - **threshold_used** (number) - The confidence threshold used for the match.
- **liveness_results** (object) - Results of the liveness detection.
  - **liveness_passed** (boolean) - Whether liveness detection passed.
  - **liveness_score** (number) - The liveness detection score.
  - **liveness_mode** (string) - The mode used for liveness detection (e.g., "head_turn").
- **age_estimation** (object) - Estimated age from document and live capture.
  - **document_face_age** (integer) - Estimated age from document photo.
  - **live_face_age** (integer) - Estimated age from live capture.
  - **declared_age** (integer) - Age declared from DOB.
  - **age_discrepancy** (integer) - Absolute difference between live face age and declared age.
- **velocity_analysis** (object) - Fraud detection based on activity velocity.
  - **ip_verifications_1h** (integer) - Number of verifications from the same IP in the last hour.
  - **ip_verifications_24h** (integer) - Number of verifications from the same IP in the last 24 hours.
  - **user_verifications_24h** (integer) - Number of verifications for the same user in the last 24 hours.
  - **avg_step_duration_ms** (integer) - Average time between verification steps.
  - **fastest_step_ms** (integer) - Duration of the fastest single step.
  - **flags** (array) - List of fraud detection flags.
  - **score** (integer) - Overall fraud score (0-100).
- **geo_analysis** (object) - Risk analysis based on IP geolocation.
  - **ip_country** (string) - Country code of the IP address.
  - **ip_region** (string) - Region code of the IP address.
  - **ip_city** (string) - City of the IP address.
  - **document_country** (string) - Country code from document OCR.
  - **is_tor** (boolean) - Whether the IP is a Tor exit node.
  - **is_datacenter** (boolean) - Whether the IP belongs to a data center.
  - **flags** (array) - List of geolocation risk flags.
  - **score** (integer) - Overall geolocation risk score (0-100).
- **final_result** (string) - The final decision of the verification ("verified", "manual_review", or "failed").

### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "COMPLETE",
  "current_step": 5,
  "selfie_id": "selfie_abc789",
  "message": "Verification complete",
  "face_match_results": {
    "passed": true,
    "similarity_score": 0.94,
    "threshold_used": 0.6
  },
  "liveness_results": {
    "liveness_passed": true,
    "liveness_score": 0.96,
    "liveness_mode": "head_turn"
  },
  "age_estimation": {
    "document_face_age": 33,
    "live_face_age": 35,
    "declared_age": 35,
    "age_discrepancy": 0
  },
  "velocity_analysis": {
    "ip_verifications_1h": 1,
    "ip_verifications_24h": 2,
    "user_verifications_24h": 1,
    "avg_step_duration_ms": 8500,
    "fastest_step_ms": 5200,
    "flags": [],
    "score": 0
  },
  "geo_analysis": {
    "ip_country": "US",
    "ip_region": "CA",
    "ip_city": "San Francisco",
    "document_country": "US",
    "is_tor": false,
    "is_datacenter": false,
    "flags": [],
    "score": 0
  },
  "final_result": "verified"
}
```
```

--------------------------------

### Submit Live Capture

Source: https://idswyft.app/docs

Submits a live capture image for liveness detection and face matching. Supports passive and head-turn liveness modes.

```APIDOC
## POST /api/v2/verify/:id/live-capture

### Description
Submits a live capture image for liveness detection (Gate 4) and face matching (Gate 5). Supports passive and head-turn liveness modes.

### Method
POST

### Endpoint
https://api.idswyft.app/api/v2/verify/:id/live-capture

### Parameters
#### Path Parameters
- **id** (string) - Required - The verification ID.

#### Request Body
- **selfie** (file) - Required - JPEG or PNG image captured live from the user's camera. Max 10 MB.
- **liveness_metadata** (string) - Optional - JSON stringified challenge data for head_turn liveness. Omit for passive mode.

### Request Example (Passive Liveness)
```bash
curl -X POST https://api.idswyft.app/api/v2/verify/VERIFICATION_ID/live-capture \
  -H "X-API-Key: your-key" \
  -F "selfie=@capture.jpg"
```

### Request Example (Head Turn Liveness Metadata)
```json
{
  "challenge_type": "head_turn",
  "challenge_direction": "left",
  "frames": [
    { "frame_base64": "/9j/4AAQ...", "timestamp": 1000, "phase": "turn1_start" },
    { "frame_base64": "/9j/4BBR...", "timestamp": 4000, "phase": "turn1_peak" },
    { "frame_base64": "/9j/4CCG...", "timestamp": 7000, "phase": "turn1_return" },
    { "frame_base64": "/9j/4DDH...", "timestamp": 8200, "phase": "turn_start" },
    { "frame_base64": "/9j/4EEI...", "timestamp": 11200, "phase": "turn_peak" },
    { "frame_base64": "/9j/4FFJ...", "timestamp": 14200, "phase": "turn_return" }
  ],
  "start_timestamp": 0,
  "end_timestamp": 15000
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **verification_id** (string) - The unique identifier for the verification process.
- **status** (string) - The current status of the verification.
- **current_step** (integer) - The current step in the verification flow.
- **message** (string) - A message describing the outcome of the operation.
- **liveness_results** (object) - Results of the liveness detection.
  - **verdict** (string) - The overall verdict of the liveness check ("PASS" or "REVIEW").
  - **score** (number) - The confidence score of the liveness check.
  - **failures** (array) - A list of specific liveness failures.
- **face_match_results** (object) - Results of the face matching comparison.
  - **verdict** (string) - The overall verdict of the face match ("PASS" or "REVIEW").
  - **score** (number) - The similarity score between the selfie and document photo.
  - **failures** (array) - A list of specific face match failures.
```

--------------------------------

### Submit Head-Turn Liveness Capture - cURL

Source: https://idswyft.app/docs

Use this endpoint to submit selfie frames for head-turn liveness detection. Ensure the `liveness_metadata` matches the expected schema; otherwise, a HTTP 400 error will be returned. Head-turn liveness is recommended for production identity verification.

```bash
curl -X POST https://api.idswyft.app/api/v2/verify/VERIFICATION_ID/live-capture \
  -H "X-API-Key: your-key" \
  -F "selfie=@capture.jpg" \
  -F 'liveness_metadata={
  "challenge_type": "head_turn",
  "challenge_direction": "left",
  "frames": [
  {"frame_base64":"<base64>","timestamp":1000,"phase":"turn1_start"},
  {"frame_base64":"<base64>","timestamp":4000,"phase":"turn1_peak"},
  {"frame_base64":"<base64>","timestamp":7000,"phase":"turn1_return"},
  {"frame_base64":"<base64>","timestamp":8200,"phase":"turn_start"},
  {"frame_base64":"<base64>","timestamp":11200,"phase":"turn_peak"},
  {"frame_base64":"<base64>","timestamp":14200,"phase":"turn_return"}
  ],
  "start_timestamp": 0,
  "end_timestamp": 15000
  }'
```

--------------------------------

### Submit Live Capture - Passive Mode - cURL

Source: https://idswyft.app/docs

Upload a selfie for passive liveness detection. This mode uses heuristic signals and does not require additional metadata. Ensure the image is a live capture from the device camera, not a static file upload.

```bash
# Passive liveness (just the file, no metadata)
curl -X POST https://api.idswyft.app/api/v2/verify/VERIFICATION_ID/live-capture \
  -H "X-API-Key: your-key" \
  -F "selfie=@capture.jpg"
```

--------------------------------

### POST /api/v2/verify/:id/back-document

Source: https://idswyft.app/docs

Uploads the back face of an identity document. This step is required to unlock live capture and performs cross-validation against the front document's data.

```APIDOC
## POST /api/v2/verify/:id/back-document

### Description
Upload the **back face** of the ID for barcode/QR scanning and cross-validation against the front OCR data. This is a **required step** — it unlocks live capture. If the front and back do not match the same document, the verification immediately moves to failed and live capture is blocked.

What cross-validation checks:
✓ PDF417 / QR barcode decoding
✓ ID number consistency (front OCR ↔ barcode)
✓ Expiry date matching
✓ Issuing authority matching
✓ Photo consistency score
✓ Security feature detection

### Method
POST

### Endpoint
`/api/v2/verify/:id/back-document`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the verification session.

#### Request Body
- **document_type** (string) - Required - Must match the `document_type` used in Step 2 (front-document upload).
- **document** (File) - Required - The document image file (JPEG, PNG, or WebP). Max 10 MB. Field name is 'document'.

### Request Example
```bash
curl -X POST https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/back-document \
  -H "X-API-Key: your-key" \
  -F "document_type=drivers_license" \
  -F "document=@back.jpg"
```

### Response
(Response details for this endpoint are not fully provided in the source text, but typically include success status, verification ID, and updated session status.)
```

--------------------------------

### Upload Back Document

Source: https://idswyft.app/docs

Uploads the back side of an identity document for verification. This endpoint processes the document and initiates cross-validation.

```APIDOC
## POST /api/v2/verify/:id/back-document

### Description
Uploads the back of an identity document for verification. This endpoint processes the document and initiates cross-validation.

### Method
POST

### Endpoint
https://api.idswyft.app/api/v2/verify/:id/back-document

### Parameters
#### Request Body
- **document_type** (string) - Required - The type of the document (e.g., "drivers_license").
- **document** (file) - Required - The image file of the back of the document.

### Request Example
```bash
curl -X POST https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/back-document \
  -H "X-API-Key: your-key" \
  -F "document_type=drivers_license" \
  -F "document=@back.jpg"
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **verification_id** (string) - The unique identifier for the verification process.
- **status** (string) - The current status of the verification (e.g., "AWAITING_LIVE").
- **current_step** (integer) - The current step in the verification flow.
- **message** (string) - A message describing the outcome of the operation.
- **barcode_data** (object) - Extracted data from the document's barcode (if available).
  - **first_name** (string) - First name from the barcode.
  - **last_name** (string) - Last name from the barcode.
  - **date_of_birth** (string) - Date of birth from the barcode (YYYYMMDD).
  - **document_number** (string) - Document number from the barcode.
- **documents_match** (boolean) - Indicates if the front and back documents match.
- **cross_validation_results** (object) - Results of the cross-validation between front and back documents.
  - **verdict** (string) - The overall verdict of the cross-validation ("PASS" or "REVIEW").
  - **has_critical_failure** (boolean) - Indicates if there was a critical failure during cross-validation.
  - **score** (number) - The confidence score of the cross-validation (0.0 - 1.0).
  - **failures** (array) - A list of specific failures encountered (e.g., ["DOB_MISMATCH", "NAME_MISMATCH"]).

### Response Example
```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_LIVE",
  "current_step": 3,
  "message": "Back document processed successfully",
  "barcode_data": {
    "first_name": "JANE",
    "last_name": "SMITH",
    "date_of_birth": "19900615",
    "document_number": "DL123456789"
  },
  "documents_match": true,
  "cross_validation_results": {
    "verdict": "PASS",
    "has_critical_failure": false,
    "score": 0.95,
    "failures": []
  }
}
```
```

--------------------------------

### Verification Response - JSON

Source: https://idswyft.app/docs

This JSON response details the outcome of the back document processing. It includes success status, verification ID, current step, and extracted data such as barcode information and cross-validation results.

```json
{
  "success": true,
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "AWAITING_LIVE",
  "current_step": 3,
  "message": "Back document processed successfully",
  
  "barcode_data": {
  "first_name": "JANE",
  "last_name": "SMITH",
  "date_of_birth": "19900615",
  "document_number": "DL123456789"
  },
  
  "documents_match": true,
  "cross_validation_results": {
  "verdict": "PASS",
  "has_critical_failure": false,
  "score": 0.95,
  "failures": []
  }
}
```

--------------------------------

### Upload Back of ID

Source: https://idswyft.app/docs

Uploads the back of the identity document for barcode scanning and cross-validation. The document type must match the front document. This step is required to unlock live capture.

```shell
curl -X POST https://api.idswyft.app/api/v2/verify/550e8400-e29b-41d4-a716-446655440001/back-document \
  -H "X-API-Key: your-key" \
  -F "document_type=drivers_license" \
  -F "document=@back.jpg"
```

--------------------------------

### Live-Capture Selfie URL Response

Source: https://idswyft.app/docs

This JSON response contains the verification ID, a signed URL for the live-capture selfie, and the expiration time in seconds.

```json
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440001",
  "selfie_url": "https://storage.idswyft.app/selfies/…?token=…",
  "expires_in": 300
}
```
Tokens:
Raw