Me namespace

board.me contains the candidate and employer operations performed as the current board user. Token-authorized exceptions (confirmEmailChange, notification unsubscribe) do not require a bearer; every other method does. Work-email consume is board.auth.verifyWorkEmail, not a board.me method.

Do not put these responses in a shared public cache. In SSR applications, keep a module-scoped nostore client and pass the current request’s authorization in the method’s final FetchOptions argument.

The undefined preserves the empty query slot in methods shaped as (query?, options?). Methods without a query slot accept options directly.

Identity

BoardUser.hasPassword is false for magic-link and OAuth-only accounts. Offer change-password only when it is true. Passwordless accounts should call board.auth.forgotPassword (the existing reset email) rather than updatePassword, which returns no_password.

Account deletion is synchronous, irreversible, and resolves after a 204 response. Do not present it as a reversible sign-out action. updatePassword keeps the caller signed in; every other session dies. Email change is verify-then-switch: requestEmailChange mails the new address and can return same_email or email_taken; confirmEmailChange consumes the token with no session.

Candidate profile

Profile updates use merge-patch semantics: omitted fields remain unchanged. Collection create/update methods return the affected entity; delete methods resolve void.

handleAvailable is advisory. A later profile.update rechecks the handle and can still throw candidate_handle_taken after another user claims it.

updateSkills and updateLanguages replace their ordered sets rather than merging individual entries. uploadAvatar accepts JPEG, PNG, or WebP up to 5 MB and builds the multipart body for you.

retrieveCustomFields returns the profile field definitions with the signed-in candidate's current values. updateCustomFields additively updates owner-editable values, so omitted fields remain unchanged. retrieveObjectReferences returns the editable collection definitions and resolved selections. listObjectReferenceChoices searches and pages the active records for one owner-editable collection field, including a private field; use its returned IDs when building a selection. updateObjectReferences replaces the complete editable selection set with body.selections; send an empty array to clear all editable selections.

Home location and commute distance

Job matches use where the candidate lives and how far they will commute. Pick the place with board.locations.search and send its id as locationId; the server looks up the place and its coordinates. The candidate's country is their home place's country: while a place is stored or sent, countryCode is that place's country and a countryCode you send is ignored (no error), so hide your country field then. countryCode only applies when there is no home place. Removing the place (locationId: null) keeps the last country. The profile returns:

update accepts:

• locationId: an id from board.locations.search. It also sets location to the place name unless you send location too. Sending the stored id again keeps the place; sending null removes the place and keeps location. Changing location without locationId removes the place.
• commuteRadiusKm: 1–250 km, stored to one decimal place. null resets it to the default.

An unknown locationId throws locations_invalid_id (400). locations_unavailable (503) means the lookup is temporarily down; keep the form values and let the candidate retry.

Hide the commute field when placeType is region or country: a region has no single point to measure from, so it matches on-site jobs anywhere in its country.

Use the installed TypeScript types for the complete optional profile and collection fields; they are generated from the same API schemas as the SDK.

Notification preferences

unsubscribeWithToken is intended for one-click email links and resolves after a 204 response.

Channels are messageEmails, applicationEmails, and recommendedJobEmails. The first two default subscribed when no row exists. recommendedJobEmails is explicit opt-in: a missing row means unsubscribed. Each item includes subscribed and additive waitlisted. subscribed: true means they asked, including while queued; they receive mail only when subscribed is true and waitlisted is false. PUT at the Email subscribers cap waitlists instead of failing.

Marketing consent

Marketing consent is a property of the signed-in board user, separate from job alerts and notification preferences. The wording someone agrees to is yours — render your own disclosure copy beside any control that calls these methods; the API records the decision, never the prose. These helpers derive the person from the verified bearer and cannot target another email.

Leave any checkbox unticked by default and call nothing when it stays unticked — absence of a record means no consent, never a default. Withdrawal is at least as direct as grant and stays effective while any downstream webhook delivery is pending.

Employer companies and claims

A board user becomes an employer by opening or receiving a company membership. An approved membership is required for company editing, job management, billing options, and the applicant pipeline.

companies.search requires { q } and accepts limit from 1–50. create can adopt an existing same-domain company. claim can return an approved membership immediately on an email-domain match; otherwise it remains pending.

companies.retrieve returns my full editable company profile (summary, socials, logo, description) — the read half of update, for pre-populating an edit form. companies.uploadLogo uploads and attaches a company logo (JPEG/PNG/WebP/GIF, ≤2 MB) in a single multipart POST and returns the updated company with its new logoUrl. Both require an approved membership.

companies.retrieveCustomFields and companies.retrieveObjectReferences return the definitions and current values or resolved selections for the named company. companies.listObjectReferenceChoices searches and pages active records for one owner-editable collection field, including a private field. Custom-field updates are additive, while companies.updateObjectReferences replaces the complete editable selection set. These methods require an approved company membership and only accept fields the company owner can edit.

companies.delete is admin-gated and returns company_deletion_disabled when the board operator has turned employer company deletion off. listMembers is visible to any approved member and includes role (admin or member) plus approvedBy join provenance (owner_creation, domain_match, work_email_verification, admin, or invite). updateMemberRole and removeMember are admin-only; demoting or removing the last admin returns last_admin. leave deletes the caller’s own membership; leaving as the last admin also returns last_admin. A company always has at least one admin. listInvites is visible to any approved member. createInvite and revokeInvite are admin-only; invites expire after 7 days; duplicate members or pending invites return already_member / already_invited. acceptInvite requires a bearer session whose email matches the invite (invite_email_mismatch otherwise) and an employer-role account (candidate_role for candidates).

workEmail.verify sends a 24-hour verification link for a pending claim. Consume that token with board.auth.verifyWorkEmail({ token }) — see Employer work-email verification. workEmail.confirm(slug, body) is the deprecated predecessor; it still works, but slug is ignored.

talentAccess.retrieve answers "does this viewer currently have talent access?" for talent-surface CTAs. An approved employer with an active talent subscription or credit pack (or any approved employer on a board without a talent paywall) gets hasTalentAccess: true; candidates get false. It also returns the charging model and remaining company-scoped unlock/message credits. Never cache it in a shared cache. retrieveCandidate is the per-candidate gate for the opaque /p/{id} route. checkout returns the same connected-account mount kit as candidate-access checkout (origin: talent_access). claim grants a public free talent-access plan without Stripe and is idempotent for the same company and plan. unlock is idempotent (alreadyUnlocked: true with no decrement). upgrade swaps the company's primary talent_access subscription in place; never start a second checkout. companyId is required on writes when the viewer has more than one approved membership (company_required). Message credits spend inline on conversations.start. This is a different buyer from board.me.access.

Employer jobs and billing

Every job method is scoped by company slug. New employer jobs are held drafts. publish only republishes a job still inside its paid window; a held or expired draft can require checkout. jobs.list returns every status: draft, published, expired, archived, and pending_approval. A pending_approval job is waiting for the board operator to approve it; the employer cannot publish it.

checkout can resolve with status: 'checkout' and a hosted payment URL, status: 'published' when a free, bundle, subscription, or member-credit option publishes immediately, status: 'pending_approval' when a free post (or invoice publish-on-issue) is held for operator review, or status: 'invoice_sent'. Branch on the returned status instead of assuming every call needs a redirect, or that a 200 means the job is live.

billingPortal.create mints a Stripe Customer Portal session for the company. Job-posting and talent-access subscriptions share one Stripe customer, so this is the manage-billing surface for both. There is no board.me.talentAccess.portal.

jobs.create requires remoteOption. A salaryMin or salaryMax also needs salaryCurrency and salaryTimeframe. jobs.update cannot clear remoteOption.

jobStats.retrieve returns one EmployerJobStat per company job — views, applyClicks, and applications (null for an external-apply job, which has no native pipeline) — over an all-time window, the same funnel the hosted employer jobs table shows. jobStats.timeseries returns daily EmployerJobStatsPoint buckets (date, views, applyClicks) aggregated across the company's jobs to drive a chart; the optional since/until window defaults to the last 30 days. Both require an approved membership and are never cached. Analytics degrade to zeroes (or an empty series) rather than failing when the upstream analytics source is unavailable, so a 0 can mean either "no activity" or "analytics briefly unavailable."

profileStats.retrieve returns the company-level profileViews total — views of the company profile page itself (/companies/{slug}), with its tab subpaths (/jobs, /salaries) and bots excluded — over an all-time window, for a dashboard "profile views" metric. profileStats.timeseries returns daily EmployerProfileViewsPoint buckets (date, views) for a sparkline; the optional since/until window defaults to the last 30 days. Both require an approved membership, are never cached, and degrade to 0 / an empty series on an analytics outage.

Applicants and pipeline stages

The applicant read returns the job header, stage rail, applicants, signed resume links, and activity timelines in one EmployerPipeline. Pipeline mutations resolve void; re-read applicants.list for fresh state.

applicants.list requires { job: jobId } and accepts an optional stage filter. Bulk moves are atomic for applicants of one job. Company-private notes appear in the applicant timeline.

Custom stages are limited to ten per job. Protected system stages cannot be removed, and a reorder must include each stage exactly once with the protected terminal order preserved.

Recommended talent

Candidates who fit a job this company posted and who have not applied to it, best match first. Ranking is computed server-side from the job (skills, title) against the candidate corpus and improves over time without any contract change.

query.job is required and must name a job belonging to :slug; a job that is still a draft raises job_not_published rather than returning an empty list, because only a published job carries the vectors a match needs. Requires an approved membership. Never cached.

This is a sourcing surface, and that shapes the contract. Applicants are excluded — they belong to the pipeline, and ranking them would be evaluation rather than discovery. Order is the ranking: no rank, score, band, or ranker identity appears in the response, now or later. The item wrapper carries only candidate today so that typed reasons and a coarse strength band can be added as minor releases. Do not build an automated reject, advance, or filter on this output.

Each item embeds the same talent_directory_entry the public directory returns, so directory rendering works unchanged. jobSearchStatus is populated here even for candidates who scoped it to employers only — the caller is a verified employer, which is what that setting is for. Only candidates who chose to be discoverable appear, and one whose status is not_looking never does. The list is a bounded top slice rather than everyone who matched, so expect it to be short — and note that low relevance alone does not empty it: v0 still returns its top slice on a weak board. An empty data means no candidate on that page survived — either nothing was ranked at all, or the entries for that page were dropped after ranking (profile deleted or hidden, or the candidate opted out since the last sync). It is not a relevance signal, and it can arrive mid-pagination, so follow hasMore / nextCursor rather than treating the first empty page as the end. Render it as "no candidates yet" rather than as an error.

Talent lists and sourced candidates

Two company-private records, one picker. A talent list is a named, company-owned predicate over the public directory (optional jobId binds it to one job). A sourced candidate is per-job membership on an unstaged rail. Saving a candidate always writes sourced membership; a bound list is one-click, an unbound list needs a job picker. Approved company members share both. Requires an approved membership. Never cached.

create accepts { name, filters?, job? }. update is a merge patch; pass job: null to unbind. List filters reuse the frozen /talent query (q, skill, jobSearchStatus, languages, openToRelocate, sort); place, seniority, permitCountry, and interestedRole are accepted no-ops until later. Deleting a job unbinds lists that pointed at it and deletes that job’s sourced rows.

sourcedCandidates.list requires { job } and omits anyone who already has a pipeline application for that job — convert-on-drop is not a second pipeline. add is idempotent (created: false when the pair already exists). convert writes a jobApplications row with source sourced: hidden from the candidate’s /me/applications, apply emails, and funnel counts until a native or guest apply flips the source. Pass a visible pipeline stage; applied aliases to the system review stage. Convert never raises employer_company_name_taken. A board without a native pipeline raises sourced_convert_unavailable (409). Missing rows raise talent_list_not_found or sourced_candidate_not_found.

Drop onto the job kanban converts; do not keep a sourced stage on the pipeline rail.

Signed-in job alerts

Authenticated alerts are active immediately and do not use the anonymous double-opt-in flow. A user can have up to ten; removing an alert is the only pause mechanism.

update replaces the alert’s filters and frequency in full. Check board.context().features.jobAlerts before exposing the route, while still handling job_alerts_disabled from the API.

Recommended jobs

Personalized jobs for the signed-in candidate, best match first. Ranking is computed server-side from the candidate's profile (skills, roles, seniority, work authorization) and improves over time without any contract change — the response never exposes scores or ranker internals.

On-site and hybrid jobs are limited to the candidate's commute distance around a city or locality locationPlace, or to their country when openToRelocate is on or the home place is a region or country. Remote jobs are not limited by distance. See Home location and commute distance.

Each item wraps the same slim job_card the jobs list returns. Jobs the candidate already applied to are excluded; saved jobs are not. An empty list means the profile has no usable matching signal yet — read board.me.profile (parseStatus, skills) to decide whether to prompt for a resume upload rather than showing an empty rail.

Applications, resume, and saved jobs

Applications are keyed by application ID. Applying to a job itself lives at board.jobs.apply; this namespace manages applications already submitted by the current candidate.

updateFacts is a merge-patch and is accepted only while the application is editable. withdraw permanently removes the application.

Resume upload creates multipart data internally and starts asynchronous parsing. opts accepts keepResumeOnFile, importMode: 'append_only' | 'replace_all', and confirmReplaceAll. Poll resume.retrieve until parseStatus is parsed or failed, then re-read the profile collections. Deleting the stored resume does not remove fields already imported into the profile.

Saving an already-saved job converges on the existing row. Unsaving an unknown job ID still resolves 204.

Conversations and messages

Messaging is polled REST, not a realtime transport. Poll the conversation list, unread count, or current thread at a bounded interval—the reference cadence is 3–5 seconds—and cancel polling when the view is inactive.

list({ archived: true }) returns the archived view. Thread messages are oldest-first; an unsent message remains as a tombstone with an empty body and deletedAt set.

start is the employer-to-candidate cold-message flow and converges on an existing thread. It accepts the recipient as exactly one of candidateBoardUserId or candidateHandle (the public handle from the talent surfaces — resolved server-side through the same gates). startAboutApplication contacts an applicant in application context. Message edit and unsend are limited to the author’s 15-minute window. Reporting a message addressed to the current user also blocks its author.

Blocks

Creating and removing a block are idempotent. Blocking is silent; it changes the messaging relationship but does not notify the blocked user.

Candidate job access

Enumerate public offers with board.paywall.offers, then use the authenticated board.me.access methods to purchase and confirm an entitlement. Expose this flow only when board.context().features.candidatePaywall is true. Starting checkout also requires a candidate profile.

checkout returns the connected-account mount values needed by Stripe.js. It does not load Stripe.js or mount the checkout UI. returnPath is a safe relative path.

Poll retrieveCheckout until the state is complete or expired; an open session can be remounted with its client secret. After completion, call grant again. No entitlement is represented by a successful { hasAccess: false } response, not a 404.

portal is available for a recurring grant and returns the billing-portal URL. Its optional body accepts a return path.

Pagination, features, and errors

List methods return ListEnvelope<T> and accept their documented cursor/limit query where present. Keep all board.me reads and writes out of shared public caches, including lists that appear non-sensitive.

Before rendering optional account routes, check the matching board context feature—especially candidates, employers, jobAlerts, and candidatePaywall. Feature flags improve navigation; the API remains authoritative and can reject stale or unauthorized state.

Every non-2xx API response throws BoardApiError. Common branches include:

• 401 for a missing or expired board-user token—enter the application’s explicit refresh/sign-in flow.
• 403 for another user’s resource, an unapproved employer membership, messaging restrictions, or entitlement restrictions. candidate_profile_required is the 403 for a candidate profile write (anything but displayName on profile.update, experience and education create or update, updateSkills, updateLanguages) from an account with no candidate profile, such as an employer. Render candidate screens only when me.role === 'candidate'.
• 404 for an ID that does not exist or does not belong to the current user.
• 409 for state conflicts such as a handle already taken.
• 429 for rate-limited messaging or other protected writes.

Domain codes give the precise branch: examples include candidate_handle_taken, candidate_profile_required, applications_not_found, messaging_cold_rule, messaging_edit_window_expired, employer_not_member, employer_payment_required, employer_jobs_quota_exceeded, no_password, email_taken, last_admin, already_invited, invite_email_mismatch, company_deletion_disabled, paywall_no_candidate_profile, and paywall_offer_not_found.

Do not turn an exception into an empty list. Log code and requestId without logging authorization, resume URLs, checkout secrets, or candidate data, then preserve unexpected errors for the framework’s error boundary.