API Reference

/talent_pool/candidates

Creates a candidate in the talent pool. Required scope: w_candidates. Accessible with all token types.

There are a few cases where this might come in handy:

  • Custom application form: If you have built an application form on your web site that you’d like to keep using, you can continue to have candidates apply using that form and then use the API to transfer the candidates to your Workable account.
  • Migration of existing candidates: If you have a list of candidates in a spreadsheet or in another system, you can use the API to create all these candidates in Workable.
  • Integration with other systems: Any system that holds people profiles can use the API to transfer these profiles to Workable.
📘

Process as uploaded or applied?

Candidates created through the API can be processed by Workable either as candidates uploaded by a Workable user or as candidates that applied through the application form. The difference is that, in the latter case, they will also receive a ‘thank you for applying’ email.

You can create an 'applied' candidate by including the "sourced": false at the root level. This will ensure that the candidate does receive the “thank you for applying” e-mail.

🚧

Candidates in job or talent pool?

Use this endpoint if you want to create candidates in the account talent pool. To create candidates in specific jobs use the POST /candidates endpoint.

❗️

Important!

A major difference with the previous API versions is that if the sourced flag is not included, candidates are considered as uploaded and not as applied, thus not receiving the "thank you for applying" email.

Here is a list of fields that can be provided:

key

type

description

name (required)

string

This field is optional if firstname and lastname are provided

firstname (required)

string

The candidate's first name, It's optional if name is provided

lastname (required)

string

The candidate's last name, it's optional if name is provided

email (required)

string

The candidate's email

headline

string

One line description as provided by the candidate or you

summary

string

The profile summary provided by the candidate

address

string

The candidate's address

phone

string

The candidate's phone number

cover_letter

string

The candidate's cover letter

education_entries

array

Explained below

experience_entries

array

Explained below

skills

string (list)

The candidate's skills.

tags

array

A list of the candidate's tags

disqualified

boolean

If true, it will mark the candidate as diqualified

disqualification_reason

string

Required only when EOCC is enabled for your account

disqualified_at

string

In ISO 8601 format (YYYY-MM-DD). If you leave this field empty, we will use the current timestamp

social_profiles

array

Explained below

domain

string

The source of the candidate

recruiter_key

string

Explained below

Here is the structure of a complete example:

{
  "sourced": true,
  "candidate": {
    "name": "Jj Botha",
    "firstname": "Jj",
    "lastname": "Botha",
    "headline": "Professional Administration Manager",
    "summary": "A focussed, results-driven team player with many year experience in the field. Working my way up to management level, I have experience of every aspect of this role. I understand the challenges it brings, and have a proven track record of providing solutions.",
    "address": "25772 Gustave Shore, Iowa, USA",
    "phone": "1-859-557-6573",
    "email": "[email protected]",
    "cover_letter": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",

    "education_entries": [
      { "degree": "MBA", "school": "University of Pennsylvania", "field_of_study": null, "start_date": "2008-03-01", "end_date": "2011-03-30" },
      { "degree": "B.S.", "school": "University of Chicago", "field_of_study": "Marketing Communication & Economics", "start_date": "2004-09-01", "end_date": "2007-03-30" }
    ],

    "experience_entries": [
      {
        "title": "Sales Director",
        "summary": null,
        "start_date": "2011-03-01",
        "end_date": "2014-03-30",
        "current": false,
        "company": "Vox Mobile",
        "industry": "Telecommunications"
      }
    ],
    "skills": [ "Travel Planning", "Problem Solving"],
    "social_profiles": [
        {
          "type": "twitter",
          "name": "Twitter",
          "username": "jj_botha",
          "url": "http://www.twitter.com/jj_botha"
        },
        {
          "type": "linkedin",
          "name": "LinkedIn",
          "url": "http://www.linkedin.com/in/jj_botha"
        },
        {
          "type": "googleplus",
          "url": "https://plus.google.com/6908286706342698"
        }
    ]
  }
}

How can I post the candidate’s resume along with the candidate information?

You can post the candidate’s resume in .pdf, .doc, .docx, .rtf format. The API accepts one of the following

key

type

description

resume_url

string

a url pointing to the candidate’s resume

or alternatively you can post the resume encoded in base64 by including a 'resume' key with an object as a value, that has the following keys

key

type

description

name

string

the candidate’s resume name

data

string

the candidate’s resume encoded in base64

Here is an example including a resume encoded in base64 format:

{
  "candidate": {
    "name": "Jj Botha",
    "firstname": "Jj",
    "lastname": "Botha",
    "headline": "Professional Administration Manager",
    "summary": "A focussed, results-driven team player with many year experience in the field. Working my way up to management level, I have experience of every aspect of this role. I understand the challenges it brings, and have a proven track record of providing solutions.",
    "address": "25772 Gustave Shore, Iowa, USA",
    "phone": "1-859-557-6573",
    "email": "[email protected]",
    "resume": {
      "name": "jj_botha.doc",
      "data": "6622116356e175ed0394b0d=="
    }
  }
}

How can I post the candidate’s education?

Candidate’s education is a list of entries. Each entry containing the following fields:

key

type

description

school (required)

string

The candidate's school

degree

string

The candidate's degree

field_of_study

string

The candidate's field of study

start_date

string

In ISO 8601 format (YYYY-MM-DD)

end_date

string

In ISO 8601 format (YYYY-MM-DD)

How can I post the candidate’s experience?

Candidate’s experience is a list of entries. Each entry containing the following fields:

key

type

description

title (required)

string

The candidate's title

summary

string

A summary of the candidate's experience

company

string

The candidate's company

industry

string

The candidate's working industry

start_date

string

In ISO 8601 format (YYYY-MM-DD)

end_date

string

In ISO 8601 format (YYYY-MM-DD)

current

boolean

True if candidate still works there

I am collaborating with recruiters. How can I create a candidate that is sourced by a recruiter?

You can include the recruiter_key in the posted data. Recruiter keys can be retrieved from the jobs/:shortcode/recruiters endpoint.

{
   "candidate":{
      "name":"John Doe",
      "email":"[email protected]",
      "headline":"Superhero developer",
      "summary":"",
      "address":"",
      "phone":"",

      ....

      "recruiter_key":"a34526b"

      ....

}

Can I also provide social profiles for my candidates?

Yes, you can provide social profiles by including the ‘social_profiles’ section:

{
   "candidate":{
      "name":"John Doe",
      "email":"[email protected]",
      "headline":"Superhero developer",
      "summary":"",
      "address":"",
      "phone":"",

      ....

      "social_profiles":[
         {
            "type":"twitter",
            "username":"Workable",
            "url":"https://twitter.com/workable" 
         }
      ]

      ....

}

‘social_profiles’ is a list of social profiles, and you can provide one social profile url for each social network type. Each entry contains the following fields:

key

type

description

type (required)

string

One of the following types: academiaedu, angellist, behance, bitbucket, blogger, crunchbase, dandyid, delicious, deviantart, digg, doyoubuzz, dribble, dribbble, econsultancy, facebook, flavorsme, flickr, fullcontact, getglue, gist, github, goodreads, googleplus, gravatar, hackernews, hiim, klout, lanyrd, linkedin, myspace, ohloh, orkut, pinterest, quora, reddit, scribd, slideshare, stackexchange, stackoverflow, tumblr, twitter, typepad, vk, wordpress, xing

username

string

The candidate's username

url (required)

string

The candidate's URL

How can I post candidates that are already disqualified?

You can do that by including the "disqualified": true along with the candidate’s data. This will ensure that the candidate is marked disqualified in workable. Notice that if EOCC is enabled for your account, you will also need to provide the "disqualification_reason": "some reason" field too.

{
   "candidate":{
      "name":"John Doe",
      "email":"[email protected]",
      ....
      "disqualified":true
      ....
   }
}
Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!