Company search in the Hire app

This document is the single hire-side reference for:

• How @/packages/ui company search (ConnectedCompanySearchInput and related helpers) is wired for qwestly-hire (CompanyAssignmentForm, env, CSP, analytics).
• The public Hire HTTP API under /api/companies that those flows and other first-party clients call (typeahead, hydration, create/dedupe).

The shared component contract (props, CompanyOption shape, candidate vs hire profiles) lives in packages/ui/docs/features/company-search.md.

Migration note (2026)

Until early 2026 hire exposed /api/external/companies/* and /api/external/search/companies/* (gated by HIRE_APP_API_KEY) plus server actions in src/lib/company-search-server-actions.ts (with a FetchedLinkedInCompany Mongo cache). Those have been removed. User-facing pickers use ConnectedCompanySearchInput and call hire public routes and api-python public routes from the browser.

Product goals and trust boundaries

Goal: Let hire users (signup / onboarding /onboarding/company, /companies/new, and similar) pick a stable hire Company document (_id in MongoDB), optionally backed by vendor LinkedIn data.

Rules

1. Database search first. Typeahead hits hire GET /api/companies/search?query= (via searchHireCompaniesByName in packages/ui) before relying on vendor data.
2. Vendor lookup is browser → api-python. No Rapid credential in the browser; api-python holds it. Hire uses GET /api/public/linkedin-company (see §api-python).
3. Server-to-server vendor calls on hire are for enrichment (e.g. logo refresh), not the user-facing picker — /api/hire/company-rapid/* with QWESTLY_SERVICE_API_KEY (same shared secret as other api-python internal routes; see api-python require_qwestly_service).
4. Persist on hire write paths. Vendor-only CompanyOption rows (id === "") are persisted with POST /api/companies (same-origin). The handler OR-dedupes on linkedin_company_id, domain, and linkedin_url.

Architecture (hire browser + hire API + api-python)

flowchart TB
  subgraph hire-browser["Hire browser"]
    HUI["CompanyAssignmentForm → ConnectedCompanySearchInput\n(profile see § Hire UI)"]
  end
  subgraph hire["Qwestly hire"]
    GET_SEARCH["GET /api/companies/search"]
    GET_FILTER["GET /api/companies? … equality filters"]
    POST_COMPANIES["POST /api/companies"]
    LOGO_SVC["company-logo-upload / company-logo-refresh"]
  end
  subgraph py["api-python"]
    PUB["GET /api/public/linkedin-company\n(CORS + Referer gate)"]
    HIRE_S2S["GET /api/hire/company-rapid/*\n(QWESTLY_SERVICE_API_KEY)"]
    Rapid[RapidAPI]
  end
  HUI --> GET_SEARCH
  HUI --> GET_FILTER
  HUI --> POST_COMPANIES
  HUI --> PUB
  LOGO_SVC --> HIRE_S2S
  PUB --> Rapid
  HIRE_S2S --> Rapid

The candidate app uses the same ConnectedCompanySearchInput patterns against the same hire public endpoints where applicable; this doc does not duplicate candidate-specific screens.

Hire UI: CompanyAssignmentForm and packages/ui

Location: src/components/company-assignment-form/ — index.tsx, parts.tsx, use-company-assignment-form.ts, utils.ts.

Used for: /onboarding/company, /companies/new, and any future signup-style company picker that mounts this form.

Views

Three modes — name (default), external, manual — one active body with the other two as ghost controls. Switching to external or manual clears any staged selectedCompany (preview) so those flows start without a leftover name-search pick.

Name view → ConnectedCompanySearchInput

• explicitParentClearOnly — Wired from CompanyAssignmentNameView in parts.tsx. When set, CompanySearchInput only notifies the parent with onSelect(null) from the input’s explicit clear (X), not when the user edits the query or blurs with partial text. The preview card stays until dismiss, a new list pick, confirm, or switching to external/manual.
• companySearchProfile="candidate" — The candidate profile hides the package’s grey panel and segmented “Company database / External lookup” toggle so hire only shows the bare typeahead + popover. Hire owns external and manual UX in separate views.
• hireOrigin: Server appBaseUrl (from APP_BASE_URL / VERCEL_BRANCH_URL) passed as prop — canonical origin for GET /api/companies/search and hydration fetches.
• Two-phase internal suggestions (aligned with candidate onboarding):
  • Query length 1–2: localSuggestions={filterSp500CompaniesByQuery} from src/lib/hire-company-search-helpers.ts — prefix match on the @/packages/ui/sp500-tech-companies dataset (cap 20), no network. Rows are vendor-only (id === "", linkedin_company_id set, linkedin_url from slug). When the SP500 row has logo_path, hire sets logo_url via sp500LogoUrlFromPath so the picker can show logos for instant suggestions.
  • Length ≥ HIRE_COMPANY_MIN_SEARCH_LENGTH (3): debounced (500 ms) searchHireCompaniesByName → GET /api/companies/search. Results merged via mergeSp500WithHireResults (dedupe by linkedin_company_id then name; hire wins). Sentinel rows from the hire API are ignored during merge.
  • Sparse merged list (hire queries only, length ≥ 3): if the merged list has at most four real company rows (after dedupe—the rows the user actually sees), hire appends a sentinel CTA option (createCompanySearchManualCtaOption from @/packages/ui/lib/company-search, default label “Company not listed? Try another way”). Choosing that row does not select a company: useCompanyAssignmentForm records COMPANY_SPARSE_SEARCH_CTA_CLICKED, switches the form to the external (LinkedIn/domain) view, and bumps searchResetKey to remount the combobox. Shorter queries (SP500-only) do not append this row.
  • hireSearchMinQueryLength={3} — below threshold the hire fetch does not run (SP500-only).
• Hydration on select is implemented inside packages/ui (handleSelectWithHireHydration in connected-company-search-input.tsx): vendor-only rows without logo_url may be resolved against GET /api/companies?linkedin_company_id= and/or search before onSelect. Hire’s handler uses isHireMongoObjectIdString to set selectionSource (hire_db vs rapid) and to skip POST /api/companies when the row already has a hire _id.
• Errors: onHireSearchError → PostHog COMPANY_FETCH_FAILED (source: "hire_db").

External view

• Single Input + Search. detectExternalKind (utils.ts) treats input as LinkedIn URL if it matches linkedin.com/company/, else domain.
• Validation: validateExternalDomainInput / validateExternalLinkedInUrlInput from @/packages/ui/lib/company-search.
• Submit calls resolveCompanyViaPython(pythonOrigin, …) from packages/ui (see §Environment). requirePythonApiBaseUrl() runs in the submit path so name/manual still work if python base URL is unset.
• 404 from api-python (not found) is expected; UI shows a friendly message; analytics COMPANY_FETCH_FAILED { source: "rapid", status: 404, kind }.

Selection preview and confirm

• Preview between body and view switcher: logo / fallback, name, tagline, links, dismiss (disabled while submitting), “Select this company”.
• Confirm: If company.id is a hire Mongo id → use it, no POST. Else POST /api/companies with buildCreatePayloadFromCompanyOption (utils.ts): base fields from CompanyOption, plus mapVendorSnapshotToCompanyPostFields(company.vendor_snapshot) from src/lib/map-vendor-snapshot-to-company-post.ts when the Rapid-backed row carries a snapshot (see tests in __tests__/unit/map-vendor-snapshot-to-company-post.test.ts).
• searchResetKey remounts the combobox after dismiss so internal input state resets.

Manual view → SimpleCompanyForm

src/components/simple-company-form.tsx: required name, optional website / description in a collapsible (default collapsed). Submit → buildPublicCompanyPostBody → POST /api/companies → onCompanySelected. No preview step.

Popover / dark theme

Radix PopoverContent portals to document.body. CompanySearchInput in packages/ui uses explicit light surface colors on the dropdown so suggestions stay readable when <html> is dark (hire does not rely on global [data-radix-popper-content-wrapper] hacks).

Analytics (PostHog)

Environment and build

Admin: out of scope

(private)/admin/companies/new still uses server actions in actions.ts and company-rapidapi — not ConnectedCompanySearchInput yet.

packages/ui symbols used by hire

The shared component does not POST — hire owns POST /api/companies in the form hook.

Unit tests: merge / SP500 / sparse CTA behavior for hire helpers lives in __tests__/unit/hire-company-search-helpers.test.ts.

Public Companies API (/api/companies)

Implemented in [src/app/api/companies/[[...slug]]/route.ts](../../src/app/api/companies/<strong class="wikilink-unresolved">...slug</strong>/route.ts). Unauthenticated surface for first-party apps; CORS/middleware per src/lib/proxy-helpers.ts (PUBLIC_ROUTE_PREFIXES). POST may still attach user_id when a session exists and the body omits linkedin_company_id (see below).

Implementation helpers: src/lib/company-public-api-helpers.ts; resolution / projections: src/services/company-public-resolution.service.ts. Equality filters for company_name and linkedin_company_slug use buildPublicCompanyExactNameFilter and buildPublicCompanyLinkedInSlugUrlFilter, composed into findSlimCompanyByFilter or listSlimCompaniesPaginatedPublic.

GET /api/companies/search

MongoDB-only name typeahead (no vendor).

Query length: Max 100 characters (PUBLIC_COMPANY_NAME_QUERY_MAX_LENGTH); longer → 400 with error: "query too long". Shorter than 2 characters after trim → { "companies": [] } (no error).

Matching: Length ≤2 → prefix on name (case-insensitive). Longer → substring on name.

Response: { "companies": SlimCompanyPublic[] } — _id, name, optional domain, logo_url, linkedin_url, linkedin_company_id, tagline.

Errors: 400 invalid limit or query too long; 500 server failure.

GET /api/companies

Success envelope (all successful list responses):

{
  "success": true,
  "companies": [],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 0,
    "totalPages": 0
  }
}

Unsupported combinations → 400

• More than one equality filter among domain, linkedin_url, linkedin_company_id, company_name, linkedin_company_slug (PUBLIC_COMPANY_RESOLUTION_EXCLUSIVE_PARAMS).
• ids with any equality filter.
• ids with page or pageSize.

Bare GET (no valid combination) → 400 with hint.

Non-2xx: JSON { "error", "hint", ... } — not the success envelope. Clients must not treat companies.length === 0 on an error response as “not found.”

A. Paginated directory (no filter, no ids)

At least one of page or pageSize required. Empty filter, sort by name ascending.

companies[]: directory row — _id, name, optional parent_org_id, industries (comma-separated when present).

B. Equality filter (lookup / dedupe)

Exactly one of:

Pagination: If page / pageSize omitted → defaults page=1, pageSize=1 (PUBLIC_COMPANY_FILTER_*) for cheap dedupe reads.

companies[]: SlimCompanyPublic (same projection as search).

Dedupe: companies.length === 0 → not found; >= 1 → found (use companies[0] for single-hit).

pagination.total (fast path): When both page and pageSize are omitted, the server may use a single-query fast path without countDocuments. Then total is bounded by pageSize (0 or 1) and is not a uniqueness guarantee — total: 1 means “at least one match.” To detect duplicates, pass pageSize >= 2. When multiple match, companies[0] is the alphabetically first by name (same as page=1 on the paged path).

C. Batch by ids

No page / pageSize. companies[]: SlimCompanyPublic. Order not guaranteed; missing ids omitted (not errors). pagination: page 1; pageSize / total = returned count; totalPages 1 if total > 0 else 0.

GET /api/companies/{id}

{id} must be 24-char hex ObjectId else 400. Response: single SlimCompanyPublic at JSON root. 404 if missing.

POST /api/companies

Signup-style create. JSON. name required else 400.

Dedupe: If body includes any of domain, linkedin_url, linkedin_company_id, server builds $or over normalized fields. Match exists → 200 { "exists": true, "company": { "_id", "name" } }.

Create: 201 { "exists": false, "company": { "_id", "name" } }; new doc claimed: false.

Optional fields on create: logo_url, linkedin_company_id, tagline, website, domain, linkedin_url, crunchbase_url, industries, employee_count, employee_range, year_founded, funding_info, description (and others supported by the route — see handler).

• logo_url: LinkedIn logo URLs may be uploaded to CDN and replaced with CDN URL.
• domain / linkedin_url: Invalid values may be skipped (not always hard errors).
• user_id: If linkedin_company_id absent and getUserId() returns a user, set on new doc.

Errors: 500 with message / details.

GET migration (breaking, historical)

Older GET /api/companies used { exists, company }. Replaced by success + companies + pagination. Use companies[0]._id when present.

POST /api/companies responses still use exists / company — unchanged.

Constants (summary)

Routing note

Catch-all registers search and root GET '' before {id} so query-only /api/companies is not parsed as an id. The segment search is not a valid ObjectId for {id}.

Removed hire routes (redirect guide)

Other /api/external/... routes (e.g. jobs) are unrelated; they still use HIRE_APP_API_KEY where documented.

api-python

Browser (user-facing)

Server-to-server (hire services, not picker)

Future internalization (/api/internal/company/*, service API key) is tracked in api-python planning docs, not here.

Known gaps and follow-ups

1. Vendor snapshot coverage: buildCreatePayloadFromCompanyOption forwards vendor_snapshot through mapVendorSnapshotToCompanyPostFields. Rows without a snapshot still only send the thin CompanyOption surface fields unless filled elsewhere.
2. No hire-side Mongo cache for browser → python reads (removed FetchedLinkedInCompany). Revisit cost/latency in api-python or a shared cache if needed (docs/plan/cache-linkedin-fetches.md).
3. QWESTLY_SERVICE_API_KEY on Hire must match api-python for logo upload/refresh and other server → Python /api/hire/company-rapid/* calls (optional later move to /api/internal/company/* is an api-python product decision).
4. Stale-logo / CDN promotion on public read paths — separate track.

Changelog (maintenance)

Operational checklist

• New picker needing vendor + hire DB: reuse ConnectedCompanySearchInput, do not add parallel Rapid proxies from hire for user-visible search.
• Changing create contract: update POST /api/companies handler and buildCreatePayloadFromCompanyOption / buildPublicCompanyPostBody / types in company-assignment-form/utils.ts together.
• requirePythonApiBaseUrl: avoid silent fallbacks — misconfig should fail clearly.
• CSP: extend connect-src for specific api-python origins when adding environments; do not wildcard all of https:.

References

• packages/ui/docs/features/company-search.md — shared component contract
• docs/plan/cache-linkedin-fetches.md — caching discussion
• api-python: api/routes/browser_public/linkedin_company.py, lib/public_first_party.py (Referer/CORS)
• hire-onboarding.md § Company step — wizard UX summary