Skip to main content
GET
Get Person

Authorizations

Authorization
string
header
required

Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.

Path Parameters

workspace_id
string<uuid>
required
person_id
string<uuid>
required

Response

Successful Response

One person, as an external integrator sees them.

The field list is CLOSED and hand-maintained. It carries who the person is (identity + demographics + interests) and nothing about how ish came to hold that row: no moderation verdict, no publisher, no viewer-specific state, no internal config pointer, no custom fields.

created_at
string<date-time>
required
id
string<uuid>
required
name
string
required

The person's display name.

owner
enum<string>
required

self for a person your workspace owns; platform for one published in the shared ish library. Both are usable in a session; only self rows are yours to edit.

Available options:
self,
platform
updated_at
string<date-time>
required
accessibility_profile
Accessibility Profile · object | null

Declared accessibility needs, as a nested object of boolean and enum flags. Only non-default keys are present. An open union: new keys appear over time.

archived_at
string<date-time> | null

When this person was archived, or null while they are live. An archived person is hidden from the default listing and closed to edits, but stays readable by id and keeps every session that ran for them intact. POST .../restore clears it.

avatar_url
string | null

Publicly fetchable avatar image, when one exists.

bio
string | null

Free-text background in the person's own register. This is the bulk of what the model is told about them when a session runs.

city
string | null
country
string | null
date_of_birth
string<date> | null
education_level
enum<string> | null
Available options:
less_than_secondary,
secondary,
some_post_secondary,
vocational_or_associate,
bachelor,
graduate
employment_status
enum<string> | null
Available options:
employed_full_time,
employed_part_time,
self_employed,
unemployed_seeking,
student,
homemaker,
retired,
unable_to_work,
other
external_id
string | null

Your own identifier for this person, if you set one. Unique among the people your workspace owns. Always null on a platform person: the shared library is nobody's to label.

gender
enum<string> | null

Gender options for people.

Available options:
male,
female,
non-binary,
prefer_not_to_say
generation_job_id
string<uuid> | null

The generation job that produced this person, when one did. This is how you collect a job's results: list people filtered by it.

household
enum<string> | null
Available options:
single,
couple_no_kids,
couple_with_kids,
single_parent,
shared_housing,
adult_with_parents,
multi_generational
income_level
enum<string> | null
Available options:
lower,
lower_middle,
middle,
upper_middle,
upper,
prefer_not_to_say
interests
string[]

IAB taxonomy node ids this person is tagged with. Filterable via the qualification rule source, where a parent node also matches everyone tagged at a node beneath it.

locale_type
enum<string> | null
Available options:
urban,
suburban,
small_town,
rural
occupation
string | null

Free-text job title, as written on the person.

occupation_code
string | null

Canonical ESCO/ISCO code beside the free-text occupation. Codes are hierarchical, so a starts_with filter on a group prefix selects a whole occupational family.

type
string
default:ai

Always ai on this API. ish also models real people who have consented to participate, and they are never readable here or through any credential you can mint. Treat this as an open union and tolerate a value you do not recognize.

Allowed value: "ai"
workspace_id
string<uuid> | null

The owning workspace, present only when owner is self. A platform person belongs to no workspace, so this is null rather than naming one.