:doc:`VoiceID <../../voice-id>` / Client / start_speaker_enrollment_job

****************************
start_speaker_enrollment_job
****************************



.. py:method:: VoiceID.Client.start_speaker_enrollment_job(**kwargs)

  

  Starts a new batch speaker enrollment job using specified details.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/voice-id-2021-09-27/StartSpeakerEnrollmentJob>`_  


  **Request Syntax**
  ::

    response = client.start_speaker_enrollment_job(
        ClientToken='string',
        DataAccessRoleArn='string',
        DomainId='string',
        EnrollmentConfig={
            'ExistingEnrollmentAction': 'SKIP'|'OVERWRITE',
            'FraudDetectionConfig': {
                'FraudDetectionAction': 'IGNORE'|'FAIL',
                'RiskThreshold': 123,
                'WatchlistIds': [
                    'string',
                ]
            }
        },
        InputDataConfig={
            'S3Uri': 'string'
        },
        JobName='string',
        OutputDataConfig={
            'KmsKeyId': 'string',
            'S3Uri': 'string'
        }
    )
    
  :type ClientToken: string
  :param ClientToken: 

    A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If not provided, the Amazon Web Services SDK populates this field. For more information about idempotency, see `Making retries safe with idempotent APIs <https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/>`__.

    This field is autopopulated if not provided.

  
  :type DataAccessRoleArn: string
  :param DataAccessRoleArn: **[REQUIRED]** 

    The IAM role Amazon Resource Name (ARN) that grants Voice ID permissions to access customer's buckets to read the input manifest file and write the job output file. Refer to `Batch enrollment using audio data from prior calls <https://docs.aws.amazon.com/connect/latest/adminguide/voiceid-batch-enrollment.html>`__ for the permissions needed in this role.

    

  
  :type DomainId: string
  :param DomainId: **[REQUIRED]** 

    The identifier of the domain that contains the speaker enrollment job and in which the speakers are enrolled.

    

  
  :type EnrollmentConfig: dict
  :param EnrollmentConfig: 

    The enrollment config that contains details such as the action to take when a speaker is already enrolled in Voice ID or when a speaker is identified as a fraudster.

    

  
    - **ExistingEnrollmentAction** *(string) --* 

      The action to take when the specified speaker is already enrolled in the specified domain. The default value is ``SKIP``, which skips the enrollment for the existing speaker. Setting the value to ``OVERWRITE`` replaces the existing voice prints and enrollment audio stored for that speaker with new data generated from the latest audio.

      

    
    - **FraudDetectionConfig** *(dict) --* 

      The fraud detection configuration to use for the speaker enrollment job.

      

    
      - **FraudDetectionAction** *(string) --* 

        The action to take when the given speaker is flagged by the fraud detection system. The default value is ``FAIL``, which fails the speaker enrollment. Changing this value to ``IGNORE`` results in the speaker being enrolled even if they are flagged by the fraud detection system.

        

      
      - **RiskThreshold** *(integer) --* 

        Threshold value for determining whether the speaker is a high risk to be fraudulent. If the detected risk score calculated by Voice ID is greater than or equal to the threshold, the speaker is considered a fraudster.

        

      
      - **WatchlistIds** *(list) --* 

        The identifier of watchlists against which fraud detection is performed.

        

      
        - *(string) --* 

        
    
    
  
  :type InputDataConfig: dict
  :param InputDataConfig: **[REQUIRED]** 

    The input data config containing the S3 location for the input manifest file that contains the list of speaker enrollment requests.

    

  
    - **S3Uri** *(string) --* **[REQUIRED]** 

      The S3 location for the input manifest file that contains the list of individual enrollment or registration job requests.

      

    
  
  :type JobName: string
  :param JobName: 

    A name for your speaker enrollment job.

    

  
  :type OutputDataConfig: dict
  :param OutputDataConfig: **[REQUIRED]** 

    The output data config containing the S3 location where Voice ID writes the job output file; you must also include a KMS key ID to encrypt the file.

    

  
    - **KmsKeyId** *(string) --* 

      The identifier of the KMS key you want Voice ID to use to encrypt the output file of a speaker enrollment job/fraudster registration job.

      

    
    - **S3Uri** *(string) --* **[REQUIRED]** 

      The S3 path of the folder where Voice ID writes the job output file. It has a ``*.out`` extension. For example, if the input file name is ``input-file.json`` and the output folder path is ``s3://output-bucket/output-folder``, the full output file path is ``s3://output-bucket/output-folder/job-Id/input-file.json.out``.

      

    
  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Job': {
              'CreatedAt': datetime(2015, 1, 1),
              'DataAccessRoleArn': 'string',
              'DomainId': 'string',
              'EndedAt': datetime(2015, 1, 1),
              'EnrollmentConfig': {
                  'ExistingEnrollmentAction': 'SKIP'|'OVERWRITE',
                  'FraudDetectionConfig': {
                      'FraudDetectionAction': 'IGNORE'|'FAIL',
                      'RiskThreshold': 123,
                      'WatchlistIds': [
                          'string',
                      ]
                  }
              },
              'FailureDetails': {
                  'Message': 'string',
                  'StatusCode': 123
              },
              'InputDataConfig': {
                  'S3Uri': 'string'
              },
              'JobId': 'string',
              'JobName': 'string',
              'JobProgress': {
                  'PercentComplete': 123
              },
              'JobStatus': 'SUBMITTED'|'IN_PROGRESS'|'COMPLETED'|'COMPLETED_WITH_ERRORS'|'FAILED',
              'OutputDataConfig': {
                  'KmsKeyId': 'string',
                  'S3Uri': 'string'
              }
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Job** *(dict) --* 

        Details about the started speaker enrollment job.

        
        

        - **CreatedAt** *(datetime) --* 

          A timestamp of when the speaker enrollment job was created.

          
        

        - **DataAccessRoleArn** *(string) --* 

          The IAM role Amazon Resource Name (ARN) that grants Voice ID permissions to access customer's buckets to read the input manifest file and write the job output file.

          
        

        - **DomainId** *(string) --* 

          The identifier of the domain that contains the speaker enrollment job.

          
        

        - **EndedAt** *(datetime) --* 

          A timestamp of when the speaker enrollment job ended.

          
        

        - **EnrollmentConfig** *(dict) --* 

          The configuration that defines the action to take when the speaker is already enrolled in Voice ID, and the ``FraudDetectionConfig`` to use.

          
          

          - **ExistingEnrollmentAction** *(string) --* 

            The action to take when the specified speaker is already enrolled in the specified domain. The default value is ``SKIP``, which skips the enrollment for the existing speaker. Setting the value to ``OVERWRITE`` replaces the existing voice prints and enrollment audio stored for that speaker with new data generated from the latest audio.

            
          

          - **FraudDetectionConfig** *(dict) --* 

            The fraud detection configuration to use for the speaker enrollment job.

            
            

            - **FraudDetectionAction** *(string) --* 

              The action to take when the given speaker is flagged by the fraud detection system. The default value is ``FAIL``, which fails the speaker enrollment. Changing this value to ``IGNORE`` results in the speaker being enrolled even if they are flagged by the fraud detection system.

              
            

            - **RiskThreshold** *(integer) --* 

              Threshold value for determining whether the speaker is a high risk to be fraudulent. If the detected risk score calculated by Voice ID is greater than or equal to the threshold, the speaker is considered a fraudster.

              
            

            - **WatchlistIds** *(list) --* 

              The identifier of watchlists against which fraud detection is performed.

              
              

              - *(string) --* 
          
        
      
        

        - **FailureDetails** *(dict) --* 

          Contains details that are populated when an entire batch job fails. In cases of individual registration job failures, the batch job as a whole doesn't fail; it is completed with a ``JobStatus`` of ``COMPLETED_WITH_ERRORS``. You can use the job output file to identify the individual registration requests that failed.

          
          

          - **Message** *(string) --* 

            A description of the error that caused the batch job failure.

            
          

          - **StatusCode** *(integer) --* 

            An HTTP status code representing the nature of the error.

            
      
        

        - **InputDataConfig** *(dict) --* 

          The input data config containing an S3 URI for the input manifest file that contains the list of speaker enrollment job requests.

          
          

          - **S3Uri** *(string) --* 

            The S3 location for the input manifest file that contains the list of individual enrollment or registration job requests.

            
      
        

        - **JobId** *(string) --* 

          The service-generated identifier for the speaker enrollment job.

          
        

        - **JobName** *(string) --* 

          The client-provided name for the speaker enrollment job.

          
        

        - **JobProgress** *(dict) --* 

          Provides details on job progress. This field shows the completed percentage of registration requests listed in the input file.

          
          

          - **PercentComplete** *(integer) --* 

            Shows the completed percentage of enrollment or registration requests listed in the input file.

            
      
        

        - **JobStatus** *(string) --* 

          The current status of the speaker enrollment job.

          
        

        - **OutputDataConfig** *(dict) --* 

          The output data config containing the S3 location where Voice ID writes the job output file; you must also include a KMS key ID to encrypt the file.

          
          

          - **KmsKeyId** *(string) --* 

            The identifier of the KMS key you want Voice ID to use to encrypt the output file of a speaker enrollment job/fraudster registration job.

            
          

          - **S3Uri** *(string) --* 

            The S3 path of the folder where Voice ID writes the job output file. It has a ``*.out`` extension. For example, if the input file name is ``input-file.json`` and the output folder path is ``s3://output-bucket/output-folder``, the full output file path is ``s3://output-bucket/output-folder/job-Id/input-file.json.out``.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`VoiceID.Client.exceptions.ServiceQuotaExceededException`

  
  *   :py:class:`VoiceID.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`VoiceID.Client.exceptions.ValidationException`

  
  *   :py:class:`VoiceID.Client.exceptions.ConflictException`

  
  *   :py:class:`VoiceID.Client.exceptions.InternalServerException`

  
  *   :py:class:`VoiceID.Client.exceptions.ThrottlingException`

  
  *   :py:class:`VoiceID.Client.exceptions.AccessDeniedException`

  