How to show job matches

Job matches are a signed-in account surface. Keep the public job card usable before login and make /matches (or /account/matches) the authenticated page.

Hosted Cavuno boards use /matches. The API and SDK stay recommendedJobs / /me/recommended-jobs.

Load the ranked list

Each item wraps the same slim public job card. Order is the ranking. The response never includes scores, weights, or ranker identity.

123456
const { data } = await board.me.recommendedJobs.list(
  { limit: 20 },
  { cache: 'no-store', headers },
);

data[0]?.job.title;

If the account can exceed one page, iterate with the list cursor rather than treating the first page as complete.

Handle an empty list

Cold start is an empty list — no hint field. Drive a resume-upload CTA from board.me.profile and board.me.resume (parseStatus, skills), not from the list response.

123456789101112131415
const skills = await board.me.profile.listSkills({
  cache: 'no-store',
  headers,
});
const resume = await board.me.resume.retrieve({
  cache: 'no-store',
  headers,
});

if (
  data.length === 0 &&
  (skills.data.length === 0 || resume.parseStatus !== 'parsed')
) {
  promptResumeUpload();
}

Handle the authentication boundary

When the visitor is signed out, send them through the normal login flow with a return path of /matches. Validate the return path before redirecting back. On 401, use the application's single refresh path.

Verify the journey

1. Sign in as a candidate with skills or a parsed resume and confirm Matches returns jobs in a stable order.
2. Sign in as a candidate with an empty profile and confirm the empty state plus a resume CTA.
3. Apply to a returned job and confirm it disappears on the next list.
4. Sign in as a second user and confirm the first user's matches never appear.
5. Expire the session and confirm refresh/retry happens at most once.

Production notes

• Call board.me.recommendedJobs.list. Do not invent a client-side ranker or call board.client.fetch('/me/recommended-jobs') when the namespace exists.
• Private match reads must bypass shared caches.
• Do not render scores or "why this job" copy from fields the API does not return.

See the Me reference for the account namespace.