Get Current Biometric Session

curl --request GET \
  --url http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

api

kyc

biometric

entities

{entityId}

current

Get Current Biometric Session

curl --request GET \
  --url http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

import requests

url = "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Overview

This endpoint returns the most recent biometric session for an entity (by createdAt), regardless of status: pending, in_progress, approved, rejected, etc. It mirrors GET /api/kyc/entities/{entityId}/current for KYC validations.

If the entity has never had a biometric session, the API responds with 200 and null (not 404), same as the KYC current endpoint.

When to Use

Recover a pending session to re-embed sessionUrl or cancel it
Check status of the latest biometric attempt (status, rejectionCode, decision)
Resolve ACTIVE_SESSION_EXISTS when creating a new session: the active session id is here (or in activeSessionId on the 409 error)

Request

GET https://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "X-Organization-ID": "your-organization-uuid"
}

Response

200 OK — session found

{
  "id": "7618e10c-b1b1-408b-b361-1901077ced73",
  "entityId": "c16b457b-500a-4250-aefe-6d69bdf71fb2",
  "organizationId": "org-uuid",
  "status": "pending",
  "mode": "face_match",
  "sessionUrl": "https://kyc.example.com/session/abc123",
  "hostedSessionId": "e291f904-9c3f-490e-a51e-73434a14ba9a",
  "iframeAllow": "camera; microphone; fullscreen; autoplay; encrypted-media",
  "rejectionCode": null,
  "rejectionMessage": null,
  "createdAt": "2026-06-19T14:40:00.000Z",
  "updatedAt": "2026-06-19T14:40:00.000Z",
  "completedAt": null
}

200 OK — no sessions

null

Recommended Flow

POST /api/kyc/biometric/sessions → store id and sessionUrl
Embed sessionUrl in an iframe
Poll: GET /api/kyc/biometric/entities/{entityId}/current or GET /api/kyc/biometric/sessions/{id}
To restart: POST /api/kyc/biometric/sessions/{id}/cancel (pending / in_progress only)

Difference From List `currentSessionId`

GET /api/kyc/biometric/sessions?entityId=... includes currentSessionId: the latest approved session (active biometric verification). This /current endpoint returns the latest created session, which may be pending.

Field / endpoint	Meaning
`GET .../entities/:entityId/current`	Latest created session (any status)
`currentSessionId` in list	Latest approved session

Error When Creating a Second Session

If you try to create another session while one is active (pending / in_progress), you get 409 ACTIVE_SESSION_EXISTS with the blocking ID:

{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "Cannot create new biometric session. There is already a pending session for this entity. Please cancel or complete the existing session first.",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}

Cancel with POST /api/kyc/biometric/sessions/{activeSessionId}/cancel, then create again.

Embedded biometric session — create session
Biometric webhook events

⌘I

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

Services

Integrations

Interactive Tutorials

Get Current Biometric Session

Overview

When to Use

Request

Headers

Response

200 OK — session found

200 OK — no sessions

Recommended Flow

Difference From List `currentSessionId`

Error When Creating a Second Session

​Overview

​When to Use

​Request

​Headers

​Response

​200 OK — session found

​200 OK — no sessions

​Recommended Flow

​Difference From List currentSessionId

​Error When Creating a Second Session

​Related

Overview

When to Use

Request

Headers

Response

200 OK — session found

200 OK — no sessions

Recommended Flow

Difference From List `currentSessionId`

Error When Creating a Second Session

Related