# lookup

> Resolve plain language to a standardized ID

**Call:** `GET /v1/lookup/{type}`  
**Price:** Uses credits (see each response's `X-Credits-Charged`); free: needs disambiguation, no match  
**Available:** soft launch  
**Contract:** https://api.gwix.ai/docs/reference

## What it's for

Turn a plain-language title, company, ticker, industry, place, job family or sub-job family into a standardized GWIX ID.

## Use it when

- Before any statistics or records call, to resolve inputs to IDs.
- To confirm what a user meant ("Springfield" - which state?).

## Inputs

| Name | In | Type | Required | Meaning |
|---|---|---|---|---|
| `type` | path | string: title | company | industry | location | job_family | sub_job_family | yes |  |
| `q` | query | string |  | Plain-language input (title, company name, industry, place or job family). |
| `company_id` | query | string |  | One or more brand-level company IDs (from the company lookup). Use only one of `company_id`, `parent_company_id` or `ticker`. |
| `company` | query | string |  | Plain-language company name as context for a title lookup. |
| `location_id` | query | string |  | One or more location IDs - country (`US`), state (`US-CO`) or metro (`mtr_…`). A city or postcode resolves to its metro through the location lookup. |
| `location` | query | string |  | Plain-language place as context for a title or company lookup. |
| `industry_id` | query | string |  |  |
| `country` | query | string |  | ISO 3166-1 alpha-2 country code. |
| `description` | query | string |  | Job description text as context for a title lookup. Breaks close votes; no model call. |
| `website` | query | string |  | Company website as context for a company lookup. |
| `ticker` | query | string |  | Stock ticker (`MAR`). Resolves to the listed company and is treated as `parent_company_id` (the whole corporate group, current ownership). Add `country` when the ticker is used in more than one country. |
| `city` | query | string |  |  |
| `state` | query | string |  | State, province or region name or code. |
| `postcode` | query | string |  |  |
| `limit` | query | integer |  | Rows per page, 1 to 1,000 (default 100). Requests needing more than 1,000 rows in total answer 501; narrow them. |

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

## What comes back

`status`, `results`, `suggestions`, `meta`.
If an input is ambiguous: `status: needs_disambiguation` with `candidates`, the `missing` input and a `retry_with` template (no charge).

## 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

- Types at launch are `company` (name or `ticker`), `location` (name, `city`, `state`, `postcode` or `country`), `job_family`, `sub_job_family` and `industry` (from `company_id`). Title lookup comes later; to start from an occupation code, use `crosswalk` or `occupation_code`.
- Statuses are `matched` (results with confidence), `needs_disambiguation` (candidates and the missing input; free) and `no_match` (free).
- Location lookups return the most local level statistics support - metro, else state, else country - and say so with `fallback`; a city or postcode maps to the metro most of its ads are in.
- A ticker resolves to the listed company, usually the ultimate parent.

## When it doesn't work

| Status | What to do |
|---|---|
| 400 | Fix the request; `invalid_params` names each bad parameter. |
| 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`. |
| 422 | Parameters conflict (e.g. two company filters) or use a reserved feature. |
| 429 | Rate or concurrency limit. Wait `Retry-After` seconds. |

## Next steps

[`get_pay`](/context/get_pay) · [`get_postings`](/context/get_postings) · [`describe_dimension_value`](/context/describe_dimension_value)

## Example response

```json
{
  "status": "matched",
  "results": [
    {
      "type": "title",
      "id": "rol_15-1252.02",
      "name": "Software Engineer",
      "confidence": 0.94,
      "match_reason": "alias match on \"software developer\"",
      "job_family_id": "jfm_software_engineering",
      "job_level_id": "lvl_p3",
      "crosswalk": [
        {
          "system": "SOC 2018",
          "code": "15-1252"
        }
      ]
    }
  ],
  "meta": {
    "request_id": "gwx_req_7a1c",
    "taxonomy_version": "utb-1.0"
  }
}
```