Mockfolk API

Overview

What is Mockfolk? Mockfolk is a hosted API and command-line tool that generates realistic fictitious people for testing AI agents and for developer test data. Give it constraints such as a country, a city, an age range, an occupation or a latitude and longitude, and it fills in the rest consistently: name (in local script where relevant), address, contact details, job, income band, personality and a short backstory. The same request with the same seed, or the same persona id, always returns the same person.

The API is a JSON API over HTTPS. Every response uses one envelope with data, error andmeta. People are generated by the deterministic engine: the same request with the same seed returns the same people, and every person has an id that regenerates them.

Countries in the first build: India (IN), the United States (US) and the United Kingdom (GB).

Authentication

Send your secret key as a bearer token. Keep it on your server; never ship it to a browser or mobile app. Keys are issued to early-access teams during the private beta.

Generate people

POST /v1/personas

Returns up to 1,000 people that satisfy every constraint you send. Anything you leave out is filled in consistently.

POST /v1/personasAuthorization: Bearer $MOCKFOLK_API_KEYContent-Type: application/json {  "country": "GB",  "age_min": 25,  "age_max": 34,  "count": 1,  "seed": "7"}

Body parameters

Response

The example below is real output from Mockfolk engine v1 (preview) for the request above. All people are fictional.

{  "data": [    {      "id": "g3mkk6o3pgz467mz7ze3baml.0",      "identity": {        "given_name": "Aminah",        "family_name": "Hussain",        "given_name_native": "",        "family_name_native": "",        "script": "Latin",        "gender": "female",        "date_of_birth": "1991-01-23",        "age": 34,        "nationality": "British"      },      "location": {        "country": "GB",        "region": "London",        "city": "London",        "locality": "Putney",        "postal_code": "SW15 9YN",        "street": "137 Church Avenue",        "time_zone": "Europe/London",        "lat": 51.5085,        "lon": -0.1257      },      "contact": {        "email": "aminahhussain734@example.com",        "phone": "07700 900883",        "username": "aminahhussain734"      },      "life": {        "education": "No formal qualifications",        "occupation": "Retail Assistant",        "occupation_id": "retail_assistant",        "employer": "Oakham Trading",        "industry": "retail",        "seniority": "entry",        "income_band": "£15k–20k",        "currency": "GBP",        "marital_status": "married",        "household_size": 4,        "languages": [          "en"        ],        "hobbies": [          "yoga",          "lawn bowls"        ],        "religion": null      },      "personality": {        "openness": 55,        "conscientiousness": 67,        "extraversion": 72,        "agreeableness": 31,        "neuroticism": 52,        "style": "energetic, driven and endlessly curious"      },      "social": [],      "media": null,      "backstory": {        "short": "Settled near Regent's Park years ago. Someone who works as a retail assistant, and who still gets excited about yoga.",        "long": null      },      "meta": {        "seed": "7",        "spec_id": "g3mkk6o3pgz467mz7ze3baml",        "index": 0,        "engine_version": "v1",        "pack_version": "2026-11",        "mode": "bulk",        "pack_tier": "tuned",        "saved": false      }    }  ],  "error": null,  "meta": {    "count": 1,    "spec_id": "g3mkk6o3pgz467mz7ze3baml"  }}

Location by coordinates

Send lat and lon instead of a country or city. The engine resolves them to the nearest place in the data pack, which sets the country, region and city, so names and everything else fit that place. These coordinates are Pune.

POST /v1/personasContent-Type: application/json {  "lat": 18.5204,  "lon": 73.8567,  "count": 5}

Get a person by id

GET /v1/personas/{id}

A persona id is the spec id and the person’s index, joined by a dot. Fetching it regenerates exactly the same person, with the same engine and data-pack versions.

GET /v1/personas/g3mkk6o3pgz467mz7ze3baml.0Authorization: Bearer $MOCKFOLK_API_KEY

Friends and coworkers

GET /v1/personas/{id}/related?kind=friends&count=5

Returns people connected to a persona. kind is friends or coworkers. The group is deterministic, so the same call always returns the same people, and links go both ways: a friend’s own friend list starts with the persona you asked about.

• Friends live in the same city most of the time, otherwise the same region, are within six years of age and share at least one hobby.
• Coworkers share the city and the exact employer, are of working age and work in the same industry.

Each related person records meta.related_to and meta.relation.

GET /v1/personas/g3mkk6o3pgz467mz7ze3baml.0/related?kind=friends&count=5Authorization: Bearer $MOCKFOLK_API_KEY

Determinism

• Every request is normalised into a spec with a concrete seed. If you do not send one, the random seed is returned in meta.
• The spec hashes to a stable 24-character spec_id. Person n of that spec has id <spec_id>.<n>.
• Each person records engine_version and pack_version. A released engine version never changes its output; improvements ship as new versions.
• fields only projects the response. It does not change the spec id or the people.

Errors

Impossible or unknown constraints return an explicit error instead of a silent guess.

{  "data": null,  "error": {    "code": "constraint_conflict",    "message": "occupation retired requires ages 60-90, outside 25-34",    "fields": ["age_min", "age_max", "occupation"]  },  "meta": null}

Safe by default

• Every person is fictional. No real people’s data is used.
• Emails use example.com, example.net or example.org. Phones use ranges set aside for fiction or unused by real phones.
• Mockfolk never generates identity documents of any kind.

CLI

The mockfolk CLI is a thin client over the API and prints JSON by default.

# Three people in India aged 25 to 34mockfolk new --country IN --age 25-34 --count 3 # The same three people again, by seedmockfolk new --country IN --age 25-34 --count 3 --seed 4 # One person by idmockfolk get g3mkk6o3pgz467mz7ze3baml.0

Questions about the preview? Get early access and we’ll be in touch.