Skip to content
Biometry

Enroll voice

POST
/v2/enrollments/voice

Enroll voice for voice recognition. Requires user_id, phrase, and at least one voice recording of that phrase. The voiceprint is built from four recordings. Supply four distinct takes: with fewer, the missing ones are padded with a copy and the resulting print carries a single take’s worth of variation, which verifies unreliably. A short enrollment still succeeds and reports meta.warnings.

Authorizations

Request Body required

object
request
required
object
user_id
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9._:@-]+$/
display_name

Optional human-readable label for the user (e.g. an email), recorded on the transaction for display. Never used as an identity; user_id remains the biometric key.

string
<= 256 characters
phrase
required

The phrase the user speaks in every recording. It applies to all four takes.

string
vocabulary

Optional vocabulary constraint.

string
voice
required

Recordings (e.g. WAV, MP3) of the user speaking phrase. Repeat the voice part once per recording; four distinct takes are strongly recommended.

Array<string>
>= 1 items

Responses

200

Enrollment attempt completed. A rejected recording also returns 200: meta.message is then failed to enroll voice and data.status is error or qafailed. Check the status field, not the HTTP status.

object
data

Endpoint-specific payload; omitted when the operation returns no data.

decision

Scoring decision computed for the request when a scoring system applies.

object
status

Decision status from the scoring engine (e.g. pass, fail, refer).

string
score
number
reasons
Array<string>
meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>
data
object
status

good (enrolled now) or enrolled (already enrolled) on success; error or qafailed when the recording was rejected.

string
qa_combined
object
key
additional properties
any
qa_list
Array<object>
object
key
additional properties
any
key
additional properties
any

400

Bad Request / Parameter Validation Failed.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

401

Unauthorized / Missing or Invalid Authentication Credentials.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

403

Forbidden / Service Not Enabled or Consent Required.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

422

Unprocessable Entity / Face not detected, audio unreadable, or file payload syntax error.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

500

Internal Server Error.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>