The Careers SDK

The Careers SDK puts your jobs on your own website. Northwilds uses it for northwilds.com/careers/. It has a typed client for the delivery API, React components and Next.js helpers.

1Install and configure

npm install @bifrost-orbit-careers/sdk

Create a public key and set:

CAREERS_API_URL=https://api.bifrostorbit.com/careers/v1CAREERS_PUBLIC_KEY=careers_pk_...CAREERS_WEBHOOK_SECRET=whsec_...

import { createCareersClient } from '@bifrost-orbit-careers/sdk';export const careers = createCareersClient({ apiUrl: process.env.CAREERS_API_URL!, publicKey: process.env.CAREERS_PUBLIC_KEY!, locale: 'en' });

2List your jobs

1import { JobList } from '@bifrost-orbit-careers/sdk/react';23export default async function CareersPage({ searchParams }) {4  const query = await searchParams;5  const [{ items }, filters] = await Promise.all([careers.getJobs(query), careers.getFilters()]);6  return <JobList jobs={items} filters={filters} query={query} href={(job) => `/careers/${job.slug}/`} />;7}

The filters are a plain form, so they stay in the address and work without JavaScript.

3Show a job and take applications

1import { ApplyForm, JobDetail } from '@bifrost-orbit-careers/sdk/react';23export default async function JobPage({ params }) {4  const job = await careers.findJob((await params).slug);5  if (!job) notFound();6  return (7    <JobDetail job={job}>8      <ApplyForm job={job} apiUrl={process.env.CAREERS_API_URL!} publicKey={process.env.CAREERS_PUBLIC_KEY!} organisationName="Northwilds" source="northwilds.com" />9    </JobDetail>10  );11}

JobDetail writes the JobPosting data Google for Jobs reads. ApplyForm builds the job's own form, reads the CV in the browser to fill in name, email and phone, and asks for consent to your privacy notice. It also sends the page's utm_source, utm_medium and utm_campaign and the referring site, so applications are counted per channel; source is used when the address has no utm_source. When the address has ?ref=, from a colleague's referral link, it sends that too, and the application counts as their referral. It counts a view of the job when it shows and an apply start when the candidate first touches the form, for the reports' channels; these counts carry no cookies and nothing about the person. Pass trackView={false} when the form isn't on the job's own page, and call trackJob(…, 'view') there instead. Use jobPostingMetadata(job, { siteName: 'Northwilds' }) from @bifrost-orbit-careers/sdk/next in generateMetadata.

TalentPoolSignup offers people a box to get an email when a new job opens (job alerts). Pass departmentIds to note which departments the form is for, such as on a guides page, so they only hear about jobs there.

4Refresh when jobs change

import { createRevalidateHandler } from '@bifrost-orbit-careers/sdk/next';export const POST = createRevalidateHandler({ secret: process.env.CAREERS_WEBHOOK_SECRET! });

Set the webhook under Settings › Website webhook. A closed job leaves your website within seconds.

5Sitemap and job addresses

createSitemapRoute(careers) lists every live job. Set Job addresses under Career site › Address and website to where your job pages live, such as https://northwilds.com{localePrefix}/careers/{slug}/, so the API, JobPosting data and candidates' emails link to your pages.

6Let candidates follow their applications

CandidatePortal is the candidate portal on your own website: sign-in with an email code, applications with the stage names candidates see, adding documents, withdrawing, the talent pool, downloading their data and asking for a correction or erasure.

1'use client';2import { CandidatePortal } from '@bifrost-orbit-careers/sdk/react';34<CandidatePortal baseUrl={process.env.NEXT_PUBLIC_CAREERS_API_URL!} publicKey={process.env.NEXT_PUBLIC_CAREERS_PUBLIC_KEY!} locale="de" />

Called this way, the browser talks to Careers Orbit directly and keeps the session in the tab's session storage, sent as X-Careers-Session. Add your website to Allowed websites under Career site › Address and website.

To keep the session in an httpOnly cookie of your own instead, forward /portal/* from your server, adding the public key, and pass your own address as baseUrl without publicKey. Northwilds does this at /api/careers/portal/...: on POST/portal/session it takes the token from the answer, keeps it in a cookie and sends it back as X-Careers-Session on later calls.

For other frameworks, createPortalClient({ baseUrl, publicKey }) has the same calls: requestCode, signIn, me, withdraw, addDocument, openOffers, acceptOffer, declineOffer, offerPdf, exportData, askToCorrect, askToErase, stayInTalentPool, leaveTalentPool, stopTexts and signOut.

7Count visits and applications in Insights Orbit

If your organisation uses Insights Orbit and has picked a site for its career pages, getSite() returns insights.site. Add CareersInsights to your careers layout to load Insights' cookieless script with that key, and every application sent through ApplyForm counts as an Applied event:

import { CareersInsights } from '@bifrost-orbit-careers/sdk/react';<CareersInsights site={site} />

If your website already loads Insights, for example through CMS Orbit's CmsInsights, leave CareersInsights out: the Applied event uses the script that is there.

When the trial or plan ends

When your organisation's Careers Orbit trial or plan has ended, the career site is paused and every call throws CareersSubscriptionInactiveError (status 402, code subscription_inactive) straight away. Check with isSubscriptionInactive(error) and show a calm "temporarily unavailable" page with your own name, rather than letting the page fail: a Next.js page that throws during a refresh keeps its last good copy, so it would go on listing jobs that can't be applied for. The sitemap helper keeps its cached copy instead of going empty. Nothing is deleted, and jobs and applications come back as soon as an owner chooses a plan.

PHP, Swift and Kotlin

The same client comes for PHP websites, iOS and macOS apps, and Android apps and JVM servers, with the same calls and the same public key:

• PHP SDK: bifrost-orbit/careers-sdk with Composer
• Swift SDK: CareersOrbit with Swift Package Manager
• Kotlin SDK: com.bifrostorbit:careers-sdk with Gradle or Maven

Styling

Every part takes a class through classNames and carries a data-careers attribute. The components speak English and German. For a CMS Orbit registry, careersComponents holds them as jobList, jobDetail, applyForm, talentPoolSignup and candidatePortal.