GET /v1/dimensions/{dimension}/{id} · markdown

Describe an ID

describe_dimension_value

Describe an ID

Call: GET /v1/dimensions/{dimension}/{id}
Price: Uses credits (see each response's X-Credits-Charged)
Available: soft launch
Contract: https://api.gwix.ai/docs/reference

What it's for

Explain what an ID means - its name, parent and attributes (for companies, the ultimate parent, ticker and industry).

Use it when

Before reporting a result, to name and define the thing measured.
Checking whether an ID is retired (status: retired gives successor_id).

Inputs

Name	In	Type	Required	Meaning
`dimension`	path	string: role	sub_job_family	job_family
`id`	path	string	yes	Value ID in that dimension (e.g. `rol_8f3k2`, `cmp_4qz71`, `5413`, `mtr_35620`).
`classifications`	query	list of string: gwix_role	onet_soc	soc_2018

Headers: GWIX-Agent-Id, GWIX-On-Behalf-Of.

What comes back

id, name, status, parent, level, country, ticker, classifications, dimension, successor_id, definition, aliases, job_family, sub_job_family, roles_count, typical_job_levels, company, location, industry, meta.

Rules

Identify your agent. Send GWIX-Agent-Id on every call (register once with register_agent). Unidentified keys get reduced limits and are refused after 10 minutes.

Notes

Roles show their sub-job family and job family; companies show the ultimate parent, ticker and primary 4-digit NAICS; locations show their parent and level.
classifications=soc_2018 adds a role's SOC 2018 occupation.

When it doesn't work

Status	What to do
401	Send a valid API key (`Authorization: Bearer ...`).
402	Not enough credits. The body lists packs and plans that would cover it.
403	Not allowed for this key or tier, a cap is reached, or the agent is unidentified; read `type` and `detail`.
404	No such ID. Use `lookup` or `list_dimension_values` to find valid IDs.
429	Rate or concurrency limit. Wait `Retry-After` seconds.

Next steps

crosswalk · get_pay

Example response

{
  "dimension": "role",
  "id": "rol_29-1141.00",
  "name": "Registered Nurse",
  "status": "active",
  "definition": "Assesses patient health problems and needs, develops and implements nursing care plans, and maintains medical records.",
  "job_family": {
    "id": "jfm_nursing",
    "name": "Nursing"
  },
  "typical_job_levels": [
    {
      "id": "lvl_p2",
      "name": "P2"
    },
    {
      "id": "lvl_p3",
      "name": "P3"
    },
    {
      "id": "lvl_p4",
      "name": "Senior Professional"
    }
  ],
  "aliases": [
    "RN",
    "Staff Nurse",
    "Registered Nurse II"
  ],
  "classifications": [
    {
      "system": "soc_2018",
      "code": "29-1141",
      "name": "Registered Nurses",
      "match_type": "exact"
    },
    {
      "system": "isco_08",
      "code": "2221",
      "name": "Nursing professionals",
      "match_type": "broader"
    }
  ],
  "meta": {
    "request_id": "gwx_req_31ab",
    "taxonomy_version": "utb-1.0"
  }
}