Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

AssociateFaces

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.

Request Syntax


{
   "ClientRequestToken": "string",
   "CollectionId": "string",
   "FaceIds": [ "string" ],
   "UserId": "string",
   "UserMatchThreshold": number
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

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.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: ^[a-zA-Z0-9-_]+$

Required: No

CollectionId

The ID of an existing collection containing the UserID.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [a-zA-Z0-9_.\-]+

Required: Yes

FaceIds

An array of FaceIDs to associate with the UserID.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Pattern: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}

Required: Yes

UserId

The ID for the existing UserID.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9_.\-:]+

Required: Yes

UserMatchThreshold

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

Type: Float

Valid Range: Minimum value of 0. Maximum value of 100.

Required: No

Response Syntax


{
   "AssociatedFaces": [ 
      { 
         "FaceId": "string"
      }
   ],
   "UnsuccessfulFaceAssociations": [ 
      { 
         "Confidence": number,
         "FaceId": "string",
         "Reasons": [ "string" ],
         "UserId": "string"
      }
   ],
   "UserStatus": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

AssociatedFaces

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

Type: Array of AssociatedFace objects

Array Members: Minimum number of 0 items. Maximum number of 100 items.

UnsuccessfulFaceAssociations

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

Type: Array of UnsuccessfulFaceAssociation objects

Array Members: Minimum number of 0 items. Maximum number of 500 items.

UserStatus

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

Type: String

Valid Values: ACTIVE | UPDATING | CREATING | CREATED

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You are not authorized to perform the action.

HTTP Status Code: 400

ConflictException

A User with the same Id already exists within the collection, or the update or deletion of the User caused an inconsistent state. **

HTTP Status Code: 400

IdempotentParameterMismatchException

A ClientRequestToken input parameter was reused with an operation, but at least one of the other input parameters is different from the previous call to the operation.

HTTP Status Code: 400

InternalServerError

Amazon Rekognition experienced a service issue. Try your call again.

HTTP Status Code: 500

InvalidParameterException

Input parameter violated a constraint. Validate your parameter before calling the API operation again.

HTTP Status Code: 400

ProvisionedThroughputExceededException

The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.

HTTP Status Code: 400

ResourceNotFoundException

The resource specified in the request cannot be found.

HTTP Status Code: 400

ServiceQuotaExceededException

The size of the resource exceeds the allowed limit. For more information, see Guidelines and quotas in Amazon Rekognition.

HTTP Status Code: 400

ThrottlingException

Amazon Rekognition is temporarily unable to process the request. Try your call again.

HTTP Status Code: 500