# Use real-time caller authentication with Voice ID in Amazon Connect
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Amazon Connect Voice ID provides real-time caller authentication and fraud risk detection which make voice interactions in contact centers more secure and efficient. Voice ID uses machine learning to verify the identity of genuine customers by analyzing a caller's unique voice characteristics. This allows contact centers to use an additional security layer that doesn't rely on the caller answering multiple security questions, and makes it easy to enroll and verify customers without changing the natural flow of their conversation. Voice ID also offers real-time detection of fraudsters who frequently target your contact center, thereby reducing losses due to fraud.
With Amazon Connect Voice ID you can:
+ Passively enroll customers for voice authentication without requiring them to repeat a particular word or phrase.
+ Migrate customers into Voice ID by enrolling them in batch.
+ Verify the enrolled customer's identity by analyzing their unique voice characteristics.
+ Detect fraudsters from a watchlist that you have created.
+ Detect voice spoofing.
## How Voice ID works
### Customer enrollment
1. When a customer calls for the first time, the agent confirms the identity of the caller by using existing security measures, such as asking for mother's maiden name or a one-time passcode (OTP) delivered by SMS. This ensures that only genuine customers are enrolled in Voice ID.
1. Voice ID starts listening to the customer's speech after the contact has encountered the [Set Voice ID](set-voice-id.md) block, where Voice ID is enabled. Voice ID listens to the call until one of the following happens:
+ It gets enough audio to evaluate the speaker for authentication, fraud, and enroll the speaker (if requested). This is 30 seconds of customer speech, excluding silence.
+ The call ends.
1. Voice ID then creates the enrollment voiceprint. A voiceprint is a mathematical representation that implicitly captures unique aspects of an individual's voice such as speech rhythm, pitch, intonation, and loudness.
The caller does not need to say or repeat any specific phrases to enroll in Voice ID.
### Customer authentication
1. When the enrolled customer calls back in, they are verified through an interaction with an IVR, or during their interaction with an agent.
By default Voice ID is configured to require 10 seconds of a caller's speech to authenticate, which can be done as part of a typical customer interaction in the IVR or with the agent (such as "what's your first and last name?" and "what are you calling about?"). You can adjust the amount of required speech using the [Authentication response time](set-voice-id.md#set-voice-id-properties-authentication-response-time) property in the [Set Voice ID](set-voice-id.md) block.
1. Voice ID uses the audio to generate the caller's voiceprint and compares it with the enrolled voiceprint corresponding to the claimed identity, and returns an authentication result.
For more information about the agent's experience, see [Enroll callers in Voice ID in the Contact Control Panel (CCP)](use-voiceid.md).
## How much speech is needed for enrollment and authentication
+ Enrollment: 30 seconds of customer net speech (speech that excludes any silence) to create a voiceprint and enroll a customer.
+ Verification: By default, 10 seconds of customer net speech to verify that the voice belongs to the claimed identity. The speech can be from interacting with an IVR or an agent. You can adjust the amount of required speech using the [Authentication response time](set-voice-id.md#set-voice-id-properties-authentication-response-time) property in the [Set Voice ID](set-voice-id.md).
## Batch enrollment
You can get a jump start on using biometrics by batch enrolling customers who have already consented for biometrics. Using stored audio recordings in your S3 bucket, and a JSON input file that provides the speaker identifier and a link to the audio recordings, you can invoke the Voice ID batch APIs.
For more information, see [Batch enrollment in Amazon Connect Voice ID using audio data from prior calls](voiceid-batch-enrollment.md).
## Known fraudster detection
There are a few steps to setting up the real-time detection of fraudsters:
1. [Create a new watchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_CreateWatchlist.html) for storing known fraudsters. Or, use the default watchlist that is created when Voice ID is enabled.
1. [Register fraudsters](voiceid-fraudster-watchlist.md) to the new watchlist or the default watchlist.
1. In the [Set Voice ID](set-voice-id.md) block, specify which watchlist you want to use.
When one of the fraudsters from the watchlist that is specified in the flow calls your contact center, Voice ID analyzes the call audio to return a risk score and outcome. This score indicates how closely the caller's voiceprint matches that of the fraudster's in the watchlist. Voice ID requires 10 seconds of audio to evaluate the call audio for fraud risk from known fraudsters.
### Default watchlist
When the Voice ID domain is created, Voice ID creates a default fraudster watchlist for that domain. The name and description of the default fraudster watchlist is encrypted using the KMS key that is provided in the domain and saved in Voice ID.
If you don't provide the fraudster watchlistId for fraud detection or fraudster registration, Voice ID uses the default fraudster watchlist.
You cannot update the metadata of the default fraudster watchlist, but you can associate or disassociate fraudsters from it.
**Note**
If your Voice ID domain was created before March 2023, when fraudster watchlists was launched: a default watchlist was created and all existing fraudsters have been placed in it.
## Voice spoofing detection
1. When a prospective fraudster tries to spoof caller audio using audio playback or synthesized speech, Voice ID returns a risk score and outcome to indicate the how likely it is that the voice is spoofed.
1. Voice spoofing is only enabled when you enable the fraud detection feature in your contact flow. Voice spoofing scores are not returned when only speaker authentication is enabled.
1. Voice ID requires 10 seconds of audio to evaluate the call audio for fraud risk from voice spoofing.
## What data is stored?
Voice ID stores audio files of the speaker's voice, voiceprints, and speaker identifiers. This data is encrypted using a KMS key that you provide.
If you enable detection of fraudsters in a watchlist, Voice ID also stores the fraudster audio and voiceprints. For more information, see [Data handled by Amazon Connect](data-handled-by-connect.md).
# Amazon Connect Voice ID end of support
After careful consideration, we decided to end support for Amazon Connect Voice ID, effective May 20, 2026. Amazon Connect Voice ID will no longer accept new customers beginning May 20, 2025. As an existing customer with an account signed up for the service before May 20, 2025, you can continue to use Amazon Connect Voice ID features. After May 20, 2026, you will no longer be able to use Amazon Connect Voice ID.
This page provides instructions and best practices for Amazon Connect IT administrators and users to transition Voice ID to alternate solutions to meet your business needs. This might include solutions from AWS Partners available on the AWS Marketplace, such as [Pindrop®](https://aws.amazon.com/marketplace/pp/prodview-f7rqlwjby3er4), or do-it-yourself solutions with AWS End User Messaging SMS.
## Do-it-yourself solutions with AWS End User Messaging SMS
You can improve contact center security by enabling One-Time-Pin (OTP) based authentication for your contact center with AWS End User Messaging SMS. You can reference a solution example for enabling OTPs using AWS End User Messaging SMS to create one for your contact center. For more information about this solution, see the following blog post: [Build a Secure One-Time Password Architecture with AWS](https://aws.amazon.com/blogs/messaging-and-targeting/build-a-secure-one-time-password-architecture-with-aws/). For more information about AWS End User Messaging SMS, see [What is AWS End User Messaging SMS?](https://docs.aws.amazon.com/sms-voice/latest/userguide/what-is-sms-mms.html)
## Managing your Voice ID data
You can get information about all your Voice ID domains in your AWS accounting using the Voice ID `ListDomains` API in conjunction with the `DescribeDomain` API. For more information about managing your Amazon Connect Voice ID domains, see [Manage Amazon Connect Voice ID domains](voiceid-domain-operations.md).
For a specific Voice ID domain, you can download data about enrolled callers using the `ListSpeakers` API and registered fraudsters using `ListFraudsters` API. For more information about speaker and fraudster management, see [Amazon Connect Voice ID speaker, watchlist, and fraudster management APIs](voiceid-speaker-fraudster-management-apis.md). You can ensure that all your customer data on Voice ID is deleted by using the Voice ID `DeleteDomain` API. You need to perform this operation for every Voice ID domain in every AWS Region and every account.
# Voice ID domains in Amazon Connect Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
When you enable Amazon Connect Voice ID, you create a Voice ID domain: a container for all Voice ID data, such as speaker identifiers (which serves as the customer identifier), the voiceprints, the customer audio that was used for creating the enrollment voiceprints, and the enrollment statuses (enrolled, opted out, etc.) associated with the speaker identifiers. For detection of fraudsters in a watchlist, the Voice ID domain stores the fraudster identifiers, voiceprints, and audio used for creating the voiceprints.
Following are guidelines for creating Voice ID domains:
+ Each Amazon Connect instance can be associated with only one Voice ID domain.
+ Each Voice ID domain can be associated with multiple Amazon Connect instances. This enables you to use the same stored customer data across multiple Amazon Connect instances.
+ You can create multiple domains, but they don't share customer data between each other.
+ We recommend creating a new Voice ID domain to associate with a Amazon Connect instance when:
+ You are enabling Voice ID for the first time on your account in an AWS Region.
+ You want to ensure that you isolate the Voice ID domains used for your test and production environments.
+ We recommend using an existing Voice ID domain when:
+ You want to use the same set of enrolled callers and fraudsters across different Amazon Connect instances (that may belong to different customer service teams)
+ You want to use the same test environment across different test Amazon Connect instances.
**Note**
Only existing Voice ID domains in the same Region in your Amazon Connect account can be shared across Amazon Connect instances in that Region.
+ You can change the association of your Amazon Connect instance from your current domain to a new domain at any time, by choosing a different domain.
+ To delete a Voice ID domain, use the [DeleteDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteDomain.html) Voice ID API. `DeleteDomain` soft deletes the domain. Amazon Connect waits 30 days before completely erasing the domain data. During this period, Voice ID; is disabled for all the Amazon Connect instances it is associated with. To restore a domain during this window, submit an Support ticket and provide the domain ID. You can find the domain ID on the Voice ID section of the Amazon Connect console, as shown in the following example:
![\[The Voice ID section of the Amazon Connect console displaying the domain ID field which is needed for domain restoration.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-domain.png)
Deleting a Voice ID domain deletes all stored customer data, such as audio recordings, voiceprints, and speaker identifiers, as well as any fraudster watchlists that you managed.
## Enrollment status
Voice ID stores three different enrollment status for a speaker: `ENROLLED`, ` OPTED_OUT` and `EXPIRED`. You can recall these speaker status using [Amazon Connect Voice ID APIs](https://docs.aws.amazon.com/voiceid/latest/APIReference/) and using contact flow blocks to take appropriate action.
+ `ENROLLED`: When you enroll a new caller is enrolled into Voice ID, Voice ID creates a new voiceprint and set the speaker status as `ENROLLED`. Even if you re-enroll the same caller into Voice ID, the status stays as `ENROLLED`.
+ `OPTED_OUT`: If a caller does not provide consent to enroll into biometrics, you can opt out the caller (in the Contact Control Panel) or using APIs. Voice ID creates a new entry for this caller and set the speaker's status `OPTED_OUT`. Voice ID does not generate any voiceprint or store any audio recording for the speaker. Future enrollment requests for this speaker is rejected unless their entry is deleted.
+ `EXPIRED`: If a caller's voiceprint has not been accessed or refreshed for 3 years, Voice ID changes the status to `EXPIRED`, and you are no longer able to perform authentications for this caller. You can re-enroll the caller again or delete the caller from Voice ID.
## Expired speakers
For BIPA compliance, Voice ID automatically expires speakers that have not been accessed for enrollment, re-enrollment, or successful authentication for three years.
To view a speaker’s last access, look at the `lastAccessedAt` attribute that is returned by the `DescribeSpeaker` and `ListSpeakers` APIs.
If you try to use the `EvaluateSesssion` API to authenticate an expired speaker, a `SPEAKER_EXPIRED` authentication decision is returned.
To use the expired speaker again, they must be re-enrolled.
## Speaker and fraudster identifiers
Voice ID uses speaker identifiers to refer to and retrieve the voiceprints in a Voice ID domain. We recommend that you use identifiers that do not contain an Personally Identifiable Information (PII) in the identifiers.
Voice ID creates two fields to refer to a caller:
+ `CustomerSpeakerId`: A identifier provided by the customer. It can be between 1-256 characters and can only contain: **a-z**, **A-Z**, **0-9**, **-** and **\$1**
+ `GeneratedSpeakerId`: A unique 22-character alphanumeric string that Voice ID creates and returns at the time of enrollment of the caller.
[Amazon Connect Voice ID speaker APIs](https://docs.aws.amazon.com/voiceid/latest/APIReference/Welcome.html) accept either form of speaker identifiers, but only emit `GeneratedSpeakerId` in the Voice ID event streams and contact records. If you want to re-record the caller to redo the voiceprint, you can enroll the caller with the same `CustomerSpeakerId`.
Similarly, Voice ID creates unique fraudster identifiers called `GeneratedFraudsterID` for every fraudster that you add to a watchlist in the domain. Voice ID returns the fraudster identifier if a fraudster is detected in a call when performing fraud risk detection.
# Get started enabling Voice ID in Amazon Connect
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
## Before you begin
Before you get started, complete the following tasks.
**Topics**
+ [Grant the required permissions](#enable-voiceid-permissions)
+ [Decide how to name your Voice ID domain](#enable-voiceid-domains)
+ [Create an AWS KMS key to encrypt data stored in the domain](#enable-voiceid-awsmanagedkey)
### Grant the required permissions
You must grant the required permissions to users, groups, or roles. For more information, see [AmazonConnectVoiceIDFullAccess](security_iam_awsmanpol.md#amazonconnectvoiceidfullaccesspolicy).
Access to Voice ID APIs using the Contact Control Panel (CCP) is disabled by default.
### Decide how to name your Voice ID domain
When you enable Voice ID, you are prompted to provide a friendly domain name that's meaningful to you such as your organization name, for example, *Voice ID-ExampleCorp*.
### Create an AWS KMS key to encrypt data stored in the domain
When you enable Voice ID, you are prompted to create or provide an [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys). It encrypts the customer data stored by Voice ID such as audio files, voiceprints, and the speaker identifiers.
Step-by-step instructions for creating these KMS keys are provided in [Step 2: Create a new Voice ID domain and encryption key](#enable-voiceid-step2).
Data at rest—specifically, freeform fields that you provide plus audio files/voiceprints—are encrypted under the KMS key you choose. Your customer managed key is created, owned, and managed by you. You have full control over the KMS key (AWS KMS charges apply).
When making calls to Voice ID for anything other than `CreateDomain` or `UpdateDomain`, the user making the call requires `kms:Decrypt` permissions for the key associated with the domain. When making calls to `CreateDomain` or `UpdateDomain`, the user also requires `kms:DescribeKey` and `kms:CreateGrant` permissions for the key. When you create (or update) a Voice ID domain, it creates a grant on the KMS key so that it can be used by Voice ID asynchronous processes (such as speaker enrollment) and by the Amazon Connect service-linked role during your flows. This grant includes an encryption context specifying the domain with which the key is associated. For more on grants, see [Using grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in the AWS Key Management Service Developer Guide.
If you create a domain and associate it with one key, store some data, and then change the KMS key to a different key, an asynchronous process will be triggered to re-encrypt the old data with the new KMS key. After this process completes, all of your domain's data will be encrypted under the new KMS key, and you may safely retire the old key. For more information, see [UpdateDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_UpdateDomain).
**Tip**
You can create KMS keys or provide an existing KMS key programmatically. For more information, see [Amazon Connect Voice ID APIs](https://docs.aws.amazon.com/voiceid/latest/APIReference/).
## Step 1: Read the BIPA Consent Acknowledgement
Reading the Biometric Privacy Act (BIPA) Consent Acknowledgement is a requirement to enable Voice ID. You need to do this once per account, across all Regions. You cannot do this step by using APIs. For more information about BIPA, see this Wikipedia article: [Biometric Information Privacy Act](https://en.wikipedia.org/wiki/Biometric_Information_Privacy_Act).
1. Open the Amazon Connect console at [https://console.aws.amazon.com/connect/](https://console.aws.amazon.com/connect/).
1. On the instances page, choose the instance alias. The instance alias is also your **instance name**, which appears in your Amazon Connect URL. The following image shows the **Amazon Connect virtual contact center instances** page, with a box around the instance alias.
![\[The Amazon Connect virtual contact center instances page, the instance alias.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/instance.png)
1. In the navigation pane, choose **Voice ID**. Read the BIPA Consent Acknowledgement, and accept if you agree.
![\[The Enable Voice ID page showing the BIPA (Biometric Information Privacy Act) Consent Acknowledgement button that users must read and accept before enabling Voice ID.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-bipa.png)
## Step 2: Create a new Voice ID domain and encryption key
You can perform this step using the Amazon Connect console or by using Amazon Connect and Voice ID APIs.
------
#### [ Amazon Connect console instructions ]
1. In the **Domain setup** section, choose **Create a new domain**.
![\[Domain setup interface with options to create a new domain or choose an existing one.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-enable-domain.png)
1. In the **Domain name** box, enter a friendly name that's meaningful to you, such as your organization name, for example, *VoiceID-ExampleCorp*.
1. Under **Encryption**, create or enter your own AWS KMS key for encrypting your Voice ID domain. Following are the steps to create your KMS key key:
1. Choose **Create KMS key**.
![\[Encryption section of the Voice ID setup page showing the 'Create AWS KMS key' button for creating a new encryption key.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-create-kms-key.png)
1. A new tab in your browser opens for the Key Management Service (KMS) console. On the **Configure key** page, choose **Symmetric**, and then choose **Next**.
![\[Configure key page with Symmetric key type selected for encryption and decryption.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/customer-profiles-create-kms-key-configure-key.png)
1. On the **Add labels** page, add a name and description for the KMS key, and then choose **Next**.
1. On the **Define key administrative permissions** page, choose **Next**.
1. On the **Define key usage permissions** page, choose **Next**.
1. On the **Review and edit key policy** page, choose **Finish**.
1. Return to the tab in your browser for the Amazon Connect console, **Voice ID** page. Click or tap in the **AWS KMS key** for the key you created to appear in a dropdown list. Choose the key you created.
1. Choose **Enable Voice ID**.
------
#### [ API instructions ]
1. Call the [CreateDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_CreateDomain.html) API to create a new Voice ID domain.
1. Call the [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html) API to associate the Voice ID domain with the Amazon Connect instance.
1. Pass the ARN of the Voice ID domain just created into the `IntegrationArn` parameter. For `IntegrationType` use `VOICE_ID`.
------
You've enabled Voice ID for your instance. The following has been created:
+ Your Voice ID domain and a default fraudster watchlist that will hold your fraudsters.
+ A managed Amazon EventBridge rule in your account. This rule is used to ingest Voice ID events for creating contact records related to Voice ID. Additionally, Amazon Connect adds [Voice ID permissions](connect-slr.md) to the service-linked role for Amazon Connect.
Next, in Step 3 you configure how you want Voice ID to work in your flow.
## Step 3: Configure Voice ID in your contact flow
In this step you add the required blocks to your flow and configure how you want Voice ID to work.
+ [Play prompt](play.md): Add this block before the [Set Voice ID](set-voice-id.md) block to stream audio properly. You can edit it to include a simple message such as "Welcome."
+ [Set Voice ID](set-voice-id.md): After the [Play prompt](play.md) block, add the [Set Voice ID](set-voice-id.md) block. It should be at the start of a call. Use this block to start streaming audio to Amazon Connect Voice ID to verify the caller's identity, as soon as the call is connected to a flow.
In **Set Voice ID** block you configure the authentication threshold, response time, fraud threshold, and fraudster watchlist to be used for known fraudster detection.
+ [Set contact attributes](set-contact-attributes.md): Use to pass the `CustomerId` attribute to Voice ID. The `CustomerId` may be a customer number from your CRM, for example. You can create a Lambda function to pull the unique customer ID of the caller from your CRM system. Voice ID uses this attribute as the `CustomerSpeakerId` for the caller.
**Note**
`CustomerId` can be an alphanumeric value. It supports only \$1 and - (underscore and hyphen) special characters. It does not need to be UUID. Since Voice ID stores biometric information for each speaker, we strongly recommend that you use an identifier that does not contain PII in the CustomerSpeakerId field. For more information, see `CustomerSpeakerId` in the [Speaker](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_Speaker.html) data type.
+ [Check Voice ID](check-voice-id.md): Use to check the response from Voice ID for enrollment status, voice authentication, and fraud detection, and then branch based on one of the returned statuses.
### Example Voice ID flow
**Caller not enrolled**
1. When a customer calls for the first time, their `CustomerId` is passed to Voice ID using the [Set contact attributes](set-contact-attributes.md) block.
1. Voice ID looks for `CustomerId` in its database. Since it's not there, it sends a **Not enrolled** result message. The [Check Voice ID](check-voice-id.md) block branches based on this result, and you can decide what the next step should be. For example, you might want agents to enroll the customer in voice authentication.
1. Voice ID starts listening to the customer's speech after the contact has encountered the [Set Voice ID](set-voice-id.md) block, where Voice ID is enabled. It listens until it accummulates 30 seconds of net speech or the call ends, whichever happens first.
**Caller enrolled**
1. The next time the customer calls, Voice ID finds their `CustomerId` in the database.
1. Voice ID starts listening to the audio to create a voiceprint. The voiceprint that is created this time is used for authentication purposes so Voice ID can compare if the caller had been enrolled previously.
1. It compares the caller's current voiceprint with the stored voiceprint associated with the claimed identity. It returns a result based on the **Authentication threshold** property you configured in the [Set Voice ID](set-voice-id.md) block.
1. After it evaluates the speech, it returns the message **Authenticated** if the voiceprints are similar. Or it returns one of the other statuses.
1. The contact is then routed down the appropriate branch by the [Check Voice ID](check-voice-id.md) block.
# Security profile permissions for Amazon Connect Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
+ To enable users to search for contacts by their Voice ID status, assign the following **Analytics and Optimization** permission to their security profile:
+ **Voice ID - attributes and search**: Enables users to search for and view Voice ID results on the **Contact detail** page.
+ To grant agents access to Voice ID in the Contact Control Panel, assign the following permission in the **Contact Control Panel** group:
+ **Voice ID - Access**: Enables controls in the Contact Control Panel so agents can:
+ View authentication outcomes.
+ Opt-out or re-authenticate a caller.
+ Update `SpeakerID`.
+ View fraud detection results, rerun fraud analysis (fraud detection decision, fraud type and score).
**Note**
The functionality to enter or update the `SpeakerID` is not available with the default Voice ID widget in the CCP. To include the option for updating the `SpeakerID`, implement the `updateVoiceIdSpeakerId` [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams) API in your custom CCP.
The following image shows an example of these controls on the CCP:
![\[Contact Control Panel (CCP) showing Voice ID controls including enrollment status, authentication result, and buttons for enrolling or opting out customers.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-ccp-controls.png)
For information about how to add more permissions to an existing security profile, see [Update security profiles in Amazon Connect](update-security-profiles.md).
By default, the **Admin** security profile already has permissions to perform all Voice ID activities.
# Search for and review results of Voice ID authentication
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Use the [Contact search](contact-search.md) page to search for and review the results of enrollment status, voice authentication, and detection of fraudsters in a watchlist. With the required [ security profile permissions](contact-search.md#required-permissions-search-contacts) (**Analytics and Optimization** - **Voice ID - attributes and search - View**), you can search for Voice ID results using the following filters:
+ **Speaker actions**: Use this filter to search for contacts where the caller was enrolled into Voice ID or chose to opt-out of Voice ID altogether.
+ **Authentication result**: Use this filter to search for contacts where Voice ID authentication returned the following results:
+ Authenticated
+ Not authenticated
+ Opted out
+ Inconclusive
+ Not enrolled
For example, if you want to search for all contacts where the authentication status was returned as **Not authenticated** or **Opted out**, select both these options and choose **Apply**.
+ **Fraud detection result**: Use this filter to search for contacts where Voice ID fraud analysis returned the following results:
+ High risk for fraud
+ Low risk for fraud
+ Inconclusive
+ **Fraud detection reason**: Use this filter to search for contacts where specific fraud risk mechanisms were detected:
+ Known fraudster: the caller’s voice matches a fraudster from the fraudster watchlist you have created.
+ Voice spoofing: the caller is modifying their voice or is using speech synthesis to spoof the agent.
## Voice ID results in a contact record
After you search for a contact, you can choose an ID to view their contact record. The following image shows an example of the fields in the Voice ID section of the contact record:
![\[Voice ID section of a contact record showing authentication results, fraudster detection status, fraudster ID and watchlist ID fields.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/voiceid-ctr-nospoofing.png)
# Manage Amazon Connect Voice ID with the Voice ID APIs
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
To manage Voice ID programmatically, see [Amazon Connect Voice ID APIs](https://docs.aws.amazon.com/voiceid/latest/APIReference/).
This section explains how to perform common scenarios using the Voice ID APIs.
**Topics**
+ [Manage Amazon Connect Voice ID domains](voiceid-domain-operations.md)
+ [Amazon Connect Integration Association APIs](voiceid-integration-association-apis.md)
+ [Speaker, watchlist, and fraudster management APIs](voiceid-speaker-fraudster-management-apis.md)
+ [Batch enrollment in Amazon Connect Voice ID using audio data from prior calls](voiceid-batch-enrollment.md)
+ [File schema for Speaker Enrollment Job](speaker-enrollment-job-schema.md)
+ [Create and edit a fraudster watchlist in Amazon Connect Voice ID](voiceid-fraudster-watchlist.md)
+ [File schema for Fraudster Registration Job](fraudster-registration-schema.md)
+ [Amazon Connect Streams APIs to integrate Voice ID](voiceid-streams-apis.md)
# Manage Amazon Connect Voice ID domains
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Amazon Connect Voice ID provides APIs for you manage Voice ID domains. You can find equivalents for Create, Describe, List, and Update in the AWS Console.
1. [CreateDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_CreateDomain.html): To create a new Voice ID domain, use the `CreateDomain` Voice ID API. When the Voice ID domain is created, a default fraudster watchlist to hold your fraudsters is created at the same time.
Note the following guidelines when using the `CreateDomain` API:
+ You can only invoke this for your account after you have acknowledged the BIPA Consent in the AWS console.
+ You must also specify the KMS key for the Voice ID domain at the time of creation.
+ After creating a Voice ID domain, use the [Amazon Connect association APIs](https://docs.aws.amazon.com/connect/latest/APIReference/) to associate it with an Amazon Connect instance.
1. [DeleteDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteDomain.html): To delete a Voice ID domain, you must invoke the `DeleteDomain` Voice ID API and provide the domain ID. If this domain was associated with an Amazon Connect instance, Voice ID API calls, and Voice ID flow blocks will return runtime error. Deleting a Voice ID domain deletes all stored customer data such as audio recordings, voiceprints and speaker identifiers, as well as fraudster lists that you managed.
1. [DescribeDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DescribeDomain.html): Use this API to return the name, description and encryption configuration of an existing domain identified by its `DomainID`.
1. [ListDomains](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_ListDomains.html): Use this API to list all your Voice ID domains owned by your account in the Region.
1. [UpdateDomain](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_UpdateDomain.html): To update the name and encryption configuration for a domain, you can use the `UpdateDomain` Voice ID API. This API clobbers existing attributes, and you must provide both these fields.
When you change the KMS key associated with the Voice ID domain, following the `UpdateDomain` call your domain's existing data will be asynchronously re-encrypted under the new KMS key. You can check status of this process from your domain's `ServerSideEncryptionUpdateDetails` attribute using the `DescribeDomain` API. While this update process is in progress, you must retain your old KMS key in an accessible state, otherwise this process may fail. After this process completes, the old KMS key may be safely retired.
# Voice ID and Amazon Connect Integration Association APIs
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
You can use the following APIs to manage associations with Amazon Connect instances. You can perform these operations on the AWS Console as well.
1. [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html): To enable Voice ID on an Amazon Connect instance, you will need to associate a Voice ID domain with a Amazon Connect instance using a `CreateIntegrationAssociation` request. You can only associate one Voice ID domain to an Amazon Connect instance. If the instance is already associated with a domain, the API returns the following error:
`DuplicateResourceException` (409) - Request is trying to created a duplicate resource.
**Note**
When you enable Voice ID for an Amazon Connect instance (by using either the Amazon Connect console or the [CreateIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateIntegrationAssociation.html) API), Amazon Connect creates a managed Amazon EventBridge rule in your account. This rule is used to ingest Voice ID events for creating contact records related to Voice ID. Additionally, Amazon Connect adds [Voice ID permissions](connect-slr.md) to the service-linked role for Amazon Connect.
1. [DeleteIntegrationAssociation](https://docs.aws.amazon.com/connect/latest/APIReference/API_DeleteIntegrationAssociation.html): To delete an existing association between an Amazon Connect instance and a Voice ID domain, you will need to call the `DeleteIntegrationAssociation` APIs along with the Amazon Connect InstanceID and the `IntegrationAssociationID` returned by `CreateIntegrationAssociation`. This is a required step if you want to associate a different Voice ID domain to this Amazon Connect instance. We do not recommend deleting associations in a production setup as it can cause unpredictable behavior for Voice ID in your Amazon Connect instance.
1. [ListIntegrationAssociations](https://docs.aws.amazon.com/connect/latest/APIReference/API_ListIntegrationAssociations.html): To list all the associations between Amazon Connect instance and Voice ID domains for your account in this Region, you can invoke `ListIntegrationAssociations` API.
# Amazon Connect Voice ID speaker, watchlist, and fraudster management APIs
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Amazon Connect Voice ID includes APIs to manage speakers enrolled into a Voice ID domain and fraudsters registered in the domain. All speaker APIs, except `ListSpeakers`, accept either the `CustomerSpeakerId` or `GeneratedSpeakerId`.
## Speaker management APIs
1. [DescribeSpeaker](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DescribeSpeaker.html): Describe a speaker's [status in a domain (ENROLLED, OPTED\$1OUT, EXPIRED)](voiceid-domain.md#voiceid-speaker-enrollments), and to map a `GeneratedSpeakerId` to a `CustomerSpeakerId`, and vice versa.
1. [DeleteSpeaker](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteSpeaker.html): Completely remove all records for a caller/speaker from a Voice ID domain. All voiceprints and enrollment status is deleted immediately, and associated audio recordings are removed within 24 hours.
1. [ListSpeakers](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_ListSpeakers.html): List all the speakers whose entries are present in a Voice ID domain. This API returns both the `CustomerSpeakerId` and `GeneratedSpeakerId` for a speaker. It returns a paginated output with the page size dictated in the API request.
1. [OptOutSpeaker](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_OptOutSpeaker.html): Opt out a caller from a Voice ID domain. This API doesn't require the speaker to be present in Voice ID. A non-existing speaker can be opted-out using this API and Voice ID persists the opted out status and rejects future enrollment requests for this speaker. Opting out also removes voiceprints and any stored audio recordings for this caller.
## Watchlist management APIs
1. [CreateWatchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_CreateWatchlist.html): Create a watchlist that fraudsters can be a part of.
1. [DeleteWatchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteWatchlist.html): Remove a custom fraudster watchlist from the Voice ID domain. To delete a watchlist, it must be empty. That is, it must not have any fraudsters associated to it. You can use the [DeleteFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteFraudster.html) or [DisassociateFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DisassociateFraudster.html) APIs to remove all fraudsters from a watchlist.
You cannot delete the default watchlist from a Voice ID domain.
1. [DescribeWatchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DescribeWatchlist.html): Determine if it is a default fraudster watchlist, or a custom watchlist that you created, and obtain watchlist details.
1. [ListWatchlists](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_ListWatchlists.html): List all the watchlists in the Voice ID domain.
1. [UpdateWatchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_UpdateWatchlist.html): Update the name and description of a custom fraudster watchlist. You cannot modify details of the default watchlist because it's managed by Voice ID.
## Fraudster management APIs
1. [AssociateFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_AssociateFraudster.html): Associate a fraudster to a watchlist in the same domain. You can associate a fraudster to multiple watchlists in a domain.
1. [DeleteFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DeleteFraudster.html): Delete a fraudster from a Voice ID domain. Deleting the fraudster removes the fraudster from all watchlists it is a part of. It also deletes all voiceprints and associated audio recordings within 24 hours.
1. [DescribeFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DescribeFraudster.html): Describe a fraudster's status in the Voice ID domain.
1. [DisassociateFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_DisassociateFraudster.html): Disassociate a fraudsters from the watchlist specified. Note that a fraudster always has to be associated with at least one fraudster watchlist; an exception is thrown if you try to disassociate a fraudster from its only watchlist.
To remove the fraudster completely, use `DeleteFraudster`.
1. [ListFraudsters](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_ListFraudsters.html): List all the fraudsters in a domain or a specific watchlist. This API also returns the watchlists the fraudster is a part of. It returns a paginated output with the page size dictated in the API request.
# Batch enrollment in Amazon Connect Voice ID using audio data from prior calls
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
You can get a jump start on using biometrics by batch enrolling customers who have already consented for biometrics. Using stored audio recordings in your S3 bucket, and a JSON input file that provides the speaker identifier and a link to the audio recordings, you can invoke the [Voice ID batch](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_StartSpeakerEnrollmentJob.html) APIs.
To enroll customers programmatically, pass the following data to the API:
1. The domain ID to specify the domain to associate recordings to.
1. The location for the output file.
1. An input file containing a list of speakers. See [Input and output file schema for the Speaker Enrollment Job in Amazon Connect Voice ID](speaker-enrollment-job-schema.md).
For each speaker the file must include:
+ A link to a call audio recording in a .wav file with 8KHz sample rate and PCM-16 encoding.
+ The corresponding `CustomerSpeakerId` for the customer.
+ A channel for the caller in the audio recording. If the audio has multiple channels, you can select only one.
1. A KMS key to use when writing the output.
1. A role that Voice ID can assume. It must have access to the S3 bucket where the audio files are stored. This role must have access to any KMS key used to encrypt the files. It must also be able to write to the specified output location and use the KMS key requested for writing the output. Specifically, it must have the following permissions:
+ `s3:GetObject` on the input bucket.
+ `s3:PutObject` on the output bucket.
+ `kms:Decrypt` on the KMS key used for input bucket’s default encryption.
+ `kms:Decrypt` and `kms:GenerateDataKey` on the KMS key provided in the input which will be used for writing output file to the output bucket.
You must have `iam:PassRole` permissions when making the call and providing the `dataAccessRole`. To enable confused deputy protection for the `dataAccessRole`, see [Amazon Connect Voice ID cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md#voiceid-cross-service).
1. Optionally, a fraud check skip flag in case you want to skip checks for fraud and voice spoofing on the enrollment audio.
1. Optionally, specify a fraudster watchlist that you want to perform fraud checks against. If no watchlist is specified, Voice ID uses the default fraudster watchlist for the domain.
1. Optionally, the fraud threshold in case you want to raise or lower the risk.
1. Optionally, a flag to re-enroll enrolled customers. This is useful if you want to refresh the audio recording, since the default is to ignore previously enrolled customers.
The batch enrollment returns the `CustomerSpeakerId`, `GeneratedSpeakerId`, and associated status for each entry. It stores this data in a JSON file at the output path you specify in the API.
**Note**
You are charged for enrolling speakers. For more information, see [Amazon Connect Voice ID Pricing](https://aws.amazon.com/connect/pricing/).
# Input and output file schema for the Speaker Enrollment Job in Amazon Connect Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
## Input file schema
Following is the schema of the input manifest file for the Speaker Enrollment Job:
```
{
"Version": "string",
"SpeakerEnrollmentRequests": [
{
"RequestId": "string",
"SpeakerId": "string",
"AudioSpecifications": [
{
"S3Uri": "string",
"ChannelId": number
}
]
}
]
}
```
**Note**
All the fields in the schema are **required**.
Following is a description of each attribute of the input schema.
+ `Version`: The version of the input schema document. Currently, this should be `1.0`.
+ `SpeakerEnrollmentRequests`: List of speaker enrollment requests to be fulfilled as part of the job.
+ `RequestId`: An identifier for this speaker enrollment request. It must be unique within the input file. It is used for mapping and identifying entries in the output file.
+ `SpeakerId`: The client-provided identifier of the speaker who needs to be enrolled. You must pass the `CustomerSpeakerId` in this field. The `GeneratedSpeakerId` is not currently supported.
+ `AudioSpecifications`: The list of audio files that Voice ID can use for enrolling this speaker. Voice ID uses these audio files together to gather required amount of speech for enrollment. Currently, the maximum number of audio files allowed for an enrollment request is **10**. Each file can be a .wav file up to 20MB, containing audio with 8KHz sample rate and PCM-16 encoding.
+ `S3URI`: The Amazon S3 location of the audio file in .wav format that needs to be used for enrolling the speaker.
+ `ChannelId`: The audio channel to be used for enrolling the speaker in a multi-channel audio file. Voice ID supports audio files with up to two channels, so this value is restricted to either **0** or **1**.
## Output file schema
Following is the schema of the output file generated for the Speaker Enrollment Job:
```
{
"Version": "string",
"Errors": [
{
"RequestId": "string",
"ErrorCode": number,
"ErrorMessage": "string"
}
],
"SuccessfulEnrollments": [
{
"RequestId": "string",
"GeneratedSpeakerId": "string",
"CustomerSpeakerId": "string",
"EnrollmentStatus": "DUPLICATE_SKIPPED" | "NEW_ENROLLMENT" | "ENROLLMENT_OVERWRITE"
}
]
}
```
Following is a description of each attribute of the output schema.
+ `Version`: The version of the output schema document. Currently, this should be `1.0`.
+ `Errors`: The list of errors for the speaker enrollment requests that failed at some point during enrollment.
+
+ `RequestId`: The request identifier associated with this request. This is the same as the `RequestId` specified in the input file for this request.
+ `ErrorCode`: The HTTP error code representing the type of error. Some example error scenarios are described below.
**Note**
This is not an exhaustive list.
+ 400 (Bad Request Exception):
+ The input JSON file is malformed and cannot be parsed.
+ The provided audio files do not have enough speech for enrollment.
+ Fraud verification checks failed for the given speaker.
+ 402 (ServiceQuotaLimitExceededException):
+ Speaker limit exceeded.
+ 409 (Conflict Exception):
+ Conflicting action: You cannot request an enrollment for an opted out speaker.
+ 500 (Internal Failure):
+ Internal Server Error (Unexpected error on the Service-side).
+ `ErrorMessage`: A message describing the cause of the enrollment failure.
+ `SuccessfulEnrollments`: The list of enrollment requests that succeeded.
+ `RequestId`: The request identifier associated with this request. This is the same as the `RequestId` specified in the input file for this request.
+ `CustomerSpeakerId`: The client-provided identifier for the speaker who was enrolled.
+ `GeneratedSpeakerId`: The service-generated identifier for the speaker who was enrolled.
+ `EnrollmentStatus`: The status of successful speaker enrollment
+ `DUPLICATE_SKIPPED`: The speaker is already enrolled, and the enrollment was skipped.
+ `NEW_ENROLLMENT`: The speaker was newly enrolled into the system.
+ `ENROLLMENT_OVERWRITE`: The speaker is already enrolled, but was re-enrolled/overwritten using the new audio.
# Create and edit a fraudster watchlist in Amazon Connect Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Use the following APIs to create a fraudster watchlist and register fraudsters:
1. Use the [CreateWatchlist](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_CreateWatchlist.html) API to create new fraudster watchlists.
1. Use the [StartFraudsterRegistrationJob](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_StartFraudsterRegistrationJob.html) API for batch registration. You can register new fraudsters to the new watchlist, or register them to the default watchlist that is associated with the Voice ID domain.
When registering a new fraudster, Voice ID compares the voiceprint against all registers fraudsters in your Voice ID domain to determine if it is a duplicate of an existing fraudster.
To add fraudsters to a specified fraudster watchlist, pass the following data to the API:
1. The domain ID to specify the domain to associate recordings to.
1. An input file containing a list of fraudsters. See [Input and output file schema for the Fraudster Registration Job in Amazon Connect Voice ID](fraudster-registration-schema.md).
1. The location for output file.
1. A KMS key to use when writing the output.
1. A role that Voice ID can assume. It must have access to the S3 bucket where the audio files are stored. This role must have access to any KMS key used to encrypt the files. It must also be able to write to the specified output location and use the KMS key requested for writing the output. Specifically, it must have the following permissions:
+ `s3:GetObject` on the input bucket.
+ `s3:PutObject` on the output bucket.
+ `kms:Decrypt` on the KMS key used for input bucket’s default encryption.
+ `kms:Decrypt` and `kms:GenerateDataKey` on the KMS key provided in the input which will be used for writing output file to the output bucket.
You must have `iam:PassRole` permissions when making the call and providing the `dataAccessRole`. To enable confused deputy protection for the `dataAccessRole`, see [Amazon Connect Voice ID cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md#voiceid-cross-service).
1. A watchlistId to register the fraudster to. If no watchlistId is specified, fraudsters are registered to the default watchlist for that Voice ID domain.
1. The threshold for establishing the duplicate status of fraudsters.
1. A flag to ignore fraudster duplicates.
Voice ID updates the fraudster list with successful additions, and return a `GeneratedFraudsterID` associated with entry back to the same S3 location. If duplicates are identified, Voice ID returns a "duplicate" status for the entry and provides the closest matching `GeneratedFraudsterId`. After a fraudster is registered successfully, you can associate this fraudster identified by the `GeneratedFraudsterID` into a new watchlist by using the [AssociateFraudster](https://docs.aws.amazon.com/voiceid/latest/APIReference/API_AssociateFraudster.html) API.
Voice ID is not able to perform detection of fraudsters in a watchlist before the fraudster list is created.
For quotas for the fraudster list, see [Amazon Connect service quotas](amazon-connect-service-limits.md).
**Note**
You are charged for adding to the fraudster list. For more information, see [Amazon Connect Voice ID Pricing](https://aws.amazon.com/connect/voice-id/).
# Input and output file schema for the Fraudster Registration Job in Amazon Connect Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
## Input file schema
Following is the schema of the input manifest file for Fraudster Registration Jobs:
```
{
"Version": "string",
"FraudsterRegistrationRequests": [
{
"RequestId": "string",
"AudioSpecifications": [
{
"S3Uri": "string",
"ChannelId": number
}
]
}
]
}
```
**Note**
All the fields in the schema are **required**.
Following is a description of each attribute of the input schema.
+ `Version`: The version of the schema document. Currently, this should be `1.0`.
+ `FraudsterRegistrationRequests`: List of fraudster registration requests to be fulfilled as part of the job.
+ `RequestId`: An identifier for this fraudster registration request. It must be unique within the input file. It is used for mapping and identifying entries in the output file.
+ `AudioSpecifications`: The list of audio files that Voice ID can use for registering this fraudster. Voice ID uses these audio files together to gather required amount of speech for registration. Currently, the maximum number of audio files allowed for a registration request is **10**. Each file can be a .wav file up to 20MB, containing audio with 8KHz sample rate and PCM-16 encoding.
+ `S3URI`: The Amazon S3 location of the audio file in .wav format that needs to be used for registering the fraudster.
+ `ChannelId`: The audio channel to be used for registering the fraudster in a multi-channel audio file. Voice ID supports audio files with up to two channels, so this value is restricted to either **0** or **1**.
## Output file schema
Following is the schema of the output manifest file for Fraudster Registration Jobs:
```
{
"Version": "string",
"Errors": [
{
"RequestId": "string",
"ErrorCode": number,
"ErrorMessage": "string"
}
],
"SuccessfulRegistrations": [
{
"RequestId": "string",
"GeneratedFraudsterId": "string",
"RegistrationStatus": "DUPLICATE_SKIPPED" | "NEW_REGISTRATION",
"FraudsterSimilarityScore": number
}
]
}
```
Following is a description of each attribute of the output schema.
+ `Version`: The version of the output schema document. Currently, this should be `1.0`.
+ `Errors`: The list of errors for the fraudster registration requests that failed at some point during registration.
+
+ `RequestId`: The request identifier associated with this request. This is the same as the `RequestId` specified in the input file for this request.
+ `ErrorCode`: The HTTP error code representing the type of error. Some example error scenarios are described below.
**Note**
This is not an exhaustive list.
+ 400 (Bad Request Exception):
+ The input JSON file is malformed and cannot be parsed.
+ The provided audio files do not have enough speech for registration.
+ 402 (ServiceQuotaLimitExceededException):
+ Fraudster limit exceeded.
+ 500 (Internal Failure):
+ Internal Server Error (Unexpected error on the Service-side).
+ `ErrorMessage`: A message describing the cause of the fraudster registration failure.
+ `SuccessfulRegistrations`: The list of registration requests that succeeded.
+ `RequestId`: The request identifier associated with this request. This is the same as the `RequestId` specified in the input file for this request.
+ `RegistrationStatus`: The status of successful fraudster registration.
+ `DUPLICATE_SKIPPED`: The fraudster was identified as a duplicate, and the registration was skipped.
+ `NEW_FRAUDSTER`: The Fraudster was newly enrolled into the system.
+ `GeneratedFraudsterId`: The service-generated identifier for the fraudster who was registered. In case the `RegistrationStatus` is `DUPLICATE_SKIPPED`, this is the identifier of the fraudster already in the domain that is the closest match to the given fraudster.
+ `FraudsterSimilarityScore`: An optional field that is populated when the fraudster registration is skipped due to it being a duplicate. This represents the similarity of the given fraudster with the closest matching fraudster already existing in the domain.
# Amazon Connect Streams APIs to integrate Voice ID
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Use the following [Amazon Connect Streams](https://github.com/aws/amazon-connect-streams) APIs to integrate Voice ID into your existing agent web applications.
+ `enrollSpeakerInVoiceId`: Enroll a customer to Voice ID after obtaining their consent to enroll.
+ `evaluateSpeakerWithVoiceId`: Check the customer's Voice ID authentication status, and to detect fraudsters.
+ `optOutVoiceIdSpeaker`: Opt out a customer from Voice ID.
+ `getVoiceIdSpeakerStatus`: Describe the enrollment status of a customer.
+ `getVoiceIdSpeakerId`: Get the `SpeakerID` for a customer.
+ `updateVoiceIdSpeakerId`: Update the `SpeakerID` for a customer.
You can also use the Voice ID widget in the Contact Control Panel (CCP) if you don't want to build a custom agent interface. For more information about Voice ID in the CCP, see [Enroll callers in Voice ID in the Contact Control Panel (CCP)](use-voiceid.md).
# Amazon Connect Voice ID event schema
**Note**
End of support notice: On May 20, 2026, AWS will end support for Amazon Connect Voice ID. After May 20, 2026, you will no longer be able to access Voice ID on the Amazon Connect console, access Voice ID features on the Amazon Connect admin website or Contact Control Panel, or access Voice ID resources. For more information, visit [Amazon Connect Voice ID end of support](https://docs.aws.amazon.com/connect/latest/adminguide/amazonconnect-voiceid-end-of-support.html).
Voice ID generates events for every transaction: enrollment, authentication, or detection of fraudsters in a watchlist. Events are sent to the EventBridge default event bus.
You can create an analytics pipeline for Voice ID authentication outcomes and detection of fraudsters in a watchlist by using EventBridge to monitor Voice ID events. Using the schema available in this topic, you can configure EventBridge rules to listen and filter for Voice ID events that are relevant, and then process them through Amazon Data Firehose to store in a data warehouse of your choice.
For example, you may want near real-time tracking of Voice ID analysis. To do that, you can pull all the `Evaluate-Session` events, and get the `authenticationResult` and `fraudDetectionResult`.
Events are emitted on a [best effort](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) basis.
## Common fields in the event
+ `version` - The version of the event data.
+ `id` - A unique identifier of the event generated by EventBridge
+ `detail-type` - An identifier for the details of the event.
+ `source` - The source of the event. This is always `aws.voiceid`.
+ `account` - AWS account ID.
+ `timestamp` - The date and time that the event was published in UTC.
+ `region` - The AWS Region where the API call was made.
+ `resources` - Resources used by the API call.
+ `detail` - Details about the event:
+ `detail.sourceId` - A unique ID generated by Voice ID that you can use for de-duplication.
+ `detail.action` - Analogous to the API being invoked.
+ `detail.status` - Specifies the status of the action: success or failure.
+ `detail.errorInfo` - Is populated when the specified action errors out at Voice ID.
Following are the schemas for the events are that emitted.
## Start Session Action
Emits events on stream start (after setup), stream end, and on failures.
```
{...commonfields
"detail-type": "VoiceId Start Session Action",
"detail": {
"sourceId": String,
"action": "START_SESSION",
"status": String,
"domainId": String,
"session": {
"sessionId": String,
"sessionName": String,
"authenticationConfiguration": {
"acceptanceThreshold":Integer
},
"fraudDetectionConfiguration": {
"riskThreshold":Integer,
"watchlistId": String
},
"streamingConfiguration": {
"authenticationMinimumSpeechInSeconds": Integer
},
"enrollmentAudioProgress": {
"audioAggregationStatus": String,
"audioAggregationStartedAt": "Timestamp",
"audioAggregationEndedAt": "Timestamp"
},
"authenticationAudioProgress": {
"audioAggregationStartedAt": "Timestamp",
"audioAggregationEndedAt": "Timestamp"
},
"fraudDetectionAudioProgress": {
"audioAggregationStartedAt": "Timestamp",
"audioAggregationEndedAt": "Timestamp"
},
"generatedSpeakerId": String
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## Update Session Action
Emits events when the internal session update succeeds or fails.
```
{...commonfields
"detail-type": "VoiceId Update Session Action",
"detail": {
"sourceId": String,
"action": "UPDATE_SESSION",
"status": String,
"domainId": String,
"session": {
"sessionId": String,
"sessionName": String,
"authenticationConfiguration": {
"acceptanceThreshold": Integer
},
"fraudDetectionConfiguration": {
"riskThreshold": Integer,
"watchlistId": String
},
"streamingConfiguration": {
"authenticationMinimumSpeechInSeconds": Integer
},
"generatedSpeakerId": String
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## Evaluate Session Action
Emits events when the session evaluation succeeds or fails. Reasons can be KNOWN\$1FRAUDSTER or VOICE\$1SPOOFING.
```
{...commonfields
"detail-type": "VoiceId Evaluate Session Action",
"detail": {
"sourceId": String,
"action": "EVALUATE_SESSION",
"status": String,
"domainId": String,
"session": {
"sessionId": String,
"sessionName": String,
"generatedSpeakerId": String,
"streamingStatus": String,
"authenticationResult": {
"authenticationResultId": String,
"decision": String,
"score": Integer,
"audioAggregationStartedAt": "Timestamp",
"audioAggregationEndedAt": "Timestamp",
"configuration": {
"acceptanceThreshold": Integer
}
},
"fraudDetectionResult": {
"fraudDetectionResultId": String,
"decision": String,
"reasons": [String],
"audioAggregationStartedAt": "Timestamp",
"audioAggregationEndedAt": "Timestamp",
"configuration": {
"riskThreshold": Integer
},
"riskDetails": {
"knownFraudsterRisk": {
"generatedFraudsterId": String,
"riskScore": Integer,
"watchlistId": String
},
"voiceSpoofingRisk": {
"riskScore": Integer
}
}
}
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## Speaker Action
Emits events on the success or failure to opt out a speaker, delete a speaker, or enroll a speaker.
```
{...commonfields
"detail-type": "VoiceId Speaker Action",
"detail": {
"sourceId": String,
"domainID": String,
"action": String,
"status": String,
"generatedSpeakerId": String,
"data": {
"enrollmentSource": String,
"enrollmentSourceId": String,
"enrollmentStatus": String
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## Fraudster Action
Emits events when a fraudster is successfully registered or deleted.
Events are not sent when a fraudster is associated or disassociated with a watchlist.
```
{...commonfields
"detail-type": "VoiceId Fraudster Action",
"detail": {
"sourceId": String,
"domainID": String,
"action": String,
"status": String,
"generatedFraudsterId": String,
"watchlistIds": [String],
"data": {
"registrationSource": String,
"registrationSourceId": String,
"registrationStatus": String
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## EnrollBySession
Emits this event when an enrollment request is submitted. A `Speaker` event is emitted when the actual enrollment succeeds or fails.
```
{...commonfields
"detail-type": "VoiceId Session Speaker Enrollment Action",
"detail": {
"sourceId": String,
"domainId": String,
"action": "SESSION_ENROLLMENT_REQUEST",
"status": String,
"sessionId": String,
"sessionName": String,
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## StartSpeakerEnrollmentJob
Emits this event when a batch enrollment request is submitted, succeeds, or fails. A `Speaker` event is emitted for each of the individual speakers to indicate if corresponding enrollment succeeds or fails.
```
{...commonfields
"detail-type": "VoiceID Batch Speaker Enrollment Action",
"detail": {
"sourceId": String,
"domainId": String,
"action": "BATCH_ENROLLMENT_REQUEST",
"status": String,
"batchJobId": String,
"data": {
"dataAccessRoleArn": String,
"enrollmentConfig": {
"existingEnrollmentAction": String,
"fraudDetectionConfig": {
"fraudDetectionAction": String,
"riskThreshold": Integer,
"watchlistIds": [String],
}
},
"inputDataConfig": {
"s3Uri": String
},
"outputDataConfig": {
"s3Uri": String,
"kmsKeyId": String
}
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```
## StartFraudsterRegistrationJob
Emits this event when a batch registration request is submitted, succeeds, or fails. A `Fraudster` event is emitted for each of the individual fraudsters to indicate if corresponding registration succeeds or fails.
```
{...commonfields
"detail-type": "VoiceId Batch Fraudster Registration Action",
"detail": {
"sourceId": String,
"domainId": String,
"action": "BATCH_REGISTRATION_REQUEST",
"status": String,
"batchJobId": String,
"data": {
"dataAccessRoleArn": String,
"registrationConfig": {
"duplicateRegistrationAction": String,
"fraudsterSimilarityThreshold": Integer,
"watchlistIds": [String],
}
"inputDataConfig": {
"s3Uri": String
},
"outputDataConfig": {
"s3Uri": String,
"kmsKeyId": String
}
},
"errorInfo": {
"errorMessage": String,
"errorType": String,
"errorCode": Integer
}
}
}
```