Companies namespace
Reference for company directories, search, profiles, jobs, markets, and salary data.
A
JUse board.companies to build public company directories, profiles, company job pages, market pages, related-company rails, and company salary pages. These reads do not require a board-user session.
Shared behavior
Every method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. The final FetchOptions argument passes abort signals, headers, and framework cache directives through to fetch.
List envelopes include object, url, hasMore, nextCursor, and data. Company and company-job lists can also include catalog totals such as count, limit, and offset.
board.companies.list
List companies, ranked by open-job count. Use marketSlug to build a market-scoped directory, or membershipPlanId to build a members directory.
Every public company object carries membership: { planId, planName } when the company holds an active membership on a public membership plan, otherwise null. Render it as a member badge, and join planId against board.plans.list({ purpose: 'membership' }) when you need the level's description or price.
| Field | Type | Behavior |
|---|---|---|
cursor | string | Opaque cursor from nextCursor. |
marketSlug | string | Board-language or English market slug. Unknown values return 404. |
membershipPlanId | string | Scope the list to the companies holding an active membership on that published membership plan. Exact: the members become the whole result set, so count and paging describe the roster. Combines with marketSlug by intersection. |
limit | number | Page size from 1 to 100. |
offset | number | Companies to skip; takes precedence over cursor. |
data contains PublicCompany values. Each company includes id, name, slug, website/logo/description fields, published job counts, and links.public. relatedSearches can contain market suggestions.
A missing/private board or unknown market returns 404. Search infrastructure failure returns search_unavailable with status 503. Resolve an inbound market slug before rendering its canonical page.
Related methods: board.companies.markets.resolve and board.companies.search.
board.companies.retrieve
Retrieve one company by slug.
The detail adds markets: CompanyMarketRef[] to the public company shape.
The slug is URL-encoded. A missing/private board or unknown company returns companies_not_found with status 404.
Related methods: board.companies.listJobs, board.companies.similar, and board.companies.salaries.
board.companies.search
Search company names, optionally within one market.
CompaniesSearchBody accepts optional query text up to 200 characters, marketSlug, cursor, limit from 1 to 100, and offset (companies to skip; takes precedence over cursor). An empty or absent query browses all companies in job-count order. The SearchEnvelope carries the total count alongside the page limit/offset; iterate forward with nextCursor or page in parallel with offset. offset + limit above 10,000 returns 400 (pagination_offset_too_large).
This is a POST read. An unknown market or board returns 404. Search infrastructure failure returns search_unavailable with status 503.
Related methods: board.companies.list and board.companies.markets.resolve.
board.companies.listJobs
List one company’s published jobs.
CompanyJobsListQuery accepts an opaque cursor and a limit from 1 to 100.
The response uses PublicJobCard rows and can include count, limit, offset, and gatedCount. Invalid pagination returns 400. A missing board or company returns 404. Search infrastructure failure returns search_unavailable with status 503.
Related methods: board.jobs.retrieve and board.jobs.list.
board.companies.similar
Return companies related to one company, with companies that have more open roles surfaced first. The source company is excluded.
query.limit accepts 1–20 and defaults to 6.
An empty data array is valid. A missing board/company returns 404; unavailable similarity infrastructure returns search_unavailable with status 503.
Related method: board.companies.retrieve.
board.companies.markets
List a top-by-company-count preview of company markets. This is not a cursor-paginated full catalog.
query.limit accepts 1–200 and defaults to 100. query.search filters markets by name.
Each CompanyMarket contains slug, name, and companyCount. A missing/private board returns 404.
Related method: board.companies.markets.resolve.
board.companies.markets.resolve
Resolve a board-language or English market slug to canonical page metadata.
The response contains sourceSlug, canonicalSlug, displayName, and redirectTo; its type is market and geo is null. Emit a 308 when redirectTo is non-null. An unknown market returns company_markets_not_found with status 404.
Related methods: board.companies.markets and board.companies.list.
board.companies.salaries
Retrieve a company salary overview.
CompanySalary includes overall salary data, seniority comparisons with board baselines, competitors, top locations, category summaries, board aggregates, and currency. Aggregate salary values remain in the units returned by the API; format them for display without changing the wire data.
A missing board/company or a company with no salary data returns company_salary_not_found with status 404. Do not publish an empty salary page.
Related method: board.companies.salaries.category.
board.companies.salaries.category
Retrieve salary data for one job category at a company.
query.locale overlays board-language category names and canonical slugs. It defaults to English.
The response contains both categorySourceSlug and categoryCanonicalSlug, localized category name, overall/seniority aggregates, competitors, board-category baselines, and currency. Your frontend owns the 308 to categoryCanonicalSlug.
A missing board/company/category or missing category salary data returns company_category_salary_not_found with status 404.
Related methods: board.companies.salaries and board.taxonomy.categories.resolve.