Face API

Microsoft Cognitive Services Face API allows you to detect, identify, analyze, organize and tag faces in photos.

This connector is available in the following products and regions:

Service	Class	Regions
Logic Apps	Standard	All Logic Apps regions
Power Automate	Standard	All Power Automate regions
Power Apps	Standard	All Power Apps regions

Contact
Name	Microsoft
URL	Microsoft LogicApps Support Microsoft Power Automate Support Microsoft Power Apps Support

Connector Metadata
Publisher	Microsoft
Website	https://azure.microsoft.com/services/cognitive-services/face/

To use this integration, you will need a Cognitive Service resource in the Azure portal. You will get an endpoint and a key for authenticating your applications. To make a connection, provide the Account key, site URL and select Create connection. For operation costs on your connection, learn more here.

You're now ready to start using this integration.

Connecting with Microsoft Entra ID

To create connections with Microsoft Entra ID, you must add the Cognitive Services User role to your account to access. To use this connection, you must input the unique subdomain associated wih your Cognitive Services resource into the supporting operations.

Operations not supported with Microsoft Entra ID authentication

When using Microsoft Entra ID authentication only V2 actions are supported. Deprecated actions will continue to work with Access Key authentication, but will fail if used with an Microsoft Entra ID connection.

Creating a connection

The connector supports the following authentication types:

Api Key	Api Key	All regions	Shareable
Default [DEPRECATED]	This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.	All regions	Not shareable

Api Key

Auth ID: keyBasedAuth

Applicable: All regions

Api Key

This is shareable connection. If the power app is shared with another user, connection is shared as well. For more information, please see the Connectors overview for canvas apps - Power Apps | Microsoft Docs

Name	Type	Description	Required
Account Key	securestring	Cognitive Services Account Key
Site URL	string	Root site url (Example: https://westus.api.cognitive.microsoft.com)

Default [DEPRECATED]

Applicable: All regions

This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name	Type	Description	Required
API Key	securestring	API Key	True
Site URL	string	Root site url (Example: https://westus.api.cognitive.microsoft.com ).If not specified site url will be defaulted to 'https://westus.api.cognitive.microsoft.com'.

Throttling Limits

Name	Calls	Renewal Period
API calls per connection	1200	60 seconds

Actions

Add a person face	Add a representative face to a person for identification.
Add a person face (V2)	Add a representative face to a person for identification.
Add face to face list	Add face to face list.
Add face to face list (V2)	Add face to face list.
Create a face list	Create an empty face list with user-specified faceListId, name and an optional userData.
Create a face list (V2)	Create an empty face list with user-specified faceListId, name and an optional userData.
Create a person	Create a new person in a specified person group.
Create a person (V2)	Create a new person in a specified person group.
Create a person group	Create a new person group with specified personGroupId, name and user-provided userData.
Create a person group (V2)	Create a new person group with specified personGroupId, name and user-provided userData.
Detect faces	Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
Detect faces (V2)	Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
Find person from face	Verify whether two faces belong to a same person or whether one face belongs to a person.
Find person from face (V2)	Verify whether two faces belong to a same person or whether one face belongs to a person.
Get a face list	Retrieve a face list's information, including faceListId, name, userData and faces in the face list.
Get a face list (V2)	Retrieve a face list's information, including faceListId, name, userData and faces in the face list.
Get a person	Retrieve a person's information, including registered persisted faces, name and userData.
Get a person (V2)	Retrieve a person's information, including registered persisted faces, name and userData.
Get a person face	Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.
Get a person face (V2)	Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.
Get a person group	Retrieve the information of a person group, including its name and userData.
Get a person group (V2)	Retrieve the information of a person group, including its name and userData.

Add a person face

Operation ID:

AddPersonFace

Add a representative face to a person for identification.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	Person group
Person Id	personId	True	string	Target person that the face is added to.
Image Url	url	True	string	Image must be JPEG, PNG, GIF(the first frame), or BMP
Target Face	targetFace		string	A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data	userData		string	User-specified data about the target face to add for any purpose. The maximum length is 1KB.

Returns

Body

AddPersonFaceResponse

Add a person face (V2)

Operation ID:

AddPersonFaceV2

Add a representative face to a person for identification.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	Person group
Person Id	personId	True	string	Target person that the face is added to.
Image Url	url	True	string	Image must be JPEG, PNG, GIF(the first frame), or BMP
Target Face	targetFace		string	A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data	userData		string	User-specified data about the target face to add for any purpose. The maximum length is 1KB.

Returns

Body

AddPersonFaceResponse

Add face to face list

Operation ID:

AddFaceToFaceList

Add face to face list.

Parameters

Name	Key	Required	Type	Description
Image Url	url		string	Image must be JPEG, PNG, GIF(the first frame), or BMP
Target Face	targetFace		string	A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data	userData		string	User-specified data about the target face to add for any purpose. The maximum length is 1KB.
Face List Id	faceListId	True	string	Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.

Returns

Body

AddPersonFaceResponse

Add face to face list (V2)

Operation ID:

AddFaceToFaceListV2

Add face to face list.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Image Url	url		string	Image must be JPEG, PNG, GIF(the first frame), or BMP
Target Face	targetFace		string	A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data	userData		string	User-specified data about the target face to add for any purpose. The maximum length is 1KB.
Face List Id	faceListId	True	string	Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.

Returns

Body

AddPersonFaceResponse

Create a face list

Operation ID:

CreateFaceList

Create an empty face list with user-specified faceListId, name and an optional userData.

Parameters

Name	Key	Required	Type	Description
Face List Id	faceListId	True	string	Valid character is letter in lower case or digit or '-' or '_', maximum length is 64
Face List Name	name	True	string	Name of the created face list, maximum length is 128.
User Data	userData		string	Optional user defined data for the face list. Length should not exceed 16KB.

Create a face list (V2)

Operation ID:

CreateFaceListV2

Create an empty face list with user-specified faceListId, name and an optional userData.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Face List Id	faceListId	True	string	Valid character is letter in lower case or digit or '-' or '_', maximum length is 64
Face List Name	name	True	string	Name of the created face list, maximum length is 128.
User Data	userData		string	Optional user defined data for the face list. Length should not exceed 16KB.

Create a person

Operation ID:

CreatePerson

Create a new person in a specified person group.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	Specifying the target person group to create the person.
Name	name	True	string	Display name of the target person. The maximum length is 128.
User Data	userData		string	Optional fields for user-provided data attached to a person. Size limit is 16KB.

Returns

Body

CreatePersonResponse

Create a person (V2)

Operation ID:

CreatePersonV2

Create a new person in a specified person group.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	Specifying the target person group to create the person.
Name	name	True	string	Display name of the target person. The maximum length is 128.
User Data	userData		string	Optional fields for user-provided data attached to a person. Size limit is 16KB.

Returns

Body

CreatePersonResponse

Create a person group

Operation ID:

CreatePersonGroup

Create a new person group with specified personGroupId, name and user-provided userData.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	New Person Group Id (valid characters include numbers, English letters in lower case, '-' and '_')
Name	name	True	string	Person group display name. The maximum length is 128.
User Data	userData		string	User-provided data attached to the person group. The size limit is 16KB.

Create a person group (V2)

Operation ID:

CreatePersonGroupV2

Create a new person group with specified personGroupId, name and user-provided userData.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	New Person Group Id (valid characters include numbers, English letters in lower case, '-' and '_')
Name	name	True	string	Person group display name. The maximum length is 128.
User Data	userData		string	User-provided data attached to the person group. The size limit is 16KB.

Detect faces

Operation ID:

Detect

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters

Name	Key	Required	Type	Description
Image Url	url	True	string	Image must be JPEG, PNG, GIF(the first frame), or BMP

Returns

Items

DetectResponse

Detect faces (V2)

Operation ID:

DetectV2

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Image Url	url	True	string	Image must be JPEG, PNG, GIF(the first frame), or BMP

Returns

Items

DetectResponse

Find person from face

Operation ID:

Verify

Verify whether two faces belong to a same person or whether one face belongs to a person.

Parameters

Name	Key	Required	Type	Description
Face Id	faceId	True	string	Unique faceId of the detected face. Will expire 24 hours after detection call.
Person Group Id	personGroupId	True	string	Person Group Id created in Face API - Create Person Group action.
Person Id	personId	True	string	Person Id created in Face API - Create Person action.

Returns

Body

VerifyResponse

Find person from face (V2)

Operation ID:

VerifyV2

Verify whether two faces belong to a same person or whether one face belongs to a person.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Face Id	faceId	True	string	Unique faceId of the detected face. Will expire 24 hours after detection call.
Person Group Id	personGroupId	True	string	Person Group Id created in Face API - Create Person Group action.
Person Id	personId	True	string	Person Id created in Face API - Create Person action.

Returns

Body

VerifyResponse

Get a face list

Operation ID:

GetFaceList

Retrieve a face list's information, including faceListId, name, userData and faces in the face list.

Parameters

Name	Key	Required	Type	Description
Face List Id	faceListId	True	string	faceListId of the target face list.

Returns

Body

GetFaceListResponse

Get a face list (V2)

Operation ID:

GetFaceListV2

Retrieve a face list's information, including faceListId, name, userData and faces in the face list.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Face List Id	faceListId	True	string	faceListId of the target face list.

Returns

Body

GetFaceListResponse

Get a person

Operation ID:

GetPerson

Retrieve a person's information, including registered persisted faces, name and userData.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	Specifying the person group containing the target person.
Person Id	personId	True	string	Specifying the target person.

Returns

Body

GetPersonResponse

Get a person (V2)

Operation ID:

GetPersonV2

Retrieve a person's information, including registered persisted faces, name and userData.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	Specifying the person group containing the target person.
Person Id	personId	True	string	Specifying the target person.

Returns

Body

GetPersonResponse

Get a person face

Operation ID:

GetPersonFace

Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	Specifying the person group containing the target person.
Person Id	personId	True	string	Specifying the target person that the face belongs to.
Persisted Face Id	persistedFaceId	True	string	The persistedFaceId of the target persisted face of the person.

Returns

Body

GetPersonFaceResponse

Get a person face (V2)

Operation ID:

GetPersonFaceV2

Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	Specifying the person group containing the target person.
Person Id	personId	True	string	Specifying the target person that the face belongs to.
Persisted Face Id	persistedFaceId	True	string	The persistedFaceId of the target persisted face of the person.

Returns

Body

GetPersonFaceResponse

Get a person group

Operation ID:

GetPersonGroup

Retrieve the information of a person group, including its name and userData.

Parameters

Name	Key	Required	Type	Description
Person Group Id	personGroupId	True	string	Target Person Group Id.

Returns

Body

GetPersonGroupResponse

Get a person group (V2)

Operation ID:

GetPersonGroupV2

Retrieve the information of a person group, including its name and userData.

Parameters

Name	Key	Required	Type	Description
Resource Subdomain or Region	subdomain	True	string	Azure subdomain or geographic region (e.g. westus)
Person Group Id	personGroupId	True	string	Target Person Group Id.

Returns

Body

GetPersonGroupResponse

Definitions

DetectResponse

Name	Path	Type	Description
Face Id	faceId	string	Unique faceId of the detected face. Will expire 24 hours after detection call.
Top	faceRectangle.top	integer	Parameters of a rectangle area for the face location on image.
Left	faceRectangle.left	integer	Parameters of a rectangle area for the face location on image.
Width	faceRectangle.width	integer	Parameters of a rectangle area for the face location on image.
Height	faceRectangle.height	integer	Parameters of a rectangle area for the face location on image.
Left Pupil X	faceLandmarks.pupilLeft.x	float	The x-coordinate of the left pupil.
Left Pupil Y	faceLandmarks.pupilLeft.y	float	The y-coordinate of the left pupil.
Right Pupil X	faceLandmarks.pupilRight.x	float	The x-coordinate of the right pupil.
Right Pupil Y	faceLandmarks.pupilRight.y	float	The y-coordinate of the right pupil.
Nose Tip X	faceLandmarks.noseTip.x	float	The x-coordinate of the nose tip.
Nose Tip Y	faceLandmarks.noseTip.y	float	The y-coordinate of the nose tip.
Mouth Left X	faceLandmarks.mouthLeft.x	float	The x-coordinate for the left side of the mouth.
Mouth Left Y	faceLandmarks.mouthLeft.y	float	The y-coordinate for the left side of the mouth.
Mouth Right X	faceLandmarks.mouthRight.x	float	The x-coordinate for the right side of the mouth.
Mouth Right Y	faceLandmarks.mouthRight.y	float	The y-coordinate for the right side of the mouth.
Outer Left Eyebrow X	faceLandmarks.eyebrowLeftOuter.x	float	The x-coordinate for the outer side of the left eyebrow.
Outer Left Eyebrow Y	faceLandmarks.eyebrowLeftOuter.y	float	The y-coordinate for the outer side of the left eyebrow.
Inner Left Eybrow X	faceLandmarks.eyebrowLeftInner.x	float	The x-coordinate for the inner side of the left eyebrow.
Inner Left Eyebrow Y	faceLandmarks.eyebrowLeftInner.y	float	The y-coordinate for the inner side of the left eyebrow.
Outer Left Eye X	faceLandmarks.eyeLeftOuter.x	float	The x-coordinate for the outer side of the left eye.
Outer Left Eye Y	faceLandmarks.eyeLeftOuter.y	float	The y-coordinate for the outer side of the left eye.
Top of Left Eye X	faceLandmarks.eyeLeftTop.x	float	The x-coordinate for the top of the left eye.
Top of Left Eye Y	faceLandmarks.eyeLeftTop.y	float	The y-coordinate for the top of the left eye.
Bottom of Left Eye X	faceLandmarks.eyeLeftBottom.x	float	The x-coordinate for the bottom of the left eye.
Bottom of Left Eye Y	faceLandmarks.eyeLeftBottom.y	float	The y-coordinate for the bottom of the left eye.
Inner Left Eye X	faceLandmarks.eyeLeftInner.x	float	The x-coordinate for the inner side of the left eye.
Inner Left Eye Y	faceLandmarks.eyeLeftInner.y	float	The y-coordinate for the inner side of the left eye.
Inner Right Eybrow X	faceLandmarks.eyebrowRightInner.x	float	The x-coordinate for the inner side of the right eyebrow.
Inner Right Eyebrow Y	faceLandmarks.eyebrowRightInner.y	float	The y-coordinate for the inner side of the right eyebrow.
Outer Right Eyebrow X	faceLandmarks.eyebrowRightOuter.x	float	The x-coordinate for the outer side of the right eyebrow.
Outer Right Eyebrow Y	faceLandmarks.eyebrowRightOuter.y	float	The y-coordinate for the outer side of the right eyebrow.
Inner Right Eye X	faceLandmarks.eyeRightInner.x	float	The x-coordinate for the inner side of the right eye.
Inner Right Eye Y	faceLandmarks.eyeRightInner.y	float	The y-coordinate for the inner side of the right eye.
Top of Right Eye X	faceLandmarks.eyeRightTop.x	float	The x-coordinate for the top of the right eye.
Top of Right Eye Y	faceLandmarks.eyeRightTop.y	float	The y-coordinate for the top of the right eye.
Bottom of Right Eye X	faceLandmarks.eyeRightBottom.x	float	The x-coordinate for the bottom of the right eye.
Bottom of Right Eye Y	faceLandmarks.eyeRightBottom.y	float	The y-coordinate for the bottom of the right eye.
Outer Right Eye X	faceLandmarks.eyeRightOuter.x	float	The x-coordinate for the outer side of the right eye.
Outer Right Eye Y	faceLandmarks.eyeRightOuter.y	float	The y-coordinate for the outer side of the right eye.
Left Nose Root X	faceLandmarks.noseRootLeft.x	float	The x-coordinate for left side of the nose root.
Left Nose Root Y	faceLandmarks.noseRootLeft.y	float	The y-coordinate for left side of the nose root.
Right Nose Root X	faceLandmarks.noseRootRight.x	float	The x-coordinate for right side of the nose root.
Right Nose Root Y	faceLandmarks.noseRootRight.y	float	The y-coordinate for right side of the nose root.
Top of Left Nose Altar X	faceLandmarks.noseLeftAlarTop.x	float	The x-coordinate for top of the left nose altar.
Top of Left Nose Altar Y	faceLandmarks.noseLeftAlarTop.y	float	The y-coordinate for top of the left nose altar.
Top of Right Nose Altar X	faceLandmarks.noseRightAlarTop.x	float	The x-coordinate for top of the right nose altar.
Top of Right Nose Altar Y	faceLandmarks.noseRightAlarTop.y	float	The y-coordinate for top of the right nose altar.
Tip of Left Nose Altar Out X	faceLandmarks.noseLeftAlarOutTip.x	float	The x-coordinate for tip of the left nose altar.
Tip of Left Nose Altar Out Y	faceLandmarks.noseLeftAlarOutTip.y	float	The y-coordinate for tip of the left nose altar/
Tip of Right Nose Altar Out X	faceLandmarks.noseRightAlarOutTip.x	float	The x-coordinate for tip of the right nose altar.
Tip of Right Nose Altar Out Y	faceLandmarks.noseRightAlarOutTip.y	float	The y-coordinate for tip of the right nose altar.
Top of Upper Lip X	faceLandmarks.upperLipTop.x	float	The x-coordinate for top of upper lip.
Top of Upper Lip Y	faceLandmarks.upperLipTop.y	float	The y-coordinate for top of upper lip.
Bottom of Upper Lip X	faceLandmarks.upperLipBottom.x	float	The x-coordinate for bottom of upper lip.
Bottom of Upper Lip Y	faceLandmarks.upperLipBottom.y	float	The y-coordinate for bottom of upper lip.
Top of Under Lip X	faceLandmarks.underLipTop.x	float	The x-coordinate for top of under lip.
Top of Under Lip Y	faceLandmarks.underLipTop.y	float	The y-coordinate for top of under lip.
Bottom of Under Lip X	faceLandmarks.underLipBottom.x	float	The x-coordinate for bottom of under lip.
Bottom of Under Lip Y	faceLandmarks.underLipBottom.y	float	The y-coordinate for bottom of under lip.
Head Pose Pitch	faceAttributes.headPose.pitch	float	Reserved field, always returns 0.
Head Pose Roll	faceAttributes.headPose.roll	float	Roll of the head pose.
Head Pose Yaw	faceAttributes.headPose.yaw	float	Yaw of the head pose.
Glasses	faceAttributes.glasses	string	Type of glasses.

AddPersonFaceResponse

Name	Path	Type	Description
Persisted Face Id	persistedFaceId	string

GetPersonGroupResponse

Name	Path	Type	Description
Person Group Id	personGroupId	string
Name	name	string
userData	userData	string

GetFaceListResponse

Name	Path	Type	Description
Persisted Faces	persistedFaces	array of object
Persisted Face Id	persistedFaces.persistedFaceId	string	Id of the face.
User Data	persistedFaces.userData	string	User-provided data attached to each face.
Face List Id	faceListId	string	faceListId of the target face list.
Name	name	string	Face list's display name.
User Data	userData	string	User-provided data attached to the face list.

GetPersonFaceResponse

Name	Path	Type	Description
Persisted Face Id	persistedFaceId	string
userData	userData	string

CreatePersonResponse

Name	Path	Type	Description
Person Id	personId	string

GetPersonResponse

Name	Path	Type	Description
Person Id	personId	string
Persisted Face Ids	persistedFaceIds	array of object
Persisted Face Id	persistedFaceIds.persistedFaceId	string
Name	name	string
User Data	userData	string

VerifyResponse

Name	Path	Type	Description
Is Identical	isIdentical	boolean	True if the two faces belong to the same person or the face belongs to the person, otherwise false.
Confidence	confidence	float	A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person.