An afternoon covers the whole set-up: choose a tier, add your keys, put the cards on your record pages, publish the careers pages, and the first application can arrive. Nothing here needs a developer, and nothing is installed beyond what you choose.

This page is written for the person who owns the portal. It is ordered as the work actually happens: decide the tier, install, provision the pages, fill the data, tune, verify. The section that most often gets skipped is § What matching needs, and skipping it is the single most common reason a working install produces useless rankings.

Before you start#

RequirementWhy
A HubSpot plan that includes custom objectsPostings, applications, interviews and documents are custom objects. Without them the app installs but the job board cannot exist — the dynamic job page is skipped rather than left as an unpublishable draft
Custom-object allowance for your chosen tier4 objects at the default. Most Enterprise portals cap around 10; the full 19-object tier needs a raised allowance agreed with HubSpot first
A CMS-hosted site on the portal, if you want the careers pages provisionedThe seven standard pages are created on your own domain, in your own theme
An active licence for the appEvery route checks it. An inactive licence answers 403 and no amount of retrying helps

The tier decision — make it before installing#

The schema installs in tiers because 19 objects does not fit on a normal portal. Choose the smallest one that covers the process you actually run; upgrading later is additive and never deletes.

TierObjectsChoose it when
minimal2You want the public job board and nothing else. This is what the OAuth callback provisions on its own
lean (default)4Normal. Postings, applications, interviews and documents — a working ATS
standard6You need a separate candidate profile object or structured offers
full19Requisitions, compliance records, scorecards, skill junctions. Requires a raised object allowance and a deliberate decision

Important

The OAuth install deliberately provisions only the minimal tier. A public app must not create a dozen custom objects on a portal because somebody clicked install. Everything above minimal is a separate, deliberate step — the Settings page's Status tab, or the tier-upgrade action. If your postings and applications are missing after install, this is why, and the fix is to upgrade the tier rather than to reinstall.

Upgrades only ever add. Going from lean to standard creates the two new objects and leaves everything else untouched; there is no downgrade, because a downgrade would mean deleting records.

What install provisions#

ProvisionedDetail
Custom objectsPer the tier above, with their properties and association labels
Contact propertiesAn ATS – Candidate Matching property group on the standard Contact object, holding every candidate-side field matching reads
app_setting recordsAll 57 settings — matching, résumé reading, geocoding and travel time — seeded at their defaults, plus app-level settings such as the public base URL
Careers pages7 standard pages, on request — /careers, /careers/jobs, the dynamic job detail page, /careers/apply, /careers/thanks, /careers/application-status and /careers/alerts. All seven embed the same module with a different view
Workflow actions6 actions — set stage, recalculate match, close posting, create interview, read résumé, find best matching job postings — available in the workflow builder immediately, in workflows of any object type (each refuses a record that is not its own kind and says so)
CRM cards5 cards. HubSpot offers them in each object's record-page editor; § Put the cards on your record pages
Sample workflowsTwo, created disabled, so nothing runs until you enable it. A third — Score new applications — is not provisioned and is described in the install result instead: any workflow using one of the app's own actions must be created in the editor, because HubSpot binds it to an app connection no API can set. It is one step and worth the minute — it is what makes every new application arrive already scored

The dynamic job-detail page is bound to the portal's own ats_job_posting object. That binding is per-portal, which is why object type ids are resolved at runtime everywhere and never hardcoded.

The settings page#

Seven tabs, in the app's listing in HubSpot:

TabWhat it is for
StatusInstalled tier, which objects are present, licence state, and the tier upgrade
GeneralApp-level settings — the careers site base URL used to build candidate links and the job-board feed, and the employer name that feed publishes
MatchingThe scoring rules — weights, the must-have gate, and each dimension's own group — plus the dry-run calibrator. ats-matching.md
CV ParsingReading a résumé into the properties the engine scores on: your AI provider and model, the daily cap, and what a parse is allowed to overwrite
GeolocationHow an address becomes coordinates, and how a commute is measured. Two different providers, two different bills
Sample dataLoad or remove a working demo dataset from the page — 5 postings, 3 candidates with applications, interviews and documents
Danger zoneDestructive operations. Read § What an uninstall destroys first
The Status tab of the ATS settings page. "Licence — Licensed": "The licence is what allows the recruiting pages and matching to run on this portal." "Installed tier: lean" — "Which custom objects this portal has. A higher tier adds objects; it never removes them." A checklist: Job Posting, Application, Interview and Candidate Document ticked; Candidate Profile and Offer crossed (they come with the standard tier); App Setting ticked.

The Status tab: what is installed on this portal, at a glance. The two crossed objects are what the next tier would add; below the list, the upgrade says exactly which objects it creates.

Settings are staged and saved as a group — nothing takes effect until Save, and Discard restores what is stored. A provider key is the exception: it saves on its own, encrypted, and is never sent back to the page afterwards.

The three keys, and what each one costs#

Everything that leaves the portal needs a key you own, and none of it runs until you set one. Nothing here is billed by us.

SettingProviderCharged perOff means
CV Parsing → provider + keyYour AI provider (Claude by default)Résumé parsed, bounded by the daily cap you setUploads still attach; nothing reads them, and every surface says so
Geolocation → geocoding keyOpenCageAddress turned into coordinates, once — coordinates are storedNo distance anywhere, and radius matching cannot score
Geolocation → travel keyGoogleCommute looked up, every time a recruiter presses the buttonThe distance line still shows; the commute button does not
The CV Parsing tab of the ATS settings page. A green notice: "A key is stored for this portal — It is encrypted and cannot be shown again. Leave the box empty to keep it — saving never clears a key by accident." The AI API key field shows only dots, with Save key and Remove. AI provider: Claude (Anthropic). Model (optional): claude-sonnet-5. Largest résumé to read (MB): 10. Most résumés to read per day (0 = no limit): 200. An editable extraction prompt. Two switches, both on: "Read uploaded resumes" ("Off by default, and never on merely because a key exists…") and "Read a résumé as soon as it is uploaded" ("The candidate never waits for it: the application is confirmed first and the reading happens after.").

CV Parsing, switched on. The key is shown only as stored; the daily cap (here 200) bounds what reading can cost.

The Sample data tab of the ATS settings page: "A bundled set of postings, candidates and applications, so a fresh portal has something to demonstrate. Removal only touches the records this app created." A tick and "Sample data is installed", then three buttons: Add sample data, Re-check and Remove sample data.

Sample data, loaded. Remove takes away exactly the records the app created and nothing else. Loading takes about half a minute; the page says so while it works and refreshes the status by itself.

Put the cards on your record pages#

The app adds 5 cards. HubSpot lists each one in the record-page editor of the object it belongs to, and on a portal with customised record pages you place them yourself — Settings → Data Management → Objects → (object) → Record Customization → the view → Add card → App cards:

CardObjectWhere it goes
Job Posting Command CentreATS Job PostingMiddle column (a tab works well)
Application WorkspaceATS ApplicationMiddle column
Interview PanelATS InterviewMiddle column
Document InspectorATS Candidate DocumentRight sidebar
Candidate 360ContactRight sidebar

Check every view of the object: a team view (for example one made for a sales team) is a separate layout and does not inherit cards added to the default view. On our demo portal, 2026-11-16, the Interview Panel and the Document Inspector were missing from their default views until they were added this way.

What matching needs#

Read this section even if you are not tuning anything. The engine scores properties, and only properties. It does not infer, it does not open a CV at scoring time, and a field nobody filled is not a low score — it is a dimension that either scores a neutral 50 or drops out of the calculation entirely. Résumé reading matters here precisely because it is the step that turns a CV into properties; without it, an attached CV is invisible to every rule below.

The failure this produces is quiet and specific: every candidate scores roughly the same, in a band around 50, and the ranking looks arbitrary. That is not a broken engine. That is an engine with nothing to compare.

On the job posting#

FieldFeeds
Must-have skills · Nice-to-have skillsThe two skill dimensions, and the must-have gate
Seniority levelSeniority
Remote model · City · CountryLocation
Salary minimum and maximum (the public ones)Salary
Minimum years of experienceExperience
Required education levelEducation
Required languagesLanguages
IndustryIndustry
Match keywordsKeywords, if you have enabled that dimension
Match weight override (JSON)Per-posting weights — see ats-matching.md

A posting that states no requirement for a dimension excludes it. That is deliberate and usually right, but it means a thinly filled posting scores everyone on very little. If rankings need to be comparable across postings, make these fields required in your own process — the app does not enforce it.

On the candidate — the Contact#

Every field lives in the ATS – Candidate Matching property group: seniority level, remote preference, willing to relocate, total years of experience, primary skills, languages, education level, industry, match keywords, salary expectation minimum and maximum, and open to work.

Four ways they get filled, in descending order of how much you should rely on them:

  1. A workflow or an import. The reliable answer. Map whatever you already hold onto these properties.
  2. Résumé reading. With an AI provider key set, an uploaded CV is read and these fields are written from it. This is the only route that fills them for a candidate who applied through the form and exists nowhere else in your data — which is most of them. It never blanks a field the CV does not mention, and never overwrites what a recruiter typed unless you have told it to.
  3. A recruiter, on the Contact record. Fine at low volume, and it outranks a parse by design.
  4. The application form itself. It captures the applicant, not their full profile. On its own it does not populate the matching fields.

Leave résumé reading off and route 2 disappears: an uploaded CV attaches to the candidate and nothing reads it, which is the state that produces the quiet failure above.

Important

ats_open_to_work is what scopes the candidate pool. A posting-to-candidates match run filters to contacts marked open to work, and scores up to 2,000 of them. If nobody is marked, the run falls back to scanning your contact base — which on a large portal means genuine candidates can fall outside the bound and never be scored at all, with only candidatePoolTruncated in the response to say so. Set this property, from the application form's own workflow if nothing else.

Migrating an already-installed portal#

Properties added after a portal was installed do not appear on it by themselves. Run the schema migration:

POST https://api.worksby.design/apps/ats/admin/migrate-schema

It is idempotent and additive — it creates what is missing and touches nothing that exists. Two properties are worth checking for specifically, because their absence is silent:

  • ats_open_to_work — without it the candidate pool is unfiltered, as above.
  • stage_entered_at — without it, time-in-stage reports nothing. There is no error; the number is always empty.

Run this after any upgrade. A portal that has been installed for a while and has never been migrated is the usual explanation for "that feature is documented but I do not have it".

Important

Read the migration's own result, do not just check it returned 200. It reports contactProperties: { created, failed }, and a property that could not be created lands in failed while the call still reports success. Each one silently degrades a matching dimension to "missing data" for every candidate — a wrong ranking rather than an error, which is the hardest kind to notice.

The failure mode worth knowing: HubSpot requires property labels to be unique across the whole object, not just across one app's properties. A label that collides with a standard HubSpot property is rejected, and the app carries on. If failed is non-empty, the fix is on our side — send us the list.

Sample data does not update itself. The seeder reuses records that already exist rather than overwriting them, which is what stops a re-seed duplicating your demo. The consequence: if the shipped sample set gains fields, an already-seeded portal will not pick them up from a re-seed. Remove the sample data and add it again, or ask us to backfill.

Verification#

In order. Each step proves the one before it actually worked, and the last one is observable by a person rather than by a log.

  1. Licence — GET /apps/ats/license-status for the portal answers active.
  2. Objects — the Settings page's Status tab lists the tier and shows every expected object present.
  3. Pages — /careers/jobs loads on the portal's own domain and renders the module rather than an empty page.
  4. A posting appears — create a posting, publish it, and confirm it is on /careers/jobs. If the list is empty, the posting is not both live and active; nothing else filters it.
  5. The job page resolves — open the posting from the list. The detail page is the dynamic page; if it 404s, the dynamic page was skipped at install because the custom object did not exist yet.
  6. An application lands — apply through the form, then find the ats_application record associated to both the Contact and the posting. Submitting the same form twice must produce one record, not two.
  7. The status link works — request a status link for that email, follow it, and see the application with a simplified status.
  8. Matching produces a real ranking — on the Settings page's Matching tab, run the dry-run calibrator against that posting's record id. This is the step that proves the data, not just the plumbing. A spread of scores means the candidate properties are populated; every candidate clustered near 50 means they are not, and § What matching needs is where to go.
  9. The job-board feed resolves — open https://api.worksby.design/apps/ats/jobs.xml?portalId=<portalId> in a browser. A 409 means the careers base URL is not set. Otherwise check the X-Jobs-Included header against the number of live postings, and click one <url> from the document — that link is what a candidate will follow from a job board, and it is the only part no test can prove for you.

When something is wrong#

SymptomUsual causeFix
Careers page is emptyPostings are not live, or not activePublish the posting; check record_status
Job detail page 404sThe dynamic page was skipped at install because the custom object did not existProvision the object, then re-provision the pages
Every route answers 403Licence inactive, or the portal's install record is missingReactivate the licence; reinstall the app if the install record is gone
A route answers 409 naming an objectThat object is not installed at the portal's tierUpgrade the tier from the Status tab
Every candidate scores about the sameCandidate properties are empty§ What matching needs. This is not a matching bug
A candidate you expected is absent from a rankingThey are not marked open to work, or the pool bound was hitCheck candidatePoolTruncated in the response; set ats_open_to_work
A setting saves but changes nothingIt may be one of the 3 that are not wired to the engineThe generated table in ats-matching.md names them
Scores never updateNothing recalculates automaticallyBuild a workflow using the recalculate-match action
Time-in-stage is always emptystage_entered_at was never provisionedRun the schema migration
The job-board feed answers 409The careers site base URL is not setSettings page → General
A board shows your hostname as the employerEmployer Name is unset, so the feed falls back to itSettings page → General
A live posting is missing from the feedIt has no slug, or it is marked noindexCompare X-Jobs-Skipped against the number of live postings
A board shows no salary on a role that has onesalary_visibility is hidden for that posting — the feed honours itChange it on the posting if you intended to publish it
New applications arrive unscoredNo scoring workflow exists yet — it is a manual one-step build, not provisionedWorkflow editor: enrol on application create, add Recalculate match score
A workflow using an ATS action does nothing, with no errorIt was created over the API rather than in the editor. It will enable, report enabled, and never fireRebuild that step in the workflow editor
A match-alert workflow enrolled on Candidate profile ready never enrols anyoneThe property is filled only after a CV is read successfully on an application. CV reading is off, or reading the CV failed, or the portal predates the propertySwitch CV reading on; check the document's parse status; run the schema migration

Security posture#

The shareable summary. A deeper analysis exists and is not published — ask, and we will walk through it.

  • Candidate data stays on your portal. The app stores postings, applications, candidates and documents as CRM records on your own HubSpot. No external database holds them.
  • The public careers routes authenticate the portal, not the caller. That is appropriate for a public careers page: anyone may read live postings and anyone may apply. What is protected is the data — public routes return only the public field set, never another candidate's application.
  • The candidate status link is a signed, expiring token bound to one contact. Requesting one always returns the same acknowledgement, so it cannot be used to discover whether somebody applied.
  • The candidate never sees your internal pipeline. The status portal returns a reduced shape by design — no internal stage name, no rejection reason.
  • The recruiter surface is bound to the individual user, cryptographically. HubSpot signs every call a CRM card makes and puts the caller's portal and user id inside that signature; the backend refuses anything that does not validate, and takes the identity only from the signed values. Recruiter actions are therefore attributable to a real person. Stated in full, with its two limits, in ats-integration.md.
  • Workflow actions are genuine signed HubSpot webhooks, verified per request.

What an uninstall destroys#

Caution

Removing the app archives every ATS record on the portal and deletes the schemas — postings, applications, interviews, documents, and their custom properties and association labels. It discovers what to remove dynamically, so a portal that was upgraded to a higher tier has that tier's objects removed too.

It also archives app_setting, which is where all 57 of your tuned settings live — including your provider keys. They are not backed up anywhere. If you have calibrated the engine, record the values you changed before uninstalling — a fresh install starts from the defaults.

Two things survive, and both matter:

  • Contacts survive. Candidates are Contacts, and Contacts are yours. The ATS property group's values remain on them, so a reinstall finds the candidate data intact.
  • Schema deletion can fail without the uninstall failing. HubSpot refuses to drop a schema while soft-deleted records or workflow references remain. That is reported in the result rather than treated as fatal, so check the result rather than assuming a clean removal. Retrying later usually clears it.

Reinstalling is not a repair tool. For a portal that is behaving oddly, the migration above fixes missing properties, and the tier upgrade fixes missing objects — both without touching data.

Click the image to switch between fit and full size. Esc closes.