Large Person Group Person - List

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

GET {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/persons
GET {Endpoint}/face/v1.0/largepersongroups/{largePersonGroupId}/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).

largePersonGroupId
path True
  • string

Id referencing a particular large 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

A successful call returns an array of person information that belong to the large person group.

Other Status Codes

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

List persons in person group

Sample Request

GET {Endpoint}/face/v1.0/largepersongroups/abc/persons?start=25985303-c537-4467-b41d-bdb45cd95ca1&top=2
Ocp-Apim-Subscription-Key: {API key}

Sample Response

[
  {
    "personId": "25985303-c537-4467-b41d-bdb45cd95ca1",
    "name": "person-name1",
    "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": "person-name2",
    "userData": "User-provided data attached to the person.",
    "persistedFaceIds": [
      "30ea1073-cc9e-4652-b1e3-d08fb7b95315",
      "fbd2a038-dbff-452c-8e79-2ee81b1aa84e"
    ]
  }
]

Definitions

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 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.