Using the Workable API to create a careers page

The Workable API will give you access to a list of your open jobs and the details for each role. You can add these to your own careers site and keep the visual styling directly in line with your company’s brand guidelines. Whenever you create a new position in Workable, your website will update with the latest job postings.

Read the API documentation to get started

Steps to build a careers page using Workable's API

Note: You will need programming/development experience or someone from your development team to use the API. Workable also offers an option to embed a job widget on your website or to use our careers page site builder. These career page types can be set up with little development experience.

Building a custom careers page using Workable's API involves fetching job listings from your Workable account and displaying them on your website with your preferred design and structure. Workable offers a REST API that allows you to retrieve open positions and job details.

1. Generate an API token

Log into your Workable account as a Super Admin and navigate to Integrations > Apps to generate an API token. This key is required to authenticate your requests.

API tokens can be configured to enable different scopes while making calls. Ensure you enable the r_jobs scope to access your jobs via the related SPI endpoints.

2. Make an API request to fetch job listings

Workable’s API provides a /jobs endpoint that returns a list of all your jobs. The job states can be draft, published, closed (internal or confidential), or archived.

Important: You need to filter the job list to retrieve only the published jobs ("state": "published"), as these are the ones to display on your careers page.

👇 Sample API Request:

GET <https://<subdomain>>.workable.com/spi/v3/jobs
Authorization: Bearer <your_api_key>

👇 Sample API Response:

The result will be in JSON format and will contain details like:

{
"jobs": [
{
"id": "3c47ff",
"title": "Account Executive",
"full_title": "Account Executive - GB/09/AE",
"shortcode": "AE84C38EE2",
"code": "GB/09/AE",
"state": "published",
"department": "Account Executive",
"department_hierarchy": [
{
"id": 346500,
"name": "Commercial"
},
{
"id": 346505,
"name": "Sales"
},
{
"id": 346506,
"name": "Account Executive"
}
],
"url": "https://subdomain.workable.com/jobs/3949357",
"application_url": "https://subdomain.workable.com/jobs/3949357/candidates/new",
"shortlink": "https://apply.workable.com/j/AE84C38EE2",
"location": {
"location_str": "London, United Kingdom",
"country": "United Kingdom",
"country_code": "GB",
"region": null,
"region_code": "England",
"city": "London",
"zip_code": "2142",
"telecommuting": false,
"workplace_type": "on_site"
},
"locations": [
{
"country_code": "GB",
"country_name": "United Kingdom",
"state_code": "England",
"subregion": null,
"zip_code": "2142",
"city": "London",
}
],
"salary": {
"salary_from": 60000,
"salary_to": 80000,
"salary_currency": "gbp"
},
"created_at": "2023-12-25T00:00:00Z"
}

Alternatively, to get the list of your published jobs only, you can try in your terminal the below public endpoints:

curl -L GET 'https://www.workable.com/api/accounts/<account_subdomain>?details=true'
curl -L GET 'https://www.workable.com/api/accounts/<account_subdomain>/locations'
curl -L GET 'https://www.workable.com/api/accounts/<account_subdomain>/departments'

Your account subdomain is the first part of the URL you see when signed in to Workable. The part “?details=true” means you also want to fetch the job descriptions. The last two endpoints will fetch all locations and departments of your published jobs, respectively.

3. Create the frontend to display jobs

Once you have the job listings, the next step is to display them on your careers page. Use HTML, CSS, and JavaScript to build the frontend. Here’s an example of how you could structure the page:

👇 HTML Example:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Careers</title>
<style>
body { font-family: Arial, sans-serif; }
.job-listing { margin-bottom: 20px; }
.job-title { font-size: 18px; font-weight: bold; }
.job-location { color: gray; }
</style>
</head>
<body>
<h1>Join Our Team</h1>
<div id="jobs-container"></div>

<script>
async function fetchJobs() {
const response = await fetch('<https://<subdomain>>.workable.com/spi/v3/jobs', {
headers: { 'Authorization': 'Bearer <your_api_key>' }
});
const data = await response.json();
const jobsContainer = document.getElementById('jobs-container');

data.jobs.forEach(job => {
const jobElement = document.createElement('div');
jobElement.classList.add('job-listing');

jobElement.innerHTML = `
<div class="job-title">${job.title}</div>
<div class="job-location">${job.location}</div>
<a href="${job.url}" target="_blank">View Job</a>
`;

jobsContainer.appendChild(jobElement);
});
}

fetchJobs();
</script>
</body>
</html>

4. Handle job description page (Optional)

If you want to display the detailed job description on a separate page, you can either:

Redirect users to Workable's hosted job pages via the URL property.
Use the /jobs/:shortcode to retrieve detailed job descriptions and show them within your website.

Sample API Request:

The job shortcode can be found at the /jobs endpoint.

GET <https://<subdomain>>.workable.com/spi/v3/jobs/<shortcode>
Authorization: Bearer <your_api_key>

5. Deploy your page

Once you’ve implemented the code, deploy it to your web server or content management system (CMS). You can embed the careers page as part of your company's website. Ensure you handle cases where the API request fails or returns no jobs.

Useful documentation

Workable API Documentation provides detailed endpoints and usage instructions
Comparing careers page options
Troubleshooting API issues

FAQs

Is the filtering option and search bar available through the API?

No. You will get the raw data with the API. You should build everything else related to the display of jobs (search bar, filtering) on your side.

Is there a specific permission/access I can grant my developers?

A Super Admin can generate an API key with relevant scopes and share it with external parties (developers, IT team).

For example, if your website only needs to display a list of jobs and redirect candidates to the Workable application form, the r_jobs scope is enough. If you would like candidates to complete their application directly on your website, you also need to add the w_candidates scope so that you can create candidates in Workable.

Why are some of my jobs missing from the company website?: For these issues, we recommend reaching out to the developers responsible for building your company's website and careers page.