Talent namespace

List or retrieve candidate talent records when the authenticated user has the required access.

Anonymous viewers get candidate profiles whose visibility is public. A signed-in board user also gets profiles visible to signed-in users only. Hidden profiles are never returned. Board configuration can disable the directory or restrict it to entitled employers.

board.talent.list()

Lists the candidate cards the viewer can see. Default order is job-search status then recent profile activity (sort: 'relevance'); sort: 'newest' is recency only.

limit accepts 1–100. offset (candidates to skip) takes precedence over cursor. The envelope carries the total count alongside the page limit/offset; iterate forward with the opaque nextCursor or page in parallel with offset. offset + limit above 10,000 returns 400 (pagination_offset_too_large).

Every filter applies, and count, hasMore, and nextCursor reflect all of them:

• languages takes comma-separated names; every name must match.
• place takes a place slug, the same slugs as the jobs location filter. Take them from board.talent.places.list, which lists the places where the board's candidates live; board.taxonomy.places.list lists only places with jobs. It matches candidates whose home place is that place or lies inside it, so a city slug returns that city and a country slug returns the whole country. An unresolvable slug does not filter, so pass the slug, not the place's display name. radius widens a city or locality place to candidates whose home city or locality is within that many km of it: 1–250, decimals allowed (8.05 is 5 mi). Omit it for the place only. It is ignored for region and country places and without place, and candidates whose home is a whole region or country never match by distance.
• seniority takes entry_level, mid_level, senior, manager, director, or executive.
• permitCountry takes an ISO 3166-1 alpha-2 code and matches candidates authorized to work in that country.
• interestedRole matches a whole role name, case-insensitively, as skill does.

A place search has no default distance, as on jobs. To offer the same choices as job search, build them with searchRadiusOptions, defaultSearchRadius, and distanceUnitForCountry from @cavuno/board/format, and pass the option's km:

board.talent.places.list()

Lists the places where the board's directory candidates live, busiest first, each with candidateCount: how many of them the viewer can see there. A candidate counts in their home place and every place above it, so a country counts every candidate in its cities and regions. Use it to build the directory's location filter, and pass a place's slug as board.talent.list's place.

Counts follow the directory: anonymous viewers count profiles whose visibility is public, and a signed-in board user also counts profiles visible to signed-in users only. Places with no candidate for the viewer are left out. Each place carries id, parentId, slug, canonicalSlug, name, displayName, placeType, countryCode, and regionCode, as on board.taxonomy.places.list; join on parentId to group cities under regions and countries. displayName is in the board's language, falling back to the English name. canonicalSlug is in the board's language where that language has unique place slugs; otherwise, and for a place with no translation, it is the English slug. Link a place's talent location page with talentLocationPath(place.canonicalSlug) from @cavuno/board/paths; board.talent.list's place filter accepts canonicalSlug or slug. board.taxonomy.places.resolve resolves either slug, also for a place with candidates but no jobs, but its canonicalSlug and redirectTo follow the job location pages and can differ from the talent place's canonicalSlug (a translated slug where the board language's place slugs are not unique, or a code-based slug for a country or region with jobs). Canonicalise a talent location page against the talent place's canonicalSlug, not redirectTo.

limit accepts 1–500 and defaults to 100. The list is not paginated. It is empty until the board's place counts have been built. Access errors are the directory's (below).

Pass q to back a location search box. It matches as q does on board.taxonomy.places.list: case- and accent-insensitive, a place matches when q appears anywhere in its name, including mid-word, or when its slug starts with q. Places whose name or slug starts with q rank first, then places with more candidates. On a board in another language, q also matches the place's name and slug in that language. Fewer than two characters returns an empty list. With q, limit defaults to 10 and at most 50 places are returned.

board.talent.retrieve()

Retrieves a public candidate by profile handle or board-user ID.

The profile contains its public header plus experience, education, skills, and languages. Job-search status can be null when the candidate exposes it only to employers.

Authorization and errors

• talent_directory_not_found (404)—the directory is disabled.
• talent_directory_restricted (403)—the current viewer needs employer access; render the employer sign-in or upgrade journey.
• talent_not_found (404)—the handle is unknown or the profile is not public. Do not reveal which case applies.

When access depends on a bearer or employer entitlement, bypass shared caches. A feature flag can hide the route early, but only the API response authorizes the viewer.