### Install Dependencies

Source: https://docs.verisoul.ai/examples/react-native-facematch-sample-app

Install the necessary npm packages for the project.

```bash
npm install
```

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

### Install Expo Dev Client

Source: https://docs.verisoul.ai/integration/frontend/react-native

Install the expo-dev-client package, which is required for Expo projects using the Verisoul SDK.

```sh
npx expo install expo-dev-client
```

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

### Run the React Sample Application

Source: https://docs.verisoul.ai/examples/web-sample-app

Start the development server for the React Sample App. The application will be accessible at http://localhost:3000.

```bash
npm start
```

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

### Install CocoaPods

Source: https://docs.verisoul.ai/integration/frontend/ios

Installs the CocoaPods package manager. Required if using CocoaPods for SDK integration.

```sh
sudo gem install cocoapods
```

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

### Install SDK with CocoaPods

Source: https://docs.verisoul.ai/integration/frontend/ios

Installs the VerisoulSDK and its dependencies into your Xcode project using CocoaPods.

```sh
pod install
```

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

### Initialize Verisoul SDK

Source: https://docs.verisoul.ai/integration/frontend/ios

Initializes the Verisoul SDK with the specified environment and project ID. This should be called once when your application starts.

```swift
import VerisoulSDK

Verisoul.shared.configure(env: .prod, projectId: "your-project-id")
```

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

### Retrieve Available Lists via OpenAPI

Source: https://docs.verisoul.ai/api-reference/lists/get

Defines the GET /list endpoint for fetching all available lists, including the response schema and example output.

```yaml
openapi: 3.0.1
info:
  title: Verisoul API
  description: The Verisoul API is used to integrate Verisoul into your application.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.sandbox.verisoul.ai
security:
  - apiKeyAuth: []
paths:
  /list:
    get:
      description: Returns all available lists
      responses:
        '200':
          description: Lists response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListsResponse'
              example:
                request_id: abb42d71-f4d4-440f-b1c7-a250ec0eddd7
                lists:
                  - name: allow
                    description: Marks every account in the list as Real.
                  - name: block
                    description: Marks every account in the list as Fake.
                  - name: main_account
                    description: >-
                      Sets the multiple_accounts score to 0 for every account in
                      the list.
                  - name: us_users
                    description: List of US based users
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListsResponse:
      type: object
      properties:
        request_id:
          type: string
          description: The ID of the request
        lists:
          type: array
          items:
            $ref: '#/components/schemas/List'
          description: Array of available lists
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    List:
      type: object
      properties:
        name:
          type: string
          description: The name of the list
        description:
          type: string
          description: Description of the list's purpose
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
```

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

### Clone Verisoul React Sample App Repository

Source: https://docs.verisoul.ai/examples/web-sample-app

Clone the sample app repository and navigate into the project directory. Ensure you have Git installed.

```bash
git clone https://github.com/verisoul/react-sample-app.git
cd react-sample-app
```

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

### Touch Event Collection

Source: https://docs.verisoul.ai/integration/frontend/react-native

Setup for capturing touch events to detect automated or bot behavior.

```APIDOC
## VerisoulTouchRootView

### Description
Wrap your root component with VerisoulTouchRootView to automatically capture touch events across both iOS and Android for fraud detection.

### Request Example
```js
import { VerisoulTouchRootView } from "@verisoul_ai/react-native-verisoul";

function App() {
  return (
    <VerisoulTouchRootView>{/* Your app components */}</VerisoulTouchRootView>
  );
}
```
```

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

### Install Verisoul SDK using NPM

Source: https://docs.verisoul.ai/integration/frontend/react-native

Use this command to add the Verisoul React Native SDK to your project via NPM.

```sh
npm install @verisoul_ai/react-native-verisoul
```

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

### Async Verisoul Script Tag Installation

Source: https://docs.verisoul.ai/integration/frontend/browser

Recommended for better page load performance. This script loads asynchronously and includes a helper to ensure the Verisoul object is always available.

```html
<script async src="https://js.verisoul.ai/{env}/bundle.js" verisoul-project-id="{project_id}"></script>
<script>!function(e){if(e.Verisoul)return;const r=[],t={},o=new Proxy(t,{get:(e,o)=>o in t?t[o]:(...e)=>new Promise(((t,n)=>r.push([o,e,t,n]))),set:(e,r,o)=>(t[r]=o,!0)});e.Verisoul=o;const n=()=>{Object.keys(t).length&&r.splice(0).forEach((([e,r,o,n])=>{try{Promise.resolve(t[e](...r)).then(o,n)}catch(e){n(e)}}))},c=document.querySelector("script[verisoul-project-id]"),s=()=>r.splice(0).forEach((([,,,e])=>e(new Error("Failed to load Verisoul SDK"))));if(!c)return void s();c.addEventListener("load",n,{once:!0}),c.addEventListener("error",((()=>{clearInterval(i),s()})),{once:!0});const i=setInterval(((()=>{Object.keys(t).length&&(clearInterval(i),n())})),40)}(window);</script>
```

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

### Initialize Verisoul SDK in React Native

Source: https://docs.verisoul.ai/integration/frontend/react-native

Initialize the Verisoul SDK with your project credentials. This should be called once when your application starts. Use VerisoulEnvironment.prod for production or VerisoulEnvironment.sandbox for testing.

```javascript
import Verisoul,
  VerisoulEnvironment,
} from "@verisoul_ai/react-native-verisoul";

useEffect(() => {
  Verisoul.configure({
    environment: VerisoulEnvironment.prod, // or VerisoulEnvironment.sandbox
    projectId: "YOUR_PROJECT_ID",
  });
}, []);
```

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

### Example URL for Spanish Face Match

Source: https://docs.verisoul.ai/verifications/face-match/integration/localization

Navigate to this URL to serve Face Match in Spanish. Replace `{VERISOUL_SESSION_ID}` with your actual session ID.

```url
https://app.sandbox.verisoul.ai?session_id={VERISOUL_SESSION_ID}&lng=es
```

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

### Install Verisoul SDK using Yarn

Source: https://docs.verisoul.ai/integration/frontend/react-native

Use this command to add the Verisoul React Native SDK to your project via Yarn.

```sh
yarn add @verisoul_ai/react-native-verisoul
```

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

### Retrieve Device Data JSON

Source: https://docs.verisoul.ai/signals-scores/device

Example of the device and browser signals collected by Verisoul to profile a user's environment.

```json
{
  "browser": {
    "type": "Chrome",
    "version": "132.0.0.0",
    "language": "en",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
    "timezone": "America/Chicago"
  },
  "device": {
    "category": "desktop",
    "type": "Mac",
    "os": "macOS 10.15.7",
    "cpu_cores": 16,
    "memory": 8,
    "gpu": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Max, Unspecified Version)"
  }
}
```

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

### Synchronous Verisoul Script Tag Installation

Source: https://docs.verisoul.ai/integration/frontend/browser

A simpler integration option that blocks page rendering until the script is loaded. The Verisoul object is available immediately after loading.

```html
<script src="https://js.verisoul.ai/{env}/bundle.js" verisoul-project-id="{project_id}"></script>
```

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

### Account Score and Decision Example

Source: https://docs.verisoul.ai/signals-scores/scoring-overview

This JSON object demonstrates the account score and the corresponding decision. The 'decision' field provides a human-readable interpretation of the 'account_score'.

```json
{
  "account_score": 0.82,  // 82% - High risk
  "decision": "Fake"
}
```

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

### Run the Application

Source: https://docs.verisoul.ai/examples/react-native-facematch-sample-app

Launch the application using Expo.

```bash
npx expo start
```

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

### Clone the Repository

Source: https://docs.verisoul.ai/examples/react-native-facematch-sample-app

Download the sample application source code from GitHub.

```bash
git clone https://github.com/verisoul/react-native-facematch-sample-app.git
cd react-native-facematch-sample-app
```

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

### Verisoul SDK Initialization

Source: https://docs.verisoul.ai/integration/frontend/react-native

Initializes the Verisoul SDK with project credentials and environment settings.

```APIDOC
## Verisoul.configure()

### Description
Initializes the Verisoul SDK with your project credentials. This method must be called once when your application starts.

### Parameters
- **environment** (VerisoulEnvironment) - Required - The environment to use (VerisoulEnvironment.prod or VerisoulEnvironment.sandbox)
- **projectId** (string) - Required - Your unique Verisoul project identifier

### Request Example
```js
import Verisoul, { VerisoulEnvironment } from "@verisoul_ai/react-native-verisoul";

useEffect(() => {
  Verisoul.configure({
    environment: VerisoulEnvironment.prod,
    projectId: "YOUR_PROJECT_ID",
  });
}, []);
```
```

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

### Get ID Check Session OpenAPI Specification

Source: https://docs.verisoul.ai/api-reference/id-check/session

Defines the GET /liveness/session endpoint for creating a new ID verification session. Requires the 'id' query parameter to be set to true.

```yaml
openapi: 3.0.0
info:
  title: Verisoul ID Check API
  description: >-
    ID Check is a Verisoul platform add-on that combines facial biometrics with
    ID verification. The workflow prompts users to provide a valid ID document
    and perform a face scan to verify their identity.


    For users: the process is quick, works on any device/language, and requires
    a valid ID document.

    For developers: ID Check can be integrated within a couple hours of one
    developer's time.
  version: 1.0.0
  contact:
    name: Verisoul Support
    url: https://verisoul.ai
    email: support@verisoul.ai
servers:
  - url: https://api.sandbox.verisoul.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /liveness/session:
    get:
      tags:
        - Session
      summary: Get ID Check session
      description: >-
        Get a new session for ID Check verification. This is the first step in
        the ID Check workflow.
      operationId: createIDCheckSession
      parameters:
        - name: id
          in: query
          description: Flag to indicate that this session will include ID verification
          required: true
          schema:
            type: boolean
        - name: referring_session_id
          in: query
          description: ID of a referring session, if applicable
          required: false
          schema:
            type: string
            format: uuid
        - name: simulate
          in: query
          description: >-
            See [Simulate ID
            Check](/verifications/id-check/resources/simulate-id-check) for more
            information
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
              example:
                request_id: aad5cc61-1766-4546-a8a7-1790554b24ec
                session_id: 000ff417-cfe3-4d32-8323-59cb05b854cb
        '400':
          description: Bad request - groups enabled on project
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
                    description: Unique identifier for the request
                  success:
                    type: boolean
                    description: Indicates whether the request was successful
                  error:
                    type: string
                    enum:
                      - groups_enabled
                    description: Error code indicating the reason for failure
              example:
                request_id: e6f078a5-7931-4c41-ad53-1ef35a4ca762
                success: false
                error: groups_enabled
components:
  schemas:
    SessionResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: Unique identifier for the request
        session_id:
          type: string
          format: uuid
          description: Unique identifier for the session
      required:
        - request_id
        - session_id
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key authentication
```

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

### Initialize Verisoul Web SDK

Source: https://docs.verisoul.ai/integration/best-practices

Add the Verisoul script to the `<head>` section of your HTML to ensure it loads before the rest of your page content. Replace `{env}` and `{project_id}` with your specific environment and project ID.

```html
<head>
  <!-- Other head elements -->
  
  <!-- Verisoul script - place as early as possible -->
  <script async src="https://js.verisoul.ai/{env}/bundle.js" verisoul-project-id="{project_id}"></script>
</head>
```

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

### Verisoul SDK Initialization

Source: https://docs.verisoul.ai/integration/frontend/ios

Configures the Verisoul SDK with the required project credentials and environment settings.

```APIDOC
## Verisoul.shared.configure(env:projectId:)

### Description
Initializes the Verisoul SDK. This method must be called once when the application starts, typically in the AppDelegate.

### Parameters
#### Request Body
- **env** (enum) - Required - The environment to use: .prod for production or .sandbox for testing.
- **projectId** (string) - Required - Your unique Verisoul project identifier.

### Request Example
```swift
import VerisoulSDK

Verisoul.shared.configure(env: .prod, projectId: "your-project-id")
```
```

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

### Example Risk Score Interpretation

Source: https://docs.verisoul.ai/signals-scores/scoring-overview

This JSON object shows an example of how different risk scores are represented, with values indicating the likelihood of risk. Lower values suggest lower risk, while higher values indicate higher risk.

```json
{
    "account_score": 0.15,  // 15% - Low risk
    "bot": 0.87,  // 87% - High risk
    "multiple_accounts": 0.08,  // 8% - Low risk
}
```

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

### Get Session ID

Source: https://docs.verisoul.ai/integration/frontend/android

Retrieves the current session identifier for risk assessment.

```APIDOC
## Verisoul.getSessionId

### Description
Returns the current session identifier after the SDK has collected sufficient device data. This ID is required for backend risk assessment requests.

### Parameters
- **callback** (VerisoulSessionCallback) - Required - Callback interface to handle success (returning the sessionId) or failure (returning an exception).
```

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

### GET /session/{session_id}

Source: https://docs.verisoul.ai/api-reference/session/get

Retrieves detailed information about a specific session using its unique ID.

```APIDOC
## GET /session/{session_id}

### Description
Returns detailed information about a specific session.

### Method
GET

### Endpoint
/session/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - ID of the session to retrieve

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **account_ids** (array[string]) - List of account IDs associated with this session
- **request_id** (string) - The ID of the request
- **project_id** (string) - The ID of the project
- **session_id** (string) - The ID of the session
- **start_time** (string) - Timestamp when the session started
- **true_country_code** (string) - The true country code of the session
- **device_id** (string) - Device identifier from the session
- **network** (object) - Network information for the session
  - **ip_address** (string) - IP address of the session
  - **service_provider** (string) - Internet service provider
  - **connection_type** (string) - Type of network connection
- **location** (object) - Location information for the session
  - **continent** (string) - Continent of the session
  - **country_code** (string) - Country code of the session
  - **state** (string) - State of the session
  - **city** (string) - City of the session
  - **zip_code** (string) - Zip code of the session
  - **timezone** (string) - Timezone of the session
  - **latitude** (number) - Latitude coordinate
  - **longitude** (number) - Longitude coordinate
- **browser** (object) - Browser information for the session
  - **type** (string) - Browser type
  - **version** (string) - Browser version
  - **language** (string) - Browser language
  - **user_agent** (string) - Full user agent string
  - **timezone** (string) - Browser timezone
- **device** (object) - Device information for the session
  - **category** (string) - Device category (e.g., desktop, mobile)
  - **type** (string) - Device type (e.g., Mac, iPhone)
  - **os** (string) - Operating system of the device
  - **cpu_cores** (integer) - Number of CPU cores
  - **memory** (integer) - Device memory in GB
  - **gpu** (string) - GPU information
  - **screen_height** (integer) - Screen height in pixels
  - **screen_width** (integer) - Screen width in pixels
- **bot** (object) - Bot detection information
  - **mouse_num_events** (integer) - Number of mouse events
  - **click_num_events** (integer) - Number of click events
  - **keyboard_num_events** (integer) - Number of keyboard events
  - **touch_num_events** (integer) - Number of touch events
  - **clipboard_num_events** (integer) - Number of clipboard events
- **risk_signals** (object) - General risk signals
  - **device_risk** (boolean) - Indicates if device risk is detected
  - **proxy** (boolean) - Indicates if a proxy is used
  - **vpn** (boolean) - Indicates if a VPN is used
  - **tor** (boolean) - Indicates if Tor network is used
  - **spoofed_ip** (boolean) - Indicates if IP is spoofed
  - **datacenter** (boolean) - Indicates if the connection is from a datacenter
  - **recent_fraud_ip** (boolean) - Indicates if IP was recently involved in fraud
  - **impossible_travel** (boolean) - Indicates impossible travel detected
  - **device_network_mismatch** (boolean) - Indicates device and network mismatch
- **risk_signal_scores** (object) - Scores for various risk signals
  - **device_risk** (number) - Score for device risk
  - **proxy** (number) - Score for proxy usage
  - **vpn** (number) - Score for VPN usage
  - **tor** (number) - Score for Tor usage
  - **datacenter** (number) - Score for datacenter connection
  - **recent_fraud_ip** (number) - Score for recent fraud IP
  - **impossible_travel** (number) - Score for impossible travel
  - **device_network_mismatch** (number) - Score for device/network mismatch

#### Response Example
```json
{
  "account_ids": [
    "john-doe"
  ],
  "request_id": "7c1fb7c5-8e5f-43f0-b35e-56b9698dac0f",
  "project_id": "00000000-0000-0000-0000-000000000001",
  "session_id": "56f9a065-1583-48af-a5c4-cd5921b21a12",
  "start_time": "2025-06-10T16:45:21.822Z",
  "true_country_code": "US",
  "device_id": "6yONB4zT6k2i7SXvWkwC9s",
  "network": {
    "ip_address": "2600:1700:261:b810:8828:f0b6:3b95:667c",
    "service_provider": "AT&T Enterprises, LLC",
    "connection_type": "isp"
  },
  "location": {
    "continent": "NA",
    "country_code": "US",
    "state": "Texas",
    "city": "Austin",
    "zip_code": "78729",
    "timezone": "America/Chicago",
    "latitude": 30.4521,
    "longitude": -97.7688
  },
  "browser": {
    "type": "Chrome",
    "version": "137.0.0.0",
    "language": "en-US",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36",
    "timezone": "America/Chicago"
  },
  "device": {
    "category": "desktop",
    "type": "Mac",
    "os": "macOS 10.15.7",
    "cpu_cores": 16,
    "memory": 8,
    "gpu": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Max, Unspecified Version)",
    "screen_height": 1329,
    "screen_width": 2056
  },
  "bot": {
    "mouse_num_events": 84,
    "click_num_events": 2,
    "keyboard_num_events": 0,
    "touch_num_events": 0,
    "clipboard_num_events": 1
  },
  "risk_signals": {
    "device_risk": false,
    "proxy": false,
    "vpn": false,
    "tor": false,
    "spoofed_ip": false,
    "datacenter": false,
    "recent_fraud_ip": false,
    "impossible_travel": false,
    "device_network_mismatch": false
  },
  "risk_signal_scores": {
    "device_risk": 0.3971,
    "proxy": 0,
    "vpn": 0,
    "tor": 0,
    "datacenter": 0,
    "recent_fraud_ip": 0,
    "impossible_travel": 0,
    "device_network_mismatch": 0.0001
  }
}
```

#### Error Response (400)
- **statusCode** (integer) - The HTTP status code
- **message** (string) - Description of the error

#### Response Example
```json
{
  "statusCode": 400,
  "message": "Session ID not found"
}
```
```

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

### Initialize Verisoul SDK

Source: https://docs.verisoul.ai/integration/frontend/flutter

Configure the SDK in your main function before running the application.

```dart
import 'package:verisoul_sdk/verisoul.dart';

void main() {
   WidgetsFlutterBinding.ensureInitialized();
   VerisoulSdk.configure(projectId: "Project ID ", environment: VerisoulEnvironment.prod);
   runApp(const MyApp());
}
```

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

### GET /list

Source: https://docs.verisoul.ai/api-reference/lists/get

Retrieves a comprehensive list of all available classification lists within the Verisoul system.

```APIDOC
## GET /list

### Description
Returns all available lists configured in the Verisoul system, including their names and descriptions.

### Method
GET

### Endpoint
https://api.sandbox.verisoul.ai/list

### Response
#### Success Response (200)
- **request_id** (string) - The ID of the request
- **lists** (array) - Array of available lists
  - **name** (string) - The name of the list
  - **description** (string) - Description of the list's purpose

#### Response Example
{
  "request_id": "abb42d71-f4d4-440f-b1c7-a250ec0eddd7",
  "lists": [
    {
      "name": "allow",
      "description": "Marks every account in the list as Real."
    },
    {
      "name": "block",
      "description": "Marks every account in the list as Fake."
    },
    {
      "name": "main_account",
      "description": "Sets the multiple_accounts score to 0 for every account in the list."
    },
    {
      "name": "us_users",
      "description": "List of US based users"
    }
  ]
}
```

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

### Prebuild and Run Expo Project

Source: https://docs.verisoul.ai/integration/frontend/react-native

Commands to prebuild your Expo project and then run it on Android or iOS after configuring the Verisoul SDK.

```sh
npx expo prebuild --clean
npx expo run:android  # or npx expo run:ios
```

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

### OpenAPI Account Retrieval Specification

Source: https://docs.verisoul.ai/api-reference/account/get

Defines the GET /account/{account_id} endpoint and the associated AccountResponse schema.

```yaml
openapi: 3.0.1
info:
  title: Verisoul API
  description: The Verisoul API is used to integrate Verisoul into your application.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.sandbox.verisoul.ai
security:
  - apiKeyAuth: []
paths:
  /account/{account_id}:
    get:
      description: Returns detailed information about a specific account
      parameters:
        - name: account_id
          in: path
          description: ID of the account to retrieve
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account information response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
              example:
                project_id: 00000000-0000-0000-0000-000000000001
                request_id: 81fca4e3-0111-45b8-a8eb-0c2b638e1d29
                account:
                  id: john-doe
                  email: johndoe.example@gmail.com
                  metadata: {}
                  group: ''
                num_sessions: 1
                first_seen: '2025-06-10T16:47:29.661Z'
                last_seen: '2025-06-10T16:47:29.661Z'
                last_session: 56f9a065-1583-48af-a5c4-cd5921b21a12
                country: US
                countries:
                  - US
                decision: Real
                account_score: 0.2191
                bot: 0
                multiple_accounts: 0.2053
                risk_signals: 0.2979
                accounts_linked: 2
                lists:
                  - us_users
                unique_devices:
                  1_day: 1
                  7_day: 1
                unique_networks:
                  1_day: 1
                  7_day: 1
                email:
                  email: johndoe.example@gmail.com
                  disposable: false
                  personal: true
                  valid: true
                  domain_type: personal
                  email_score: 0
                  trust_signals:
                    - email_age_greater_than_5_years
                    - email_known_online_history
                  risk_signals:
                    - email_alias
                  num_account_from_domain: 156
                risk_signal_average:
                  device_risk: 0.3971
                  proxy: 0
                  vpn: 0
                  tor: 0
                  spoofed_ip: 0
                  datacenter: 0
                  recent_fraud_ip: 0
                  impossible_travel: 0
                  device_network_mismatch: 0.0001
        '400':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountError'
              example:
                statusCode: 400
                message: Account not found
components:
  schemas:
    AccountResponse:
      type: object
      properties:
        project_id:
          type: string
          description: The ID of the project
        request_id:
          type: string
          description: The ID of the request
        account:
          type: object
          properties:
            id:
              type: string
              description: The account identifier
            email:
              type: string
              description: The email associated with the account
            metadata:
              type: object
              additionalProperties: true
              description: Additional metadata about the account
            group:
              type: string
              description: >-
                Groups must be enabled for the project to use this field. See
                [Multi Accounting
                Groups](/integration/advanced/multi-accounting-groups) for more
                information.
        num_sessions:
          type: integer
          description: Number of sessions associated with this account
        first_seen:
          type: string
          format: date-time
          description: Timestamp when the account was first seen
        last_seen:
          type: string
          format: date-time
          description: Timestamp when the account was last seen
        last_session:
          type: string
          description: ID of the last session
        decision:
          type: string
          description: Decision about the account authenticity
        account_score:
          type: number
          format: float
          description: Overall account risk score
        bot:
          type: number
          format: float
          description: Bot detection score
        multiple_accounts:
          type: number
          format: float
          description: Multiple accounts detection score
        risk_signals:
          type: number
          format: float
```

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

### Define Name Claims

Source: https://docs.verisoul.ai/api-reference/types/email

Examples of providing name claims using first name, last name, or both.

```json
{ "name": { "first": "John", "last": "Doe" } }
```

```json
{ "name": { "first": "John" } }
```

```json
{ "name": { "last": "Doe" } }
```

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

### GET /account/{account_id}

Source: https://docs.verisoul.ai/api-reference/account/get

Retrieves detailed information, risk signals, and session data for a specific account identifier.

```APIDOC
## GET /account/{account_id}

### Description
Returns detailed information about a specific account, including risk scores, session history, and email validation signals.

### Method
GET

### Endpoint
/account/{account_id}

### Parameters
#### Path Parameters
- **account_id** (string) - Required - ID of the account to retrieve

### Response
#### Success Response (200)
- **project_id** (string) - The ID of the project
- **request_id** (string) - The ID of the request
- **account** (object) - Account details including id, email, metadata, and group
- **num_sessions** (integer) - Number of sessions associated with this account
- **first_seen** (string) - Timestamp when the account was first seen
- **last_seen** (string) - Timestamp when the account was last seen
- **last_session** (string) - ID of the last session
- **decision** (string) - Decision about the account authenticity
- **account_score** (number) - Overall account risk score
- **bot** (number) - Bot detection score
- **multiple_accounts** (number) - Multiple accounts detection score
- **risk_signals** (number) - Risk signals score

#### Response Example
{
  "project_id": "00000000-0000-0000-0000-000000000001",
  "request_id": "81fca4e3-0111-45b8-a8eb-0c2b638e1d29",
  "account": {
    "id": "john-doe",
    "email": "johndoe.example@gmail.com",
    "metadata": {},
    "group": ""
  },
  "num_sessions": 1,
  "first_seen": "2025-06-10T16:47:29.661Z",
  "last_seen": "2025-06-10T16:47:29.661Z",
  "last_session": "56f9a065-1583-48af-a5c4-cd5921b21a12",
  "decision": "Real",
  "account_score": 0.2191,
  "bot": 0,
  "multiple_accounts": 0.2053,
  "risk_signals": 0.2979
}
```

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

### GET /liveness/session

Source: https://docs.verisoul.ai/api-reference/face-match/session

Retrieves a new session for Face Match verification, serving as the initial step in the biometric workflow.

```APIDOC
## GET /liveness/session

### Description
Get a new session for Face Match verification. This is the first step in the Face Match workflow.

### Method
GET

### Endpoint
/liveness/session

### Parameters
#### Query Parameters
- **referring_session_id** (string) - Optional - ID of a referring session, if applicable
- **simulate** (string) - Optional - See Simulate Face Match for more information

### Response
#### Success Response (200)
- **request_id** (string) - Unique identifier for the request
- **session_id** (string) - Unique identifier for the session

#### Response Example
{
  "request_id": "db4ad346-e8f1-46cc-922d-f89ca8fb7ac7",
  "session_id": "00022912-cbaa-4239-a3ec-51c32fcc0fc1"
}
```

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

### Web Application Navigation

Source: https://docs.verisoul.ai/verifications/id-check/integration/navigate-to-idcheck

Example JavaScript code for redirecting users to the ID Check URL from a web application.

```APIDOC
## Navigation Options - Web

For web applications, you can redirect the user to the FaceMatch URL:

```javascript
function redirectToIDCheck(sessionId) {
  const redirectUrl = encodeURIComponent(window.location.origin + '/verification-complete');
  const idcheckUrl = `https://app.prod.verisoul.ai/?session_id=${sessionId}&redirect_url=${redirectUrl}`;
  
  window.location.href = idcheckUrl;
}
```

**Note**: If your user is on desktop, Face Match will automatically recognize this and display a QR code so that the user can complete the verification on their mobile device.
```

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

### Configure Verisoul Environment Variables

Source: https://docs.verisoul.ai/examples/web-sample-app

Copy the environment variable sample file and update it with your Verisoul API Key and Project ID. This is necessary for the application to authenticate with Verisoul services.

```bash
cp .env.sample .env
```

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

### Configure Web Integration

Source: https://docs.verisoul.ai/integration/frontend/flutter

Add the Verisoul script and Content Security Policy to your web/index.html.

```html
<script
  async
  src="https://js.verisoul.ai/{env}/bundle.js"
  verisoul-project-id="{project_id}"
></script>
```

```html
<meta
  http-equiv="Content-Security-Policy"
  content="script-src 'self' https://js.verisoul.ai; worker-src 'self' blob: data:;connect-src 'self' https://*.verisoul.ai wss://*.verisoul.ai;"
/>
```

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

### Retrieve Session Risk Scores

Source: https://docs.verisoul.ai/signals-scores/account-vs-session

Example of risk signals and their associated numerical scores derived from session data.

```json
"risk_signals": {
    "device_risk": false,
    "proxy": false,
    "vpn": false,
    "tor": false,
    "spoofed_ip": false,
    "datacenter": false,
    "recent_fraud_ip": false,
    "impossible_travel": false,
    "device_network_mismatch": false
},
"risk_signal_scores": {
    "device_risk": 0.0295,
    "proxy": 0,
    "vpn": 0,
    "tor": 0,
    "datacenter": 0,
    "recent_fraud_ip": 0,
    "impossible_travel": 0,
    "device_network_mismatch": 0.0001
}
```

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

### Account Object Structure Example

Source: https://docs.verisoul.ai/api-reference/types/account

This JSON represents the structure of an Account object, including its ID, email, and metadata.

```json
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "John",
    "signup_date": "2023-01-15"
  }
}
```

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

### Navigate to Face Match

Source: https://docs.verisoul.ai/verifications/face-match/integration/navigate-to-facematch

This section details how to construct the Face Match URL and use it to initiate the verification process.

```APIDOC
## Navigate to Face Match

Once you have fetched a valid session token, you can navigate the user to Verisoul's Face Match URL to complete the verification process.

### Face Match URL

The Face Match URL is:
`https://app.{env}.verisoul.ai/` where `{env}` is:

* `prod` for production
* `sandbox` for sandbox

The Face Match URL accepts the following query parameters:

### Parameters

#### Query Parameters
- **session_id** (string) - Required - The session token obtained from the Verisoul API
- **redirect_url** (string) - Optional - The URL encoded string to redirect to after the verification is complete (default: https://verisoul.ai)
- **lng** (string) - Optional - Language parameter to customize the instructions (default: en)

### On Completion

Once the Face Match session is complete, the user will be sent to the `redirect_url` configured in the query parameters. By default, Face Match redirects to `https://verisoul.ai`.

The completed redirect URL will contain the following parameters:

#### Query Parameters
- **session_id** (string) - The session ID used for the verification
- **success** (boolean) - Whether the verification was successful
- **error_message** (string) - Present only if success is `false`, contains the reason for failure

### Navigation Options

#### Web

For web applications, you can redirect the user to the Face Match URL:

```javascript
function redirectToFaceMatch(sessionId) {
  const redirectUrl = encodeURIComponent(window.location.origin + '/verification-complete');
  const facematchUrl = `https://app.prod.verisoul.ai/?session_id=${sessionId}&redirect_url=${redirectUrl}`;
  
  window.location.href = facematchUrl;
}
```

**Note**: If your user is on desktop, Face Match will automatically recognize this and display a QR code so that the user can complete the verification on their mobile device.

#### Mobile

For mobile applications, you can open Face Match in a webview:

```javascript
import { WebView } from 'react-native-webview';

function FaceMatchVerification({ sessionId, onComplete }) {
  const facematchUrl = `https://app.prod.verisoul.ai/?session_id=${sessionId}&redirect_url=yourapp://verification-complete`;
  
  return (
    <WebView
      source={{ uri: facematchUrl }}
      onNavigationStateChange={(navState) => {
        // Handle redirect back to your app
        if (navState.url.startsWith('yourapp://')) {
          // Extract parameters from URL
          const url = new URL(navState.url);
          const status = url.searchParams.get('status');
          const errorMessage = url.searchParams.get('error_message');
          
          onComplete({ status, errorMessage });
        }
      }}
    />
  );
}
```
```

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

### Mobile Application Navigation

Source: https://docs.verisoul.ai/verifications/id-check/integration/navigate-to-idcheck

Example React Native code for embedding the ID Check verification in a webview for mobile applications.

```APIDOC
## Navigation Options - Mobile

For mobile applications, you can open Face Match in a webview:

```javascript
import { WebView } from 'react-native-webview';

function IDCheckVerification({ sessionId, onComplete }) {
  const idcheckUrl = `https://app.prod.verisoul.ai/?session_id=${sessionId}&redirect_url=yourapp://verification-complete`;
  
  return (
    <WebView
      source={{ uri: facematchUrl }}
      onNavigationStateChange={(navState) => {
        // Handle redirect back to your app
        if (navState.url.startsWith('yourapp://')) {
          // Extract parameters from URL
          const url = new URL(navState.url);
          const status = url.searchParams.get('status');
          const errorMessage = url.searchParams.get('error_message');
          
          onComplete({ status, errorMessage });
        }
      }}
    />
  );
}
```
```

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

### Verify Webhook Signature in Go

Source: https://docs.verisoul.ai/email-intelligence/webhook-signature-verification

Implement webhook signature verification using Go. This example demonstrates how to parse the signature, validate the timestamp, and compute the HMAC-SHA256 hash to verify the request's authenticity. Ensure the 'WEBHOOK_SECRET' environment variable is set.

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"math"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

func verifySignature(body []byte, signature, secret string, headers http.Header, toleranceSec int64) bool {
	parts := make(map[string]string)
	for _, seg := range strings.Split(signature, ",") {
		idx := strings.Index(seg, "=")
		if idx < 0 {
			continue
		}
		parts[seg[:idx]] = seg[idx+1:]
	}

	t, ok := parts["t"]
	h, ok2 := parts["h"]
	v1, ok3 := parts["v1"]
	if !ok || !ok2 || !ok3 {
		return false
	}

	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil || int64(math.Abs(float64(time.Now().Unix()-ts))) > toleranceSec {
		return false
	}

	names := strings.Split(h, " ")
	vals := make([]string, len(names))
	for i, name := range names {
		vals[i] = headers.Get(name)
	}
	signedData := fmt.Sprintf("%s.%s.%s.%s", t, h, strings.Join(vals, "."), body)

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(signedData))
	expected := hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(expected), []byte(v1))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	signature := r.Header.Get("x-signature")

	if !verifySignature(body, signature, os.Getenv("WEBHOOK_SECRET"), r.Header, 300) {
		http.Error(w, `{"error":"Invalid signature"}`, http.StatusUnauthorized)
		return
	}

	var payload map[string]interface{}
	json.Unmarshal(body, &payload)
	fmt.Printf("Verified webhook: %v\n", payload["event_type"])

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{"status": "verified"})
}

func main() {
	http.HandleFunc("/webhook", webhookHandler)
	http.ListenAndServe(":3000", nil)
}
```

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

### Configure Android Maven Repository

Source: https://docs.verisoul.ai/integration/frontend/react-native

Add this Maven repository to your android/build.gradle file if the 'ai.verisoul:android' package cannot be downloaded.

```groovy
allprojects {
    repositories {
        // ...
        maven { url = uri("https://us-central1-maven.pkg.dev/verisoul/android") }
    }
}
```