GET /v1/lookup/{type} · markdown

Resolve plain language to a standardized ID

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
`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 · get_postings · describe_dimension_value

Example response

{
  "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"
  }
}