Toggle document index

About career sites


An app can host one or more careers sites, e.g. one for graduate recruitment, one for a specific country, etc.

Each site might support:

  • static content and employment branding
  • browsing and searching for jobs
  • viewing details for a specific job
  • on a specific job, displaying buttons for other apps, e.g. apply, share, refer, etc.
  • on the site as a whole, displaying buttons for other apps, e.g. register

A tenant can designate (via some settings app) any site as the "primary", i.e. the main careers site.

Other apps will typically target the primary board when they create links to jobs (or to the site itself), e.g. links in:

  • the main menu of the tenant's web site (i.e. leading to the "careers" section)
  • job alert emails
  • job board postings
  • social media shares

Produce APIs

GET /careerSites/forApp

If your app hosts any board that the tenant may want to mark as the primary board (even in the future), or that other apps may want to generate links to, then it must declare some details about that board to other apps by producing (as non-SoT):

GET /careerSites/forApp



Header/common area

Most sites have some kind of header or common area at the top of the page where the candidate's login status etc. is displayed.

Your site should inject HTML for the general buttons in this area, by consuming:

GET /actions/byCandidate/anonymous/general


or if the candidate is logged in:

GET /actions/byCandidate/me/general

Job details page

Your site likely serves a "job details page" where the candidate can read the job description and click to apply.

LoggedIn filter

If your site supports login (a site that doesn't should only display publicly visible jobs), then this page should sit behind a loggedIn filter (as per conventions).

This way a candidate who was logged in at another app (e.g. UberApply) and then linked to here (e.g. by clicking "View job details"), will be asked to log in, which should happen invisibly, and can then (for example) see internal details for the job if they are an internal.

Fetch details for job

Your site should parse the job's ID from the URL, then use it to consume APIs to get details about the job:

GET /jobs/byID/{job}

GET /jobs/byID/{job}/description

You should display an indicator to show if the job is internal only (to guide internals not to share it).

Your site can render the job using the following logic to handle internal candidates:

- if your site supports login
	- if the candidate is logged in
		- if the candidate is internal
			- if the job is visible internally
				- render the job, with its internal details
			- else
				- render "sorry, this job is not available to internal candidates" message
		- else (public job seeker)
			- if the job is visible externally
				- render the job, with its external details
			- else
				- render "sorry, this job is not visible to external candidates" message
	- else
		- if the job is visible externally
			- render job, with its external details
		- else if the job is visible internally
			- redirect to self with loggedIn param (they may be internal)
			- the loggedIn filter fires and forces login
		- else (not visible at all)
			- render "sorry, this job is no longer available" message

The job's description is in safe markdown and needs to be converted to HTML before display.

Your site should retrieve details of all of the job-related actions (apply button, share button, etc.) and render them:

GET /actions/byCandidate/anonymous/jobs/{job}

or if the candidate is logged in:

GET /actions/byCandidate/me/jobs/{job}

Job search UI

Most sites will display a screen something like this to allow the user to search for jobs:

Location:  |_Balclutha_______|V]
Expertise: |_Sales roles_____|V]
Type:      |_Part-time_______|V]
Keywords:  [______]

To populate a search UI like this, your board can consume the category APIs:

GET /categories

GET /categories/byID/{category}/values Response:

Job list/search results pages

To search/fetch lists of jobs, your site consumes one of:

GET /jobs
POST /jobs/searches


Your site should make sure not to display the wrong jobs to the wrong candidates by restricting for availableInternally or availableExternally depending on whether a candidate is logged in and if so whether they are internal or not. This restriction could be done:

  • by passing "availableInternally = true" to the search
  • by fetching all jobs then filtering out based on the value of availableInternally

Obviously for security reasons it must not be done client-side.

Handling trackers

Normally your site should handle trackers as described in "Trackers".

This means:

  • creating session trackers
  • attaching the session tracker to all links your board emits
  • passing the session tracker to all tracker-aware APIs that your board consumes


  • Keyword spec for search
  • Entry with a job code
  • Displaying the logged in candidate's name.
  • Handling internals - grabbing role from incoming SAML assertion - checking IP address - using login - restricting jobs