Person Group Person - List

Service:

Cognitive Services - Face

API Version:

1.0

List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).

GET {Endpoint}/face/v1.0/persongroups/{personGroupId}/persons

With optional parameters:

GET {Endpoint}/face/v1.0/persongroups/{personGroupId}/persons?start={start}&top={top}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).
personGroupId	path	True	string	Id referencing a particular person group. Regex pattern: ^[a-z0-9-_]+$
start	query		string	Starting person id to return (used to list a range of persons).
top	query		integer	Number of persons to return starting with the person id indicated by the 'start' parameter.

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Responses

Name	Type	Description
200 OK	Person[]	A successful call returns an array of person information that belong to the person group.
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

List persons in person group

Sample Request

HTTP

GET {Endpoint}/face/v1.0/persongroups/abc/persons?start=25985303-c537-4467-b41d-bdb45cd95ca1&top=2

Sample Response

Status code:

200

[
  {
    "personId": "25985303-c537-4467-b41d-bdb45cd95ca1",
    "name": "Ryan",
    "userData": "User-provided data attached to the person",
    "persistedFaceIds": [
      "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
      "fce92aed-d578-4d2e-8114-068f8af4492e",
      "b64d5e15-8257-4af2-b20a-5a750f8940e7"
    ]
  },
  {
    "personId": "2ae4935b-9659-44c3-977f-61fac20d0538",
    "name": "David",
    "userData": "User-provided data attached to the person",
    "persistedFaceIds": [
      "30ea1073-cc9e-4652-b1e3-d08fb7b95315",
      "fbd2a038-dbff-452c-8e79-2ee81b1aa84e"
    ]
  }
]

Definitions

Name	Description
APIError	Error information returned by the API
Error	Error body.
Person	Person object.

APIError

Error information returned by the API

Name	Type	Description
error	Error	Error body.

Error

Error body.

Name	Type	Description
code	string
message	string

Person

Person object.

Name	Type	Description
name	string	User defined name, maximum length is 128.
persistedFaceIds	string[]	PersistedFaceIds of registered faces in the person. These persistedFaceIds are returned from Person - Add a Person Face, and will not expire.
personId	string	PersonId of the target face list.
userData	string	User specified data. Length should not exceed 16KB.