:doc:`Rekognition <../../rekognition>` / Client / search_users

************
search_users
************



.. py:method:: Rekognition.Client.search_users(**kwargs)

  

  Searches for UserIDs within a collection based on a ``FaceId`` or ``UserId``. This API can be used to find the closest UserID (with a highest similarity) to associate a face. The request must be provided with either ``FaceId`` or ``UserId``. The operation returns an array of UserID that match the ``FaceId`` or ``UserId``, ordered by similarity score with the highest similarity first.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/rekognition-2016-06-27/SearchUsers>`_  


  **Request Syntax**
  ::

    response = client.search_users(
        CollectionId='string',
        UserId='string',
        FaceId='string',
        UserMatchThreshold=...,
        MaxUsers=123
    )
    
  :type CollectionId: string
  :param CollectionId: **[REQUIRED]** 

    The ID of an existing collection containing the UserID, used with a UserId or FaceId. If a FaceId is provided, UserId isn’t required to be present in the Collection.

    

  
  :type UserId: string
  :param UserId: 

    ID for the existing User.

    

  
  :type FaceId: string
  :param FaceId: 

    ID for the existing face.

    

  
  :type UserMatchThreshold: float
  :param UserMatchThreshold: 

    Optional value that specifies the minimum confidence in the matched UserID to return. Default value of 80.

    

  
  :type MaxUsers: integer
  :param MaxUsers: 

    Maximum number of identities to return.

    

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

    
    ::

      {
          'UserMatches': [
              {
                  'Similarity': ...,
                  'User': {
                      'UserId': 'string',
                      'UserStatus': 'ACTIVE'|'UPDATING'|'CREATING'|'CREATED'
                  }
              },
          ],
          'FaceModelVersion': 'string',
          'SearchedFace': {
              'FaceId': 'string'
          },
          'SearchedUser': {
              'UserId': 'string'
          }
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **UserMatches** *(list) --* 

        An array of UserMatch objects that matched the input face along with the confidence in the match. Array will be empty if there are no matches.

        
        

        - *(dict) --* 

          Provides UserID metadata along with the confidence in the match of this UserID with the input face.

          
          

          - **Similarity** *(float) --* 

            Describes the UserID metadata.

            
          

          - **User** *(dict) --* 

            Confidence in the match of this UserID with the input face.

            
            

            - **UserId** *(string) --* 

              A provided ID for the UserID. Unique within the collection.

              
            

            - **UserStatus** *(string) --* 

              The status of the user matched to a provided FaceID.

              
        
      
    
      

      - **FaceModelVersion** *(string) --* 

        Version number of the face detection model associated with the input CollectionId.

        
      

      - **SearchedFace** *(dict) --* 

        Contains the ID of a face that was used to search for matches in a collection.

        
        

        - **FaceId** *(string) --* 

          Unique identifier assigned to the face.

          
    
      

      - **SearchedUser** *(dict) --* 

        Contains the ID of the UserID that was used to search for matches in a collection.

        
        

        - **UserId** *(string) --* 

          A provided ID for the UserID. Unique within the collection.

          
    
  
  **Exceptions**
  
  *   :py:class:`Rekognition.Client.exceptions.InvalidParameterException`

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

  
  *   :py:class:`Rekognition.Client.exceptions.ProvisionedThroughputExceededException`

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

  
  *   :py:class:`Rekognition.Client.exceptions.InternalServerError`

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

  