curl --request POST \
--url https://api.facesign.ai/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"clientReferenceId": "user-123",
"metadata": {
"source": "web-app"
},
"flow": [
{
"id": "start",
"type": "start",
"outcome": "greeting"
},
{
"id": "greeting",
"type": "conversation",
"prompt": "Say: Hello! What's your name?",
"outcomes": [
{
"id": "t1",
"condition": "user provided name",
"targetNodeId": "end"
}
]
},
{
"id": "end",
"type": "end"
}
]
}
EOFimport requests
url = "https://api.facesign.ai/sessions"
payload = {
"clientReferenceId": "user-123",
"metadata": { "source": "web-app" },
"flow": [
{
"id": "start",
"type": "start",
"outcome": "greeting"
},
{
"id": "greeting",
"type": "conversation",
"prompt": "Say: Hello! What's your name?",
"outcomes": [
{
"id": "t1",
"condition": "user provided name",
"targetNodeId": "end"
}
]
},
{
"id": "end",
"type": "end"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientReferenceId: 'user-123',
metadata: {source: 'web-app'},
flow: [
{id: 'start', type: 'start', outcome: 'greeting'},
{
id: 'greeting',
type: 'conversation',
prompt: 'Say: Hello! What\'s your name?',
outcomes: [{id: 't1', condition: 'user provided name', targetNodeId: 'end'}]
},
{id: 'end', type: 'end'}
]
})
};
fetch('https://api.facesign.ai/sessions', 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 => "https://api.facesign.ai/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'clientReferenceId' => 'user-123',
'metadata' => [
'source' => 'web-app'
],
'flow' => [
[
'id' => 'start',
'type' => 'start',
'outcome' => 'greeting'
],
[
'id' => 'greeting',
'type' => 'conversation',
'prompt' => 'Say: Hello! What\'s your name?',
'outcomes' => [
[
'id' => 't1',
'condition' => 'user provided name',
'targetNodeId' => 'end'
]
]
],
[
'id' => 'end',
'type' => 'end'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.facesign.ai/sessions"
payload := strings.NewReader("{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.facesign.ai/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.facesign.ai/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"session": {
"id": "<string>",
"createdAt": 123,
"settings": {
"clientReferenceId": "user-123",
"modules": [
{
"type": "emailVerification",
"name": "<string>",
"email": "<string>",
"publicRecognitionEnabled": true
}
],
"metadata": {
"source": "web-app",
"department": "sales"
},
"initialPhrase": "<string>",
"finalPhrase": "<string>",
"providedData": {},
"avatarId": "<string>",
"langs": [
"en",
"es",
"fr"
],
"defaultLang": "en",
"flow": [
{
"id": "<string>",
"type": "start",
"outcome": "<string>"
}
]
},
"startedAt": 123,
"finishedAt": 123,
"version": "<string>",
"report": {
"transcript": [
{
"id": "<string>",
"createdAt": 123,
"text": "<string>",
"isAvatar": true
}
],
"aiAnalysis": {
"ageMin": 123,
"ageMax": 123,
"overallSummary": "<string>",
"analysis": [
{
"title": "<string>",
"shortDescription": "<string>",
"longDescription": "<string>"
}
]
},
"location": {},
"device": {},
"livenessDetected": true,
"lang": "<string>",
"extractedData": {},
"screenshots": [
"<string>"
],
"videos": {
"avatarVideoUrl": "<string>",
"userVideoUrl": "<string>"
},
"isVerified": true
}
},
"clientSecret": {
"secret": "<string>",
"createdAt": 123,
"expireAt": 123,
"url": "<string>"
}
}{
"error": {
"type": "validation_error",
"message": "Invalid request parameters"
}
}{
"error": {
"type": "authentication_error",
"message": "Invalid API key provided"
}
}{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded"
}
}Create a verification session
Creates a new identity verification session with the specified configuration
curl --request POST \
--url https://api.facesign.ai/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"clientReferenceId": "user-123",
"metadata": {
"source": "web-app"
},
"flow": [
{
"id": "start",
"type": "start",
"outcome": "greeting"
},
{
"id": "greeting",
"type": "conversation",
"prompt": "Say: Hello! What's your name?",
"outcomes": [
{
"id": "t1",
"condition": "user provided name",
"targetNodeId": "end"
}
]
},
{
"id": "end",
"type": "end"
}
]
}
EOFimport requests
url = "https://api.facesign.ai/sessions"
payload = {
"clientReferenceId": "user-123",
"metadata": { "source": "web-app" },
"flow": [
{
"id": "start",
"type": "start",
"outcome": "greeting"
},
{
"id": "greeting",
"type": "conversation",
"prompt": "Say: Hello! What's your name?",
"outcomes": [
{
"id": "t1",
"condition": "user provided name",
"targetNodeId": "end"
}
]
},
{
"id": "end",
"type": "end"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
clientReferenceId: 'user-123',
metadata: {source: 'web-app'},
flow: [
{id: 'start', type: 'start', outcome: 'greeting'},
{
id: 'greeting',
type: 'conversation',
prompt: 'Say: Hello! What\'s your name?',
outcomes: [{id: 't1', condition: 'user provided name', targetNodeId: 'end'}]
},
{id: 'end', type: 'end'}
]
})
};
fetch('https://api.facesign.ai/sessions', 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 => "https://api.facesign.ai/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'clientReferenceId' => 'user-123',
'metadata' => [
'source' => 'web-app'
],
'flow' => [
[
'id' => 'start',
'type' => 'start',
'outcome' => 'greeting'
],
[
'id' => 'greeting',
'type' => 'conversation',
'prompt' => 'Say: Hello! What\'s your name?',
'outcomes' => [
[
'id' => 't1',
'condition' => 'user provided name',
'targetNodeId' => 'end'
]
]
],
[
'id' => 'end',
'type' => 'end'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.facesign.ai/sessions"
payload := strings.NewReader("{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.facesign.ai/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.facesign.ai/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"clientReferenceId\": \"user-123\",\n \"metadata\": {\n \"source\": \"web-app\"\n },\n \"flow\": [\n {\n \"id\": \"start\",\n \"type\": \"start\",\n \"outcome\": \"greeting\"\n },\n {\n \"id\": \"greeting\",\n \"type\": \"conversation\",\n \"prompt\": \"Say: Hello! What's your name?\",\n \"outcomes\": [\n {\n \"id\": \"t1\",\n \"condition\": \"user provided name\",\n \"targetNodeId\": \"end\"\n }\n ]\n },\n {\n \"id\": \"end\",\n \"type\": \"end\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"session": {
"id": "<string>",
"createdAt": 123,
"settings": {
"clientReferenceId": "user-123",
"modules": [
{
"type": "emailVerification",
"name": "<string>",
"email": "<string>",
"publicRecognitionEnabled": true
}
],
"metadata": {
"source": "web-app",
"department": "sales"
},
"initialPhrase": "<string>",
"finalPhrase": "<string>",
"providedData": {},
"avatarId": "<string>",
"langs": [
"en",
"es",
"fr"
],
"defaultLang": "en",
"flow": [
{
"id": "<string>",
"type": "start",
"outcome": "<string>"
}
]
},
"startedAt": 123,
"finishedAt": 123,
"version": "<string>",
"report": {
"transcript": [
{
"id": "<string>",
"createdAt": 123,
"text": "<string>",
"isAvatar": true
}
],
"aiAnalysis": {
"ageMin": 123,
"ageMax": 123,
"overallSummary": "<string>",
"analysis": [
{
"title": "<string>",
"shortDescription": "<string>",
"longDescription": "<string>"
}
]
},
"location": {},
"device": {},
"livenessDetected": true,
"lang": "<string>",
"extractedData": {},
"screenshots": [
"<string>"
],
"videos": {
"avatarVideoUrl": "<string>",
"userVideoUrl": "<string>"
},
"isVerified": true
}
},
"clientSecret": {
"secret": "<string>",
"createdAt": 123,
"expireAt": 123,
"url": "<string>"
}
}{
"error": {
"type": "validation_error",
"message": "Invalid request parameters"
}
}{
"error": {
"type": "authentication_error",
"message": "Invalid API key provided"
}
}{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded"
}
}Authorizations
API key authentication. Use format "Bearer sk_live_..." or "Bearer sk_test_..."
Body
- Option 1
- Option 2
Your internal reference ID for this session
"user-123"
Legacy module configuration (deprecated, use flow instead)
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
Show child attributes
Show child attributes
Custom metadata (max 50KB)
{
"source": "web-app",
"department": "sales"
}
Opening message from the avatar
Closing message from the avatar
Pre-filled user data
Show child attributes
Show child attributes
Specific avatar to use
Available languages for the session
["en", "es", "fr"]
Default language
"en"
Geographic zone
es, eu Flat array of nodes that defines the verification flow. Each node
carries its own outcome (START node) or outcomes (verification
nodes) that reference other node ids by string, so there is no
separate edges array. See the FSNode schema for per-type shapes.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
Show child attributes
Show child attributes