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

***************
associate_faces
***************



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

  

  Associates one or more faces with an existing UserID. Takes an array of ``FaceIds``. Each ``FaceId`` that are present in the ``FaceIds`` list is associated with the provided UserID. The number of FaceIds that can be used as input in a single request is limited to 100.

   

  Note that the total number of faces that can be associated with a single ``UserID`` is also limited to 100. Once a ``UserID`` has 100 faces associated with it, no additional faces can be added. If more API calls are made after the limit is reached, a ``ServiceQuotaExceededException`` will result.

   

  The ``UserMatchThreshold`` parameter specifies the minimum user match confidence required for the face to be associated with a UserID that has at least one ``FaceID`` already associated. This ensures that the ``FaceIds`` are associated with the right UserID. The value ranges from 0-100 and default value is 75.

   

  If successful, an array of ``AssociatedFace`` objects containing the associated ``FaceIds`` is returned. If a given face is already associated with the given ``UserID``, it will be ignored and will not be returned in the response. If a given face is already associated to a different ``UserID``, isn't found in the collection, doesn’t meet the ``UserMatchThreshold``, or there are already 100 faces associated with the ``UserID``, it will be returned as part of an array of ``UnsuccessfulFaceAssociations.``

   

  The ``UserStatus`` reflects the status of an operation which updates a UserID representation with a list of given faces. The ``UserStatus`` can be:

   

  
  * ACTIVE - All associations or disassociations of FaceID(s) for a UserID are complete.
   
  * CREATED - A UserID has been created, but has no FaceID(s) associated with it.
   
  * UPDATING - A UserID is being updated and there are current associations or disassociations of FaceID(s) taking place.
  

  

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


  **Request Syntax**
  ::

    response = client.associate_faces(
        CollectionId='string',
        UserId='string',
        FaceIds=[
            'string',
        ],
        UserMatchThreshold=...,
        ClientRequestToken='string'
    )
    
  :type CollectionId: string
  :param CollectionId: **[REQUIRED]** 

    The ID of an existing collection containing the UserID.

    

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

    The ID for the existing UserID.

    

  
  :type FaceIds: list
  :param FaceIds: **[REQUIRED]** 

    An array of FaceIDs to associate with the UserID.

    

  
    - *(string) --* 

    

  :type UserMatchThreshold: float
  :param UserMatchThreshold: 

    An optional value specifying the minimum confidence in the UserID match to return. The default value is 75.

    

  
  :type ClientRequestToken: string
  :param ClientRequestToken: 

    Idempotent token used to identify the request to ``AssociateFaces``. If you use the same token with multiple ``AssociateFaces`` requests, the same response is returned. Use ClientRequestToken to prevent the same request from being processed more than once.

    This field is autopopulated if not provided.

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

    
    ::

      {
          'AssociatedFaces': [
              {
                  'FaceId': 'string'
              },
          ],
          'UnsuccessfulFaceAssociations': [
              {
                  'FaceId': 'string',
                  'UserId': 'string',
                  'Confidence': ...,
                  'Reasons': [
                      'FACE_NOT_FOUND'|'ASSOCIATED_TO_A_DIFFERENT_USER'|'LOW_MATCH_CONFIDENCE',
                  ]
              },
          ],
          'UserStatus': 'ACTIVE'|'UPDATING'|'CREATING'|'CREATED'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **AssociatedFaces** *(list) --* 

        An array of AssociatedFace objects containing FaceIDs that have been successfully associated with the UserID. Returned if the AssociateFaces action is successful.

        
        

        - *(dict) --* 

          Provides face metadata for the faces that are associated to a specific UserID.

          
          

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

            Unique identifier assigned to the face.

            
      
    
      

      - **UnsuccessfulFaceAssociations** *(list) --* 

        An array of UnsuccessfulAssociation objects containing FaceIDs that are not successfully associated along with the reasons. Returned if the AssociateFaces action is successful.

        
        

        - *(dict) --* 

          Contains metadata like FaceId, UserID, and Reasons, for a face that was unsuccessfully associated.

          
          

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

            A unique identifier assigned to the face.

            
          

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

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

            
          

          - **Confidence** *(float) --* 

            Match confidence with the UserID, provides information regarding if a face association was unsuccessful because it didn't meet UserMatchThreshold.

            
          

          - **Reasons** *(list) --* 

            The reason why the association was unsuccessful.

            
            

            - *(string) --* 
        
      
    
      

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

        The status of an update made to a UserID. Reflects if the UserID has been updated for every requested change.

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

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

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

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

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

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

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

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

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

  