---
title: "List occupations"
method: GET
path: "/v1/people/occupations"
tags: ["People", "tier:standard"]
---

# List occupations

`GET /v1/people/occupations`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/people/occupations`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Lists one level of an official occupation standard: SOC 2018 major groups, or the detailed occupations under one; or, for ISCO-08, the groups SOC 2018 maps to, listed flat: 436 unit groups and the two minor groups (211, 315) the crosswalk maps an occupation to whole. Every code, slug, and title listed here is accepted wherever speaker expertise is filtered by occupation.

## Query parameters

- `limit` integer: Results per page (default: all)
- `cursor` string: Opaque pagination cursor from previous response
- `standard` 'soc_2018' | 'isco_08': Occupation standard to browse: soc_2018 (US Standard Occupational Classification; major groups, then minor groups, broad groups and detailed occupations) or isco_08 (ILO International Standard Classification of Occupations; the groups SOC 2018 maps to, listed flat: unit groups, plus the minor groups 211 and 315).
- `parent` string: List the occupations one level below this one. Accepts its code (11-0000), slug (management-occupations), or title (Management Occupations). Omit to list the top level.
- `q` string: Search the standard's occupations by title instead of listing a level: words match in either number and by prefix, so cardiologist finds Cardiologists. With parent, only occupations below that one are searched. Best matches first.

## Response `200`

OK

- PageExpertiseCode
  - `cursor` string: Pass to next request for more results
  - `data` ExpertiseCode[], nullable, required: List of results
    - `code` string, required: The standard's own notation, such as 29-1212 (SOC), 2212 (ISCO), or 320101 (FoR).
    - `group` 'minor' | 'broad' | 'alias': Set for a code that stands for several detailed SOC 2018 occupations: a SOC minor group (such as 29-1000 Healthcare Diagnosing or Treating Practitioners), a broad group (such as 29-1210 Physicians), or an alias, an everyday name such as doctors (physicians and surgeons). Every occupation filter accepts one and matches a speaker listed under any of its occupations.
    - `level` integer: Depth in the standard's official hierarchy: SOC major group 1 and detailed occupation 2; FoR division 1, group 2, field 3; ISCO-08 unit group 4 and minor group 3. ISCO-08 codes are the groups SOC maps to, listed flat without the standard's upper levels. Omitted for a SOC group or alias (see group).
    - `parent_code` string: The standard's official parent code; omitted at the top level and for every ISCO-08 code, since ISCO-08 is listed without its upper levels. A SOC broad group's parent is its minor group and a minor group's its major group, but a detailed SOC occupation's official parent is its major group (29-1211 has parent_code 29-0000), so it can differ from parent, which is the browse parent one level up (29-1210).
    - `slug` string, required: The title as a URL segment, such as cardiologists.
    - `standard` 'soc_2018' | 'isco_08' | 'anzsrc_for_2020', required: The standard the code belongs to: soc_2018 (US Standard Occupational Classification), isco_08 (the ILO's International Standard Classification of Occupations), or anzsrc_for_2020 (ANZSRC Fields of Research).
    - `title` string, required: The standard's official title, such as Cardiologists.
  - `has_more` boolean, required: Whether more results exist

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)