Voice Biometrics API

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

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the verify call (POST /api/v1/voice-biometrics/verify), hammered per IVR turn. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_voicebioa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_voicebioa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "sample_ms", "value": "1500", "expected": "an integer in milliseconds, at least 3000" }
    },
    "meta": {
      "request_id": "req_voicebiob2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and enrol the customer first, then re-fire verify with a long enough sample instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_voicebioc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

404 — Not found

  {
    "error": {
      "code": "VOICEPRINT_NOT_ENROLLED",
      "message": "No voiceprint is enrolled for this customer yet.",
      "status": 404,
      "details": { "enrollment_state": "not_started" }
    },
    "meta": {
      "request_id": "req_voicebiod4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface enrolment — retrying a verify call cannot pass until enrolment completes.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`VOICEPRINT_NOT_ENROLLED` (404 not found)	Surface enrolment	Branch on `error.code`. Retrying a verify call cannot pass until enrolment completes.

List enrolled voiceprints

GET /api/v1/verify/voice-biometrics

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

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

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/node'

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);

{
  "data": {
    "rows": [
      {
        "id": "vp_3f8a2c9d1e4b6a7c",
        "contactId": "contact_8f2a1c9d",
        "enrolledByUserId": "usr_2b7f4c1a",
        "consentVersion": "gdpr-art9-v1",
        "enrollmentSpoofScore": 0.97,
        "sampleDurationMs": 6120,
        "modelEmbedVersion": "speechbrain-ecapa-v2",
        "modelSpoofVersion": "asvspoof-v3",
        "createdAt": "2026-08-22T09:41:12.000Z"
      }
    ],
    "nextCursor": "eyJkYXRlIjoiMjAyNi0wOC0yMlQwOTo0MToxMi4wMDBaIiwiaWQiOiJ2cF8zZjhhMmM5ZDllNGI2YTdjIn0="
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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): { id, status, voiceprint_id, confidence? }. Enrollment is synchronous, so a known id reports enrolled; an unknown or GDPR-erased id returns 404.

string

required

—

string (enum: true|false)

cURL

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

Node.js

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

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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", 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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
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);

{
  "data": {
    "id": "vp_3f8a2c9d1e4b6a7c",
    "status": "enrolled",
    "voiceprint_id": "vp_3f8a2c9d1e4b6a7c",
    "confidence": 0.97
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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.

string (enum: true|false)

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/node'

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);

{
  "data": {
    "enrolled_count": 3,
    "recent_events": [
      {
        "id": "vpe_9a3f2c1d",
        "phone_number": "contact_8f2a1c9d",
        "status": "passed",
        "confidence": 0.87,
        "occurred_at": "2026-08-26T11:58:40.000Z"
      }
    ],
    "far_trend_7d": [
      {
        "date": "2026-08-24",
        "far": 0
      },
      {
        "date": "2026-08-25",
        "far": 0.02
      },
      {
        "date": "2026-08-26",
        "far": 0
      }
    ],
    "settings": {
      "confidence_threshold": 0.75,
      "auto_2fa_on_low_confidence": true
    }
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

Id of the contact to challenge (1–255 characters). The returned nonce + phrase must echo back on the next POST /verify.

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 '{
  "contactId": "contact_8f2a1c9d"
}'

Node.js

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

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({
  "contactId": "contact_8f2a1c9d"
}),
})
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={
  "contactId": "contact_8f2a1c9d"
})
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(`{
  "contactId": "contact_8f2a1c9d"
}`)))
	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 = {
  "contactId": "contact_8f2a1c9d"
}.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
{
  "contactId": "contact_8f2a1c9d"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "nonceId": "chg_7e0a1b3c5d",
    "phrase": "739215",
    "expiresAt": "2026-08-26T12:05:00.000Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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 429 voiceprint_tenant_cap_exceeded if the tenant has reached its voice_biometrics.tenant_enroll_cap quota.

string

string (enum: true|false)

string

required

Id of the contact the voiceprint belongs to (1–255 characters).

string

required

Base64-encoded WAV clip (max 30s / 2MB) used to build the embedding. Rejected below the anti-spoof floor.

Verbatim GDPR Art. 9 consent text the speaker agreed to (10–5000 characters). Stored for the audit trail.

Version tag of the consent copy (e.g. gdpr-art9-v1), so revoking a version can target the right enrollments.

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 '{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
}'

Node.js

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

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({
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
}),
})
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={
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
})
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(`{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
}`)))
	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 = {
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
}.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
{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "consentText": "I consent to Devotel Orbit processing my voice for speaker verification (GDPR Art. 9).",
  "consentVersion": "gdpr-art9-v1"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "voiceprintId": "vp_3f8a2c9d1e4b6a7c",
    "enrolledAt": "2026-08-22T09:41:12.000Z",
    "modelVersions": {
      "embed": "speechbrain-ecapa-v2",
      "spoof": "asvspoof-v3"
    },
    "antiSpoofScore": 0.97,
    "deepfakeScore": 0.03
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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.

string

string (enum: true|false)

string

required

Id of the contact to verify against their enrolled voiceprints (1–255 characters).

string

required

Base64-encoded WAV probe clip (max 30s / 2MB). Both the cosine-similarity gate AND the anti-spoof gate must pass for a match.

string

The nonceId returned by POST /challenge. One-shot-consumed on verify; reuse/expiry/mismatch is rejected. Omit both challenge fields to skip liveness.

string

The exact phrase the caller read aloud — must match the phrase issued with the nonce.

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 '{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
}'

Node.js

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

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({
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
}),
})
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={
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
})
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(`{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
}`)))
	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 = {
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
}.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
{
  "contactId": "contact_8f2a1c9d",
  "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA…",
  "challengeNonceId": "chg_7e0a1b3c5d",
  "challengePhrase": "739215"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "match": true,
    "confidence": 0.87,
    "antiSpoof": true,
    "antiSpoofScore": 0.96,
    "voiceprintId": "vp_3f8a2c9d1e4b6a7c",
    "result": "passed",
    "thresholds": {
      "similarity": 0.75,
      "antiSpoof": 0.6
    },
    "challengeVerified": true,
    "deepfakeScore": 0.04
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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.

string (enum: true|false)

number

required

Cosine-similarity gate a verification must clear, between 0.50 (permissive) and 0.95 (strict). Values outside the range are rejected.

boolean

required

When true, a below-threshold verification signals downstream step-up flows to escalate to a second factor instead of 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.75,
  "auto_2fa_on_low_confidence": true
}'

Node.js

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

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.75,
  "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.75,
  "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.75,
  "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.75,
  "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.75,
  "auto_2fa_on_low_confidence": true
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "confidence_threshold": 0.75,
    "auto_2fa_on_low_confidence": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

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

Permanently deletes a voiceprint and its encrypted embedding. GDPR Article 17 right-to-erasure. Real DELETE (not soft-delete). Idempotent.

string

required

—

string (enum: true|false)

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/node'

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);

{
  "data": {
    "ok": true
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Voice Biometrics API

Voice Biometrics API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix

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

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​404 — Not found

​60-second retry matrix

​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

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix

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)