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?
-
There is no dedicated access only for this use. A Super Admin should generate an API key and then share it with external parties (developers, IT team).