Documentation
Parameters
All `GET /people` parameters are optional. Unknown, repeated or incompatible values are rejected.
Available filters
| Parameter | Value | Purpose |
|---|---|---|
| count | 1–100 · default 1 | Number of profiles |
| gender | male, female | Gender |
| ageGroup | child, teen, adult, senior | One or more comma-separated groups |
| nationality | Two-letter ISO code | Nationality with a reviewed name pool |
| residenceCountry | Two-letter ISO code | Country with an available city |
| continent | africa, americas, asia, europe, oceania | Limits nationalities |
| city | City in residence country | Requires a country |
| emailDomain | ASCII domain · default example.test | Generated email domain |
| portraitContexts | Comma-separated; empty means no portrait | Types: standard, doctor, construction, business, school-pupil |
| skinTone | Distinct integers from 1 to 10, comma-separated | Filter portraits with any selected reviewed tone |
| seed | 1–128 characters | Generation seed |
| asOf | YYYY-MM-DD | UTC reference date |
| fields | Comma-separated paths | Select returned fields |
Age groups
The groups are child (6–12), teen (13–17), adult (18–64) and senior (65–100). Distinct values can be combined: ageGroup=adult,senior.
Portrait types and tone
On a compatible API, omitting portraitContexts selects all five released types; portraitContexts= excludes portraits. These filters apply to images, not profile generation.
standard: ages 6–100;doctor: 25–64;constructionandbusiness: 18–64;school-pupil: 6–17.- Selected types combine their eligible ages. The profile still returns when no compatible portrait is available;
pictureis thennull. skinToneaccepts distinct comma-separated integers from 1 to 10 and matches existing reviewed visual annotations. It does not describe ancestry; unannotated images do not match.
The Playground starts with all five boxes checked. Unchecking a type removes it from the request; clearing every box leaves the selection empty and does not restore Standard. Choices are preserved in the URL. For an older API, set NEXT_PUBLIC_PERSONA_PORTRAIT_CONTEXTS_ENABLED=false to hide these boxes and omit the parameter.
Select fields
fields selects properties of each person. results and meta remain. Without it, all public fields except login are included.
GET /people?fields=name.first,location.city,location.coordinates.latitude,picture.thumbnailA parent/child combination such as name,name.first returns 400. The encoded query string is limited to 2,048 characters.