What's new in v3

Version 3 is the latest API provided by Workable.

New features

Version 3 includes some new features that significantly improve the performance of the API. To be more specific latest version provides:

paginated data for jobs and candidates
scroll parameters since_id and max_id
filter parameters created_after and updated_after
reduced verbose candidate json on job candidates collection

Breaking changes

❗️
IMPORTANT UPDATES
The v1 & v2 APIs are now deprecated but will continue to function correctly. We highly recommend you to update to v3 in order to take advantage of the increased performance, improvements and new features.
NOTE: Updating your code to use the new v3 endpoints will require some changes to your code but we have tried to minimize the changes that you'll have to make.

Common changes

The key attributes are renamed to id
Timestamp fields are rendered in ISO 8601 format (e.g. 2015-06-08T00:00:00Z). Timezone is always UTC
Empty string values are now returned as null
Candidates are now considered as 'uploaded' by default. You have to include the sourced: false in order to consider a candidate as applied. More details on this here.

Candidates collection

In order to improve the overall performance of the candidates endpoint the following changes have been made since v2:

Candidates are sorted by the time inserted on system, in ascending order (older candidates come first).
Response contains a limited number of candidates. Number is controlled by the limit parameter (50 for default). More results can be fetched by following the paging/next url.
The candidate json is limited to basic arguments. The following attributes are no longer returned: address, phone, outbound_mailbox, cover_letter, summary, education_entries, exprerience_entries, skills, answers, resume_url, social_profiles, tags. This information can be retrieved by the candidate info endpoint.

The following sample compares the candidate payload of v2 and v3.

{
      "id": "3fc9a811",
      "name": "Mattias Avelin",
      "firstname": "Mattias",
      "lastname": "Avelin",
      "headline": "Software Engineer at Gears of Leo",
      "account": {
        "subdomain": "groove-tech",
        "name": "Groove Tech"
      },
      "job": {
        "shortcode": "GROOV005",
        "title": "Office Manager"
      },
      "stage": "Sourced",
      "disqualified": false,
      "disqualification_reason": null,
      "sourced": true,
      "profile_url": "https://groove-tech.workable.com/backend/jobs/376844767/candidates/1070179135",
      "email": null,
      "domain": null,
      "created_at": "2015-07-09T08:54:12Z",
      "updated_at": "2015-07-09T08:54:16Z"
    }

{
      "key": "3fc9a811",
      "name": "Mattias Avelin",
      "firstname": "Mattias",
      "lastname": "Avelin",
      "headline": "Software Engineer at Gears of Leo",
      "account": {
        "subdomain": "groove-tech",
        "name": "Groove Tech"
      },
      "job": {
        "shortcode": "GROOV005",
        "title": "Office Manager"
      },
      "stage": "Sourced",
      "disqualified": false,
      "sourced": true,
      "profile_url": "http://groove-tech.workable.com/backend/jobs/376844767/candidates/1070179135",
      "address": "Stockholm, Sweden",
      "phone": "",
      "email": "",
      "outbound_mailbox": "[email protected]",
      "domain": "",
      "created_at": "2015-07-09 08:54:12",
      "updated_at": "2015-07-09 08:54:16",
      "cover_letter": "",
      "summary": "Expert knowledge/experience in complex data migration, working with open source solutions (Linux, MySQL, Java, php, Apache, JBoss, TomCat etc.). Experienced in build systems capable of handling high transaction volumes. Experienced MySQL power-user. Worked with clients such as Tele2, Ericsson, Eniro, Bwin Games, SIX and others. Certified MySQL Developer.",
      "education_entries": [],
      "experience_entries": [
        {
          "title": "Software Engineer",
          "summary": "",
          "start_date": "2015-05-01",
          "end_date": "",
          "company": "Gears of Leo",
          "industry": "Gambling & Casinos",
          "current": true
        }
      ],
      "skills": [],
      "answers": [],
      "resume_url": "",
      "social_profiles": [
        {
          "type": "linkedin",
          "url": "https://www.linkedin.com/in/mattiasavelin"
        }
      ],
      "tags": []
    }

Jobs collection

Jobs are sorted by the time inserted on system, in ascending order (older jobs come first).
Response contains a limited number of jobs. Number is controlled by the limit parameter (50 for default). More results can be fetched by following the paging/next url.
The account specific attributes name and description are removed.

The following sample compares the job payload of v2 and v3.

{
  "jobs": [
    {
      "id": "61884e2",
      "title": "Sales Intern",
      "full_title": "Sales Intern - US/3/SI",
      "shortcode": "GROOV003",
      "code": "US/3/SI",
      "state": "draft",
      "department": "Sales",
      "url": "https://groove-tech.workable.com/jobs/102268944",
      "application_url": "https://groove-tech.workable.com/jobs/102268944/candidates/new",
      "shortlink": "https://groove-tech.workable.com/j/GROOV003",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Oregon",
        "region_code": "OR",
        "city": "Portland",
        "zip_code": "97201",
        "telecommuting": false
      },
      "created_at": "2015-07-01T00:00:00Z"
    },
    {
      "id": "1166bf8c",
      "title": "Operations Manager",
      "full_title": "Operations Manager - US/02/CM",
      "shortcode": "GROOV001",
      "code": "US/02/CM",
      "state": "archived",
      "department": "Operations",
      "url": "https://groove-tech.workable.com/jobs/291945146",
      "application_url": "https://groove-tech.workable.com/jobs/291945146/candidates/new",
      "shortlink": "https://groove-tech.workable.com/j/GROOV001",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-05-07T00:00:00Z"
    },
    {
      "id": "167636b1",
      "title": "Office Manager",
      "full_title": "Office Manager - US/4/OM",
      "shortcode": "GROOV005",
      "code": "US/4/OM",
      "state": "published",
      "department": "Administration",
      "url": "https://groove-tech.workable.com/jobs/376844767",
      "application_url": "https://groove-tech.workable.com/jobs/376844767/candidates/new",
      "shortlink": "https://groove-tech.workable.com/j/GROOV005",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-06-06T00:00:00Z"
    },
    {
      "id": "2700d6df",
      "title": "Web Developer",
      "full_title": "Web Developer - US/2/WD",
      "shortcode": "GROOV002",
      "code": "US/2/WD",
      "state": "closed",
      "department": "Engineering",
      "url": "https://groove-tech.workable.com/jobs/654365197",
      "application_url": "https://groove-tech.workable.com/jobs/654365197/candidates/new",
      "shortlink": "https://groove-tech.workable.com/j/GROOV002",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-05-22T00:00:00Z"
    },
    {
      "id": "2b2d288d",
      "title": "Finance Manager",
      "full_title": "Finance Manager - UK/1/FM",
      "shortcode": "GROOV006",
      "code": "UK/1/FM",
      "state": "archived",
      "department": "Finance",
      "url": "https://groove-tech.workable.com/jobs/724378555",
      "application_url": "https://groove-tech.workable.com/jobs/724378555/candidates/new",
      "shortlink": "https://groove-tech.workable.com/j/GROOV006",
      "location": {
        "country": "United Kingdom",
        "country_code": "GB",
        "region": "London, City of",
        "region_code": "LND",
        "city": "London",
        "zip_code": "W1B 5 QA",
        "telecommuting": false
      },
      "created_at": "2015-06-06T00:00:00Z"
    }
  ],
  "paging": {
    "next": "https://www.workable.com/spi/v3/accounts/groove-tech/jobs?limit=5&since_id=34ed8eb6"
  }
}

{
  "name": "Groove Tech",
  "description": "<p>We’ve all spent tons of hours trying to book a trip! Well, our guys finally got tired of going through this frustrating process and passionately decided to do something about it: To change the traveller’s experience. Four years later, we stick to that idea by daily plotting the traveling revolution.</p> <p>Like busy little bees, all 98 of us, customise our user-friendly software and innovative services to match leisure and business travellers needs throughout the entire journey. We create innovative and top notch travel products for a simple reason: You deserve it.</p> <p>Whether it’s about booking tickets or hotels, whatever the budget, us travel lovers are dedicated to deliver you a lifetime experience. How? By empowering you to easily discover, book and have fun at the whole world!</p> <p>We are innovators, idealists and perfectionists. We love raising the bar to delight and amaze our customers and that’s exactly why working with us requires a lot of you. But it’s a lot more than that. We’ll brightly reward you. We’ll develop your career. We’ll keep you excited! In other words we promise being the most exciting place for you to work at.</p> <p>We are growing as crazy and we need you industry experts and passionate individuals to do things that matter and take us off! Come aboard ready to share, learn and grow.</p>",
  "jobs": [
    {
      "key": "2b2d288d",
      "title": "Finance Manager",
      "full_title": "Finance Manager - UK/1/FM",
      "code": "UK/1/FM",
      "shortcode": "GROOV006",
      "state": "archived",
      "department": "Finance",
      "url": "http://groove-tech.workable.com/jobs/724378555",
      "application_url": "http://groove-tech.workable.com/jobs/724378555/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV006",
      "location": {
        "country": "United Kingdom",
        "country_code": "GB",
        "region": "London, City of",
        "region_code": "LND",
        "city": "London",
        "zip_code": "W1B 5 QA",
        "telecommuting": false
      },
      "created_at": "2015-06-06"
    },
    {
      "key": "34ed8eb6",
      "title": "Head of Account Management",
      "full_title": "Head of Account Management - US/4/HAM",
      "code": "US/4/HAM",
      "shortcode": "GROOV004",
      "state": "published",
      "department": "Sales",
      "url": "http://groove-tech.workable.com/jobs/887982564",
      "application_url": "http://groove-tech.workable.com/jobs/887982564/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV004",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "New York",
        "region_code": "NY",
        "city": "New York",
        "zip_code": "10001",
        "telecommuting": false
      },
      "created_at": "2015-06-06"
    },
    {
      "key": "167636b1",
      "title": "Office Manager",
      "full_title": "Office Manager - US/4/OM",
      "code": "US/4/OM",
      "shortcode": "GROOV005",
      "state": "published",
      "department": "Administration",
      "url": "http://groove-tech.workable.com/jobs/376844767",
      "application_url": "http://groove-tech.workable.com/jobs/376844767/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV005",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-06-06"
    },
    {
      "key": "1166bf8c",
      "title": "Operations Manager",
      "full_title": "Operations Manager - US/02/CM",
      "code": "US/02/CM",
      "shortcode": "GROOV001",
      "state": "archived",
      "department": "Operations",
      "url": "http://groove-tech.workable.com/jobs/291945146",
      "application_url": "http://groove-tech.workable.com/jobs/291945146/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV001",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-05-07"
    },
    {
      "key": "61884e2",
      "title": "Sales Intern",
      "full_title": "Sales Intern - US/3/SI",
      "code": "US/3/SI",
      "shortcode": "GROOV003",
      "state": "draft",
      "department": "Sales",
      "url": "http://groove-tech.workable.com/jobs/102268944",
      "application_url": "http://groove-tech.workable.com/jobs/102268944/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV003",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Oregon",
        "region_code": "OR",
        "city": "Portland",
        "zip_code": "97201",
        "telecommuting": false
      },
      "created_at": "2015-07-01"
    },
    {
      "key": "2700d6df",
      "title": "Web Developer",
      "full_title": "Web Developer - US/2/WD",
      "code": "US/2/WD",
      "shortcode": "GROOV002",
      "state": "closed",
      "department": "Engineering",
      "url": "http://groove-tech.workable.com/jobs/654365197",
      "application_url": "http://groove-tech.workable.com/jobs/654365197/candidates/new",
      "shortlink": "http://groove-tech.workable.com/j/GROOV002",
      "location": {
        "country": "United States",
        "country_code": "US",
        "region": "Illinois",
        "region_code": "IL",
        "city": "Chicago",
        "zip_code": "60290",
        "telecommuting": false
      },
      "created_at": "2015-05-22"
    }
  ]
}

New features

Breaking changes

❗️IMPORTANT UPDATES

Common changes

Candidates collection

Jobs collection

❗️
IMPORTANT UPDATES