Careers spaces

The content model

A role is a page in a CAREERS space. Its sections (summary, responsibilities, requirements, nice-to-have, benefits, process) are what a candidate reads; its declared fields are what a candidate filters on and what Google Jobs indexes.

Roles and pages

Not every page in a careers space is a role. "How we hire" or "Working here" is a page. Set metadata.kind with PATCH …/pages/{id}/metadata ({"kind": "page"}), or use Kind of page in the editor's details rail.

A page with no kind is a role, so nothing you already have changes. Any other value is refused with a 422. The kinds are listed under pageKinds at GET /space-types/CAREERS.

Closing a role

closes (a date) closes the role from the following day, counted in UTC. A closed role stays readable at its address and says that it has closed. It also changes in five ways:

• It is removed from the board and from every feed.

• It no longer has an apply form, and the apply endpoint answers 410 gone for it.

• It is marked noindex.

• It is removed from the sitemap.

• Its JobPosting markup is removed.

Country

country (a code like GB, or a country name) becomes addressCountry on an on-site or hybrid role's jobLocation. We never parse it out of the free-text location.

A role in several places lists them in location separated by semicolons (London; Berlin). The board prints "London · Berlin", the location filter offers each city, and the JobPosting gets one Place per city. Give country once for all of them (US), or once per place in the same order (GB; DE).

Pay transparency

payNote is a sentence shown under the salary on the role — what the band covers and how an offer is placed in it, which New York, Colorado, California and the EU pay-transparency rules ask for.

Employment type

The full set, as declared — Full time, Part time, Contract, Temporary, Internship, Volunteer, Per diem, Other. (An older version of this guide listed only the first four; the other four have always worked.) Each maps to a valid Google employmentType, so nothing is guessed from prose.

Where the work happens

remote is On-site / Hybrid / Remote, and it alone decides what the markup claims:

A hybrid role is a place you go some of the time, so it is not marked TELECOMMUTE — that value means 100% remote, and a role marked with it is indexed as a job anybody anywhere can do.

Put a remoteness word in location ("Remote (EU)", "Anywhere") and we claim no place at all rather than assert it as a city, which is what gets a listing rejected.

Who may apply from

Google wants an applicant-location requirement on a fully remote role, and only you know the answer, so it is a field: applicantLocations, countries comma-separated ("Germany, Austria"). Leave it blank and the property is omitted — we never claim "Worldwide", which is not a country.

Salary

salary is a structured band and its keys are exactly four:

{ "min": 80000, "max": 100000, "currency": "EUR", "period": "year" }

period is one of hour, day, week, month, year, and it becomes unitText in the markup. Any other key in the object is refused with 422 naming the shape — a band posted with unit instead of period used to be accepted and then published with no period on it at all.

compensation is the free-text band readers see in prose; it is the fallback for the markup when there is no structured band.

Import roles from your ATS

If your roles already live in Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Personio, Recruitee or Teamtailor, connect the board instead of retyping them. For every provider but Teamtailor we read the same public job board your candidates see, with no API key (Teamtailor needs one), and make one role page per posting. Apply on every imported role goes back to the posting in your ATS, so candidates land in the pipeline you already work.

# Connect (and say who the hourly sync publishes as: you)
PUT    /orgs/{org}/spaces/{space}/careers/ats
  { "provider": "lever", "board": "acme", "syncEnabled": true }

# Read the board now — 202 once the board answered; pages are written in the background
POST   /orgs/{org}/spaces/{space}/careers/ats/sync

# How the last pass went: lastRunAt, lastStatus, lastCounts, lastError
GET    /orgs/{org}/spaces/{space}/careers/ats

# Disconnect — imported roles stay as ordinary pages and stop updating
DELETE /orgs/{org}/spaces/{space}/careers/ats

board is the name in your board's address: the acme in boards.greenhouse.io/acme, jobs.lever.co/acme or jobs.ashbyhq.com/acme. In the studio it is Settings → Import from an ATS.

What a sync does, per posting:

• New — a published role page. Team, location(s), employment type, where the work happens, the salary band and Apply URL are filled from the posting; the Reference ID too when the ATS publishes a requisition id.

• Changed — the page's text and those fields are rewritten and republished. The ATS is the source of truth for what it publishes, so edit imported roles there.

• Gone from the board — the role is closed (its closes date set to yesterday), not deleted: the address still answers, with "closed", and the role leaves the board, the sitemap and Google Jobs.

• Back on the board — reopened.

• Deleted here — left alone. Deleting an imported role is how you keep it off your site; the sync will not bring it back.

Pages you write yourself ("How we hire") are never touched. Images, video and embeds in a posting's description are dropped — a reader page loads nothing from another company's servers. With syncEnabled the board is re-read every hour; changing the provider or board starts over (the old roles stay, unsynced).

Applications

# Public: a candidate applies
POST /public/orgs/{org}/spaces/{space}/careers/apply
  { "pageId": "…", "name": "…", "email": "…", "coverLetter": "…", "links": "…" }

# Admin: the inbox
GET   /orgs/{org}/spaces/{space}/careers/applications?status=reviewing
PATCH /orgs/{org}/spaces/{space}/careers/applications/{id}  { "status": "interviewing" }

Who is told

Every application sends two emails, both on your own mail provider:

• the candidate gets "We received your application for …" (the Application received email template). Turn it off with confirmation: false;

• the hiring team gets New application — at notifyEmails, else your support address, else nobody (the inbox is still the record).

PATCH /orgs/{org}/spaces/{space}/careers/form
  { "notifyEmails": ["hiring@acme.com"], "confirmation": true }

Both are in the apply form's settings in the studio.

The pipeline stages

The stages are yours. A space that never sets them has these six:

Change them in the studio (Settings → Hiring pipeline) or over the API:

GET /orgs/{org}/spaces/{space}/careers/pipeline
PUT /orgs/{org}/spaces/{space}/careers/pipeline
  { "stages": [
      { "key": "new", "label": "Applied" },
      { "key": "screen", "label": "Phone screen" },
      { "key": "take-home", "label": "Take-home task" },
      { "key": "onsite", "label": "Onsite" },
      { "key": "hired", "label": "Offer accepted", "kind": "hired" },
      { "key": "rejected", "label": "Not this time", "kind": "rejected" } ],
    "ratingScale": "stars",
    "moveTo": { "reviewing": "screen", "interviewing": "onsite", "offer": "onsite" } }

• The list is in order. A new application lands in the first stage, which must be open. At least one stage must be hired or rejected.

• The key is what an application stores; the label is what people read. Renaming a stage keeps its key, so nothing moves. status on an application and ?status= on the inbox take a key; anything this space does not have is refused with a 422 that lists the keys it does.

• The kind is what the platform acts on. The retention sweep keeps every application in a hired stage, whatever you call it.

• Removing a stage that holds applications needs moveTo — where they go. They move in the same write, so no candidate is ever in a stage nobody can see. Without it the write is refused, naming the stage and how many.

Notes and ratings

Each application has a private notes thread and one rating per reviewer. Notes are never mailed and never in a webhook — a reply is what the candidate reads, a note is what the team thinks. Only a note's author can delete it.

GET    /orgs/{org}/spaces/{space}/careers/applications/{id}/notes
POST   /orgs/{org}/spaces/{space}/careers/applications/{id}/notes   { "body": "…" }
DELETE /orgs/{org}/spaces/{space}/careers/applications/{id}/notes/{noteId}
GET    /orgs/{org}/spaces/{space}/careers/applications/{id}/ratings
PUT    /orgs/{org}/spaces/{space}/careers/applications/{id}/rating  { "score": 4 }

A score is 1–5; null withdraws yours. With ratingScale: "thumbs" the studio shows thumbs up (stored as 5) and down (1), so switching scale loses nothing. Every inbox row carries rating: { average, count, mine } and notes (how many).

The inbox has a List and a Board view — a column per stage; drag a card or use its stage menu. Export CSV (GET …/careers/applications.csv) adds stage_name, rating, ratings and notes (a count — the notes' text stays in the product).

What readers see

• The open roles at /jobs/{org}/{space} (or your own address), with location and employment type on each. Four arrangements (the space's preset): list, departments (grouped by team, with a count beside each), table (a column each for team, location and type) and cards. "12 open roles" sits over the list (frontDoor.showCounts).

• Once the board has 8 open roles, a search box and a filter bar (team, location, where the work happens, employment type, level). Every search and filter is an address you can share: ?q=design&f_remote=Remote. Set theme.careers.list.filtersFrom to change the threshold (0 = always). The filters sit over the list; theme.careers.list.filterPlacement moves them to a column on the left (rail-left, the hosted-board look) or right (rail-right), or into one line of menus (dropdowns). On a phone a rail becomes the bar over the list.

• Your own words for the board's fixed phrases: frontDoor.emptyText (no open roles), frontDoor.rowCta (the row's "Learn more", with theme.careers.list.rowAction: "text") and frontDoor.allTeamsLabel.

• The rest of the board's look — layout, columns, density, dividers, hover, facts as chips, page size — is theme.careers.list; see Theming.

• An ItemList of the open roles on the board itself, for search engines.

• A role at its own address, with an apply form — or a link to applyUrl. Under its title: its facts as chips, an Apply now button and copy link / share (frontDoor.showShare); an Apply bar stays at the bottom of the screen until the reader reaches the form. Three layouts, the space's piece layout (PUT …/preset {"piecePreset": "…"}): single (the form under the role), split (a sticky column with the facts and Apply) and tabs (Overview / Application). Under the form: your equal-opportunity statement and accommodations contact (frontDoor.eeoStatement, frontDoor.accommodations — written once for the space) and "More roles on <team>". Every piece is a theme key (theme.careers.role, facts, item); see Theming.

• A social card per role: "We're hiring", the title, team, place, type and pay.

• JobPosting structured data built from the fields above, on open roles only. datePosted is the day the role was first published, so editing a role does not make it look new again. directApply is true when candidates apply through the form on the page. identifier is the page id. The hiring organization includes your logo and social profiles when you have set them.

Job alerts and feeds

Beside the board's title, a "Get job alerts" control offers every way to follow the board (frontDoor.subscribeStyle, unset button):

• The talent community — a candidate leaves their email (double opt-in) and gets one mail each time a role opens. On a team's own address (?team=Design) the sign-up is for that team's roles only. A role is announced once, the first time it is published as an open role: edits, republishing, and closing and reopening send nothing more, and pages beside the roles, closed roles and roles hidden from the board are never announced. Roles that were already live before job alerts existed are not announced. The mail is the careers.role-opened email template, counted against your plan's email quota. Turn it off with frontDoor.showSubscribe: false (the subscribe route then answers 404).

• The roles as RSS, Atom and JSON Feed — rss.xml, atom.xml and feed.json beside the board (/careers/rss.xml on your own address), newest role first, dated from each role's first publish. ?tag=<team> narrows any of them to one team. Turn them off with frontDoor.showRss: false.

A front page can also carry the sign-up as a band of its own: a spaceBand with band: "subscribe".

Google for Jobs: instant updates

Google lists a new role when it next crawls your board, which can take days, and keeps listing a closed one until it notices. With your own Google service account connected, a role is announced the moment it is published or edited (URL_UPDATED) and withdrawn the moment it closes, becomes a plain page, is unpublished, made private or deleted (URL_DELETED). A role that closes by its closes date is withdrawn by a daily sweep, once. A renamed role retires its old address.

1. In Google Cloud, create a service account, enable the Web Search Indexing API, and download a JSON key.

2. In Search Console, add the service account's address as an Owner of the site your board is served on (your own domain, or ours).

3. In the studio, open Settings → Google indexing, paste the key, and press Test connection. Send all roles now announces every published role (up to 200, Google's default daily quota).

PUT  /orgs/{orgId}/google-indexing                         {"serviceAccount": "<key JSON>", "enabled": true}
GET  /orgs/{orgId}/spaces/{spaceId}/careers/indexing       the key's account + what Google was told per role
POST /orgs/{orgId}/spaces/{spaceId}/careers/indexing/test
POST /orgs/{orgId}/spaces/{spaceId}/careers/indexing/submit

The key belongs to the organization (org.manage_integrations) and is stored encrypted; nothing ever returns it. Without one, nothing is sent.

Front page

A careers space's front page is a composed document. Until you edit it, it is generated: the intro band, then the roles band. A careers feed sorts by latest and filters by section (a department); its cards can show title, location, employment and department — "We're hiring" on another space's front page is one spaceFeed pointed here.

More fields on a role

A role with no date of its own is dated from its first publish, and that date is used in the "Posted" line, the feeds and the markup.

Internal-only roles

A role with internal: true is for the people already in your organization. Only your organization's members can read it, apply to it and see it on the board. With internalGroups, only members of those groups can, including readers who sign in through the space's reader sign-in with one of those groups in their token. Everyone else gets the same 404 an absent page gets, on the role page and on its apply form and apply call alike, so nobody can confirm that the role exists. An internal role is never in a feed, the job-board XML, the widget, the sitemap, search or the JobPosting markup. Pages that show it are never cached for other readers.

How the board and roles look

All of this is theme.careers, set with the space theme (PATCH /orgs/{orgId}/spaces/{spaceId}/theme). A misspelt key is a 422 that names its path. The layering is: the look's patch, then your space theme, then a role's own customization.

Looks are patches

theme.careers.look picks a starting point. A look is a patch of independent keys over the default layer, so every key works under every look and your own keys always win.

Because each look is just keys, you can combine parts of different looks. Some examples:

{ "careers": { "look": "board", "list": { "layout": "cards", "columns": 2 } } }

Board's team grouping and filter rail, with the roles drawn as cards.

{ "careers": { "look": "minimal", "list": { "featuredFirst": true, "posted": "date" },
               "role": { "layout": "tabs", "tabs": { "style": "segmented" } } } }

Minimal's hairline list, plus featured roles first and posted dates, with the role split into Overview and Application tabs.

{ "careers": { "look": "bold", "role": { "layout": "single", "stickyApplyOn": "all" } } }

Bold's tiles on the board, with the role in one column and the Apply bar on every screen.

The board: theme.careers.list

On top of the keys described above (layout, columns, density, divider, hover, chips, rowAction, filtersFrom, filterPlacement, pageSize):

The board publishes an ItemList of its open roles.

Team pages

Every named collection in the space is a team, with its own page at /jobs/{org}/{space}/c/{team} (/careers/c/{team} on your own address). The page shows the collection's name and description over its open roles, drawn by the same board with every theme.careers.list key.

A role: theme.careers.role, item, facts

item.rail.items is limited to what a role page has a slot for: facts, cta, actions, date, back, share, subscribe, toc, people (the hiringManager field) and tags. The space's benefits (frontDoor.benefits, one per line) are shown under every role, beside the equal-opportunity statement.

The apply form's look: theme.careers.apply

One role's own look

A role can override theme.careers (and theme.docs) for itself:

PATCH /orgs/{org}/spaces/{space}/pages/{page}/metadata
  { "theme": { "careers": { "role": { "layout": "split" }, "apply": { "width": "narrow" } } } }

Another type's namespace is refused with a 422 that names it (customization.theme.forum) and the namespaces a role can take. null clears a key. In the studio this is Page look & sharing in the role's details.

The front page's careers bands

Besides intro and roles, a careers front page can place teams (team cards with their open counts), locations, featured and benefits. Each draws nothing without data. With general applications on (below), a "Don't see the right role?" band sits under the board.

New frontDoor settings: showJobFeed (on: the job-board XML feeds) and benefits (what every role comes with, one per line).

The apply form, in depth

All of these are in PATCH /orgs/{org}/spaces/{space}/careers/form, and in the studio's Apply form section.

The built-in labels speak in one voice and follow the reader's language. A candidate's answers are kept as a draft in their own browser, per role, so an accidental reload loses nothing. The self-identification answers, the consent tick and attached files are never kept in that draft.

Screening questions

{ "screening": {
    "visa_country": { "showIf": { "field": "needs_visa", "equals": "yes" } },
    "right_to_work": { "knockout": { "answers": ["no"], "action": "reject" } },
    "years": { "knockout": { "answers": ["0-1"], "action": "flag" } } } }

• showIf asks a question only when an earlier one was answered equals (a choice's value, or yes for a ticked checkbox).

• knockout acts on an answer in answers: reject files the application straight into the pipeline's rejected stage, and flag marks it for a reviewer. It is judged on the server, and the answers that knock out are never sent to the candidate's browser.

Up to 40 rules.

Hiring tools

These are in PUT /orgs/{org}/spaces/{space}/careers/pipeline beside the stages, and in the studio's Hiring pipeline section.

# Move many at once, and/or send each a template
POST /orgs/{org}/spaces/{space}/careers/applications/bulk
  { "ids": ["…", "…"], "status": "rejected", "template": "not-this-time" }

# The hiring report: funnel per stage, sources (referral, campaign, referring site), time to hire, per role
GET  /orgs/{org}/spaces/{space}/careers/report

The report is also the studio's Hiring report panel. A link to a role or the board with ?ref=<code> records <code> as the candidate's referral source.

Offers and the candidate's status page

PUT  /orgs/{org}/spaces/{space}/careers/applications/{id}/offer
  { "title": "Senior Designer", "compensation": "€90,000", "startDate": "2027-01-04", "letter": "…" }
POST /orgs/{org}/spaces/{space}/careers/applications/{id}/offer/approve
POST /orgs/{org}/spaces/{space}/careers/applications/{id}/offer/send
POST /orgs/{org}/spaces/{space}/careers/applications/{id}/offer/withdraw

An offer is drafted, then approved by a member other than its author (the author's own approval is refused with a 403), then sent. Sending it mails the candidate a link to their status page, /jobs/{org}/{space}/applications/{token}, where they read the letter and accept or decline. Before any offer, the status page tells them where their application stands in plain words (received, in-review, closed or hired). It never shows your internal stage names. POST …/applications/{id}/status-link issues a fresh link and retires the old one.

Two webhooks follow the pipeline: application.stage_changed and application.offer_answered.

Channels

The job-board feeds

• /jobs/{org}/{space}/jobs.xml (/careers/jobs.xml on your own address): the roles in Indeed's job-feed XML, also read by Glassdoor and ZipRecruiter.

• /jobs/{org}/{space}/linkedin.xml: the same roles in LinkedIn's Job Wrapping XML.

Both list only the board's open, public roles, and both are on by default (frontDoor.showJobFeed: false turns them off). Give the address to the job site. Nothing is pushed.

The job widget

<script src="https://acme.com/careers/widget.js" data-team="Design"></script>

The script writes one frame after its own tag: the board with ?embed=1, narrowed by data-team and any data-f-<field> filters, and sized to its content. Nothing third-party loads. theme.careers.embed controls what the smaller box shows:

Apply with Indeed

With an Indeed Apply token and secret saved, every role draws Indeed's button, so a candidate can apply with their Indeed profile. Indeed posts the application back to us, signed with your secret. The application goes through the same door as the form's, so screening, duplicates, the pipeline, mail and webhooks all apply, and an attached CV (up to 5 MB) is kept. A post-back without a valid signature is refused.

More ATS boards

Beyond Greenhouse, Lever and Ashby, the import reads Workable, SmartRecruiters, Personio and Recruitee without a key. For those four, board is your subdomain: the acme in acme.recruitee.com. Teamtailor has no public feed, so it needs your Teamtailor API key:

PUT /orgs/{org}/spaces/{space}/careers/ats
  { "provider": "teamtailor", "board": "acme", "apiKey": "<key>", "syncEnabled": true }

The key is stored encrypted and never returned (hasApiKey says one is held). Leaving out apiKey keeps the stored key, and "" clears it. Sync passes fire careers.ats.* webhooks. Moving from another tool is covered in Importers.

Outlets

Theme components and extensions can add markup in these slots on the careers surface:

In the studio

A careers space's studio has these sections: Apply form (questions, the question bank, screening, the form's words and translations, the hiring team per role, CV autofill, general applications, Apply with Indeed), Import from an ATS, Google indexing, Hiring pipeline (stages, email templates, blind review, scorecard, scheduling links), Hiring report, Applications (list and board, bulk move and reply, offers) and Design (every theme.careers key).

What you need to set up

Published. https://forumulate.com/guides/careers-spaces, in the guides space's "Building your site" collection. Re-import after editing — the page is not generated from this file.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a CLI command or MCP tool exists too, the last column names it. Operation names link to the API reference.

Careers

Careers Ats

Careers Hiring

Careers Indexing

Esign

Google Indexing

Public Careers

Public Careers Channels

Public Careers Status

Public Contact