Overview
Gem ATS provides a hosted and embeddable job board by default, but for those organizations who want to be able to create fully customizable job boards, we also provide a Job Board API. This API allows you to generate a list of all live job posts to embed on a suitable web page, which you can then customize to present a unique job board with whatever layout and styling you want. In this article we will explain how to use the Job Board API and explore two of the most common use cases.
Having read this article, you and/or your web developer should be able to understand and use the Job Board API to create a custom job board on your website.
If you’re just looking for the Job Board API documentation you can find that on our API docs site.
Requirements
- Your team must use Gem ATS.
Job board options
There are three options for creating a job board in Gem ATS, and the right option for your organization will depend on your goals and technical requirements.
- Using the job board hosted by Gem: This is the quickest and simplest way to start using your job board, requiring no technical knowledge - just link out to the auto-generated URL from anywhere in your website.
- Embedding a job board into your website: This option requires access to your website’s code in order to drop in code snippets, which allow you to embed a job board into any page on your site.
- Using the Gem Job Board API to create a custom page: This requires familiarity with RESTful APIs, but allows a developer to completely customize how jobs are pulled through to a custom job board page on your website.
You can find more information about the first two options in Gem ATS: Configure your job board in Gem ATS. For this article we’re going to focus exclusively on the third option.
A note on job posts and application forms
It’s important to note that when using the Job board API, job posts and application forms themselves are still hosted by Gem. When a candidate selects a job from your job board, they will be taken to the relevant page for that job hosted on jobs.gem.com.
Note that the View all jobs link - which takes the user from a job post to the Gem job board - can’t be hidden or removed from job posts.
With that in mind, we recommend customizing the appearance of your job posts to match the branding of your job board. To do this, in your Gem Admin settings go to Gem ATS and then Job boards & posts. From there, first select Customize your job board.
Here you can set the colors for the page background, body text and accent (used for icons at the top of the page). Set these colors using either the color pickers provided or the hex codes for the colors you want to use. Select Save & publish when you’re done.
Next, select External job post settings.
Here you can set the following options:
- Show job posting start date: Uncheck this if you would prefer not to show the date each job post was first published.
- Include intro content on job posts: Choose whether or not to include some additional content which will appear between the job title and the job description. Toggling this to ON reveals a text field where you can input whatever you’d like for this content, and format accordingly. This is useful if you want to include standardized, company-specific information on every job post.
- Include outro content on job posts: As above, but displays between the job description and the application form.
Note that both the intro and outro content settings apply by default to all job posts. They can, however, be disabled on individual job posts.
Select Save & publish when you’re done.
The Job board API
The Job board API works by returning a list of all of your currently open job posts. The endpoint to call is:
GET https://api.gem.com/job_board/v0/{vanity_url_path}/job_posts/Where {vanity_url_path} is the job board URL defined in your Admin settings under Gem ATS and then Job boards & posts - make sure you swap in your own URL here.
This returns a range of information pulled from each job in question - specifically from the Job details and Job post.
You can find details of all the fields which are returned in our Job Board API documentation.
In the following sections we will talk you through two of the most common use cases for the Job Board API:
- Use case 1: Standard job board
- Use case 2: Subsidiaries
Prerequisites
For either use case, before making a start you will need:
- Your job board URL.
- At least one live job with a completed job post.
Use case 1: Standard job board
In its simplest form, you can use the list of job posts returned exactly as it is - just ask your web developer/web team to use that list as the basis for how you want to display your job board. You can use data from any of the response fields to populate your job board, and you can also filter the results by any of the returned parameters.
Some of the most common options for sorting include:
- Departments: To match the default hosted and embeddable job board, you can sort by one of the objects from the
departmentsarray such asidorname. - Locations: If you have offices in multiple locations and would prefer to list your jobs by where they’re located, you can sort by one of the objects from the
officesarray - eitherlocationorname. - Job titles: Whatever field you use for the main sorting option, you might then want to sort by job title using the
titlefield (for example, sorting first by Departmentidand then bytitle).
As well as the way you sort the jobs, you could also use the same fields for optional on-page filters so that users are able to narrow down the list to just the departments or locations that they’re interested in.
For an example of both sorting and filtering, check out the Gem careers site and the job board used there.
You can see from this that the list is sorted alphabetically by Department, then alphabetically by Role within each department.
Use case 2: Subsidiaries
If your organization consists of a parent company and one or more subsidiaries, you can use the Departments functionality in Gem ATS as a way of creating separate job boards for each part of the organization (we’ll use the term subsidiary from now on to represent any part of the business, for the sake of simplicity).
The idea is that you create a department to represent each subsidiary, and then a number of sub-departments under each one to represent the actual departments that make up each subsidiary. So conceptually, that would look something like this:
- Department 1: Subsidiary 1
- Sub-department 1: Subsidiary 1 Sales
- Sub-department 2: Subsidiary 1 Engineering
- etc.
- Department 2: Subsidiary 2
- Sub-department 1: Subsidiary 2 Sales
- Sub-department 2: Subsidiary 2 Engineering
- etc.
- etc.
With that done, create one web page for each subsidiary, filtering the API responses by department id or department name to only display jobs with the relevant department.
You can then sort using sub-departments, to determine the order in which individual jobs display on each page.
So that would look something like this:
- Job board 1: Subsidiary 1
- Filter the responses to only show jobs using Department 1
- Job board 2: Subsidiary 2
- Filter the responses to only show jobs using Department 2
- etc.
Department setup
Here’s a quick run-down of the steps required to set up departments and sub-departments as described above.
- Under Gem ATS and then Jobs in Admin settings, create a new department and name it after the core part of your organization.
- Against that department, click on the three dots on the right-hand side and select + Create sub-department.
- Create a new sub-department for each department within that part of the organization.
- Repeat this process for each subsidiary part of the organization.
Job setup
Each time you create a new job, make sure to set the Department field on the Job details page.
With everything set up correctly, the list of departments should clearly show the overall organizational structure of your business. Make sure you select the correct sub-department for each job to reflect its subsidiary and department.
Job board setup
With all that done, for each job board you want to create you should be able to do the following:
- Make a standard Job Board API call.
- Filter the responses to only show jobs using the relevant Department.
- Sort the responses by whichever field is most appropriate (see Use case 1).
- Provide whatever additional filtering options you want (see Use case 1).
FAQs
Can I use a tracking pixel on an API job board?
Yes, you can. Gem can automatically generate unique tracking links for each job, and these are available regardless of how you create your job board. If you want to use either tracking pixels or your own custom tracking links though, you can do so using an API-generated job board.
If you want to add a tracking pixel to your API job board, speak to your developer/web team who should be able to set this up for you.
Have any issues or questions on this topic? Please feel free to contact your dedicated Gem Customer Success Manager directly or our Support team at support@gem.com.