Companies namespace

Reference for company directories, search, profiles, jobs, markets, and salary data.

Use 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.

1234
board.companies.list(
  query?: CompaniesListQuery,
  options?: FetchOptions,
): Promise<CompanyListEnvelope>

Field	Type	Behavior
`cursor`	`string`	Opaque cursor from `nextCursor`.
`marketSlug`	`string`	Board-language or English market slug. Unknown values return 404.
`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.

123456789
const page = await board.companies.list({
  marketSlug: 'cybersecurity',
  limit: 20,
  offset: 0,
});

for (const company of page.data) {
  console.log(company.name, company.publishedJobCount);
}

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.

`board.companies.retrieve`

Retrieve one company by slug.

12345
board.companies.retrieve(
  companySlug: string,
  query?: Record<string, never>,
  options?: FetchOptions,
): Promise<PublicCompanyDetail>

The detail adds markets: CompanyMarketRef[] to the public company shape.

1234
const company = await board.companies.retrieve('acme');

console.log(company.name);
console.log(company.markets.map((market) => market.name));

The slug is URL-encoded. A missing/private board or unknown company returns companies_not_found with status 404.

`board.companies.search`

Search company names, optionally within one market.

12345
board.companies.search(
  body: CompaniesSearchBody,
  query?: Record<string, never>,
  options?: FetchOptions,
): Promise<SearchEnvelope<PublicCompany>>

CompaniesSearchBody accepts optional query text up to 200 characters, marketSlug, cursor, and limit from 1 to 100. An empty or absent query browses all companies in job-count order.

123456789101112
const controller = new AbortController();
const results = await board.companies.search(
  {
    query: 'robotics',
    marketSlug: 'defence-technology',
    limit: 10,
  },
  undefined,
  { signal: controller.signal },
);

console.log(results.data);

This is a POST read. An unknown market or board returns 404. Search infrastructure failure returns search_unavailable with status 503.

`board.companies.listJobs`

List one company’s published jobs.

12345
board.companies.listJobs(
  companySlug: string,
  query?: CompanyJobsListQuery,
  options?: FetchOptions,
): Promise<JobCardListEnvelope>

CompanyJobsListQuery accepts an opaque cursor and a limit from 1 to 100.

12345
const jobs = await board.companies.listJobs('acme', { limit: 10 });

for (const job of jobs.data) {
  console.log(job.title, job.links.public);
}

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.

12345
board.companies.similar(
  companySlug: string,
  query?: CompanySimilarQuery,
  options?: FetchOptions,
): Promise<ListEnvelope<PublicCompany>>

query.limit accepts 1–20 and defaults to 6.

12345
const { data } = await board.companies.similar('acme', { limit: 6 });

for (const company of data) {
  console.log(company.name);
}

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.

1234
board.companies.markets(
  query?: CompanyMarketsListQuery,
  options?: FetchOptions,
): Promise<ListEnvelope<CompanyMarket>>

query.limit accepts 1–200 and defaults to 100. query.search filters markets by name.

12345678
const markets = await board.companies.markets({
  search: 'robotics',
  limit: 20,
});

for (const market of markets.data) {
  console.log(market.name, market.companyCount);
}

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.

1234
board.companies.markets.resolve(
  market: string,
  options?: FetchOptions,
): Promise<TaxonomyResolution>

123456789
const market = await board.companies.markets.resolve('cybersecurity');

if (market.redirectTo) {
  console.log('Redirect permanently to:', market.redirectTo);
}

const companies = await board.companies.list({
  marketSlug: market.sourceSlug,
});

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.

1234
board.companies.salaries(
  companySlug: string,
  options?: FetchOptions,
): Promise<CompanySalary>

1234
const salary = await board.companies.salaries('acme');

console.log(salary.currency, salary.overallSalary);
console.log(salary.bySeniority, salary.topLocations);

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.

123456
board.companies.salaries.category(
  companySlug: string,
  categorySlug: string,
  query?: SalaryDetailQuery,
  options?: FetchOptions,
): Promise<CompanyCategorySalary>

query.locale overlays board-language category names and canonical slugs. It defaults to English.

1234567891011
const salary = await board.companies.salaries.category(
  'acme',
  'software-engineer',
  { locale: 'de' },
);

if (salary.categoryCanonicalSlug !== 'software-engineer') {
  console.log('Canonical category:', salary.categoryCanonicalSlug);
}

console.log(salary.categoryName, salary.overallSalary);

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.