Voice Biometrics API

Voice-print enrollment and speaker verification Base path: /api/v1/verify/voice-biometrics Endpoint count: 8

List enrolled voiceprints

GET /api/v1/verify/voice-biometrics/

Cursor-paginated list of voiceprints for this tenant. Returns metadata only — no embedding bytes.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Get voiceprint enrollment status

GET /api/v1/verify/voice-biometrics/enroll/{id}

Returns the enrollment status of a single voiceprint by id (the id returned by POST /enroll). Response shape is { id, status, voiceprint_id, confidence? }. Enrollment is synchronous, so a known id reports enrolled while an unknown or GDPR-erased id returns 404.

string

required

The voiceprint id to look up (the vp_-prefixed id returned by POST /enroll). Returns 404 if the id is unknown or its voiceprint was erased.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll/{id}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Voice biometrics overview

GET /api/v1/verify/voice-biometrics/overview

Returns enrolled voiceprint count, recent verification events, 7-day false-accept rate trend, and tenant threshold settings.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/overview');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

Issue a verification challenge nonce

POST /api/v1/verify/voice-biometrics/challenge

Issues a per-attempt liveness/replay-resist challenge phrase. The caller reads the returned phrase aloud, records the audio, and submits both the audio AND the nonceId+phrase on the next POST /verify. The verify path one-shot-consumes the nonce and rejects on missing/expired/reused/mismatched values, defeating recorded-voice replay attacks. 5-minute TTL.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/challenge');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Enroll a voiceprint

POST /api/v1/verify/voice-biometrics/enroll

Upload a WAV audio clip (base64) to enroll a new voiceprint for a contactId. Requires explicit GDPR Art. 9 consent. Rejected if anti-spoof score is below threshold. Returns a 429 with top-level code RATE_LIMIT_EXCEEDED and details.reason voiceprint_tenant_cap_exceeded if the tenant has reached its voice_biometrics.tenant_enroll_cap quota.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/enroll');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Verify a caller by voice

POST /api/v1/verify/voice-biometrics/verify

Upload a WAV audio clip (base64) to verify a contactId against their enrolled voiceprints. Both cosine similarity AND anti-spoof gates must pass.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/verify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Update voice biometrics tenant settings

PATCH /api/v1/verify/voice-biometrics/settings

Persist the per-tenant confidence threshold (0.50 permissive → 0.95 strict — governs the cosine-similarity gate on POST /verify) and the auto-escalate-to-2FA-on-low-confidence intent flag. Both values round-trip via GET /overview. Both fields are required — send the full pair on every request.

confidence_threshold

number

required

The cosine-similarity gate a verification must clear to pass, between 0.50 (most permissive) and 0.95 (most strict). Values outside this range are rejected.

auto_2fa_on_low_confidence

boolean

required

When true, a verification that falls below the threshold signals downstream step-up flows to escalate to a second factor instead of returning a hard fail.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"confidence_threshold": 0.85, "auto_2fa_on_low_confidence": true}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ confidence_threshold: 0.85, auto_2fa_on_low_confidence: true }),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.patch("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings", headers=headers, json={"confidence_threshold": 0.85, "auto_2fa_on_low_confidence": True})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings", bytes.NewBuffer([]byte(`{"confidence_threshold": 0.85, "auto_2fa_on_low_confidence": true}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = { confidence_threshold: 0.85, auto_2fa_on_low_confidence: true }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/settings');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{"confidence_threshold": 0.85, "auto_2fa_on_low_confidence": true}
JSON);
echo curl_exec($ch);

DELETE /api/v1/verify/voice-biometrics/{voiceprintId}

Permanently deletes a voiceprint and its encrypted embedding. GDPR Article 17 right-to-erasure. This is a real DELETE (not a soft-delete), so the record leaves no trace once removed.

This endpoint is not idempotent. A successful delete returns { "deleted": true }. Because the row is erased outright, a second DELETE of the same voiceprintId — including a client retry after a network timeout — returns 404 Not Found, the same as deleting an unknown id. Treat a 404 on retry as confirmation the voiceprint is already gone.

voiceprintId

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.delete("https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/verify/voice-biometrics/{voiceprintId}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

API Reference

All Endpoints

Voice Biometrics API

Voice Biometrics API

List enrolled voiceprints

Get voiceprint enrollment status

Voice biometrics overview

Issue a verification challenge nonce

Enroll a voiceprint

Verify a caller by voice

Update voice biometrics tenant settings

​Voice Biometrics API

​List enrolled voiceprints

​Get voiceprint enrollment status

​Voice biometrics overview

​Issue a verification challenge nonce

​Enroll a voiceprint

​Verify a caller by voice

​Update voice biometrics tenant settings

​Delete a voiceprint (GDPR erasure)

Voice Biometrics API

List enrolled voiceprints

Get voiceprint enrollment status

Voice biometrics overview

Issue a verification challenge nonce

Enroll a voiceprint

Verify a caller by voice

Update voice biometrics tenant settings

Delete a voiceprint (GDPR erasure)