Creates a candidate at the specified job. Required scope: w_candidates. Accessible with all token types.

This endpoint creates candidates in a specific job. 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 a specific jobs. To create candidates in the account's talent pool use the POST /talent_pool/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:

keytypedescription
name (required)stringThis field is optional if firstname and lastname are provided
firstname (required)stringThe candidate's first name, It's optional if name is provided
lastname (required)stringThe candidate's last name, it's optional if name is provided
email (required)stringThe candidate's email
headlinestringOne line description as provided by the candidate or you
summarystringThe profile summary provided by the candidate
addressstringThe candidate's address
phonestringThe candidate's phone number
cover_letterstringThe candidate's cover letter
education_entriesarrayExplained below
experience_entriesarrayExplained below
answersarrayExplained below
skillsstring (list)The candidate's skills.
tagsarrayA list of the candidate's tags
disqualifedbooleanIf true, it will mark the candidate as diqualified
disqualification_reasonstringRequired only when EOCC is enabled for your account
disqualified_atstringIn ISO 8601 format (YYYY-MM-DD). If you leave this field empty, we will use the current timestamp
social_profilesarrayExplained below
domainstringThe source of the candidate
recruiter_keystringExplained 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"
      }
    ],

    "answers": [
      {
        "question_key": "2128d717",
        "body": "Planning"
      },
      {
        "question_key": "3399e6cd",
        "choices": ["1e477229"]
      }
    ],

    "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

keytypedescription
resume_urlstringa 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

keytypedescription
namestringthe candidate’s resume name
datastringthe 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:

keytypedescription
school (required)stringThe candidate's school
degreestringThe candidate's degree
field_of_studystringThe candidate's field of study
start_datestringIn ISO 8601 format (YYYY-MM-DD)
end_datestringIn 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:

keytypedescription
title (required)stringThe candidate's title
summarystringA summary of the candidate's experience
companystringThe candidate's company
industrystringThe candidate's working industry
start_datestringIn ISO 8601 format (YYYY-MM-DD)
end_datestringIn ISO 8601 format (YYYY-MM-DD)
currentbooleanTrue if candidate still works there

How can I post the candidate's answers?

Each workable position can have a list of associated questions that can be retrieved from the /jobs/:shortcode/questions endpoint. For each question, an answer can be provided by adding the answers list in the posted data. For each question, add to the answers list the following attributes based on question’s type.

Free text questions

keytypedescription
question_key (required)stringThe question key
body (required)stringThe candidate's response

Short text questions

keytypedescription
question_key (required)stringThe question key
body (required)stringThe candidate's response (maximum 128 characters)

Boolean questions

keytypedescription
question_key (required)stringThe question key
checked (required)booleantrue | false

Multiple choice questions

keytypedescription
question_key (required)stringThe question key
choices (required)array[choices_ids]. For single answer questions provide only one selected choice

Dropdown questions

keytypedescription
question_key (required)stringThe question key
choices (required)array[choices_ids]. Provide only one selected choice

Date questions

keytypedescription
question_key (required)stringThe question key
datestringThe date in ISO 8601 format (i.e. "2017-05-22")

Numeric question

keytypedescription
question_key (required)stringThe question key
valuenumberThe value may be an integer or floating point number (use '.' as decimal point separator)

File question

keytypedescription
question_key (required)stringThe question key
file_urlstringa url pointing to the candidate’s answer

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

keytypedescription
namestringThe file name
datastringThe candidate’s answer encoded in base64

You can have a look below:

{
  "answers": [
    {
      "question_key": "dc3e",
      "body": "Sublime Editor"
    },
    {
      "question_key": "2d30",
      "checked": true
    },
    {
      "question_key": "dc3f",
      "choices": ["e2b", "e2d"]
    },
    {
      "question_key": "dc3b",
      "date": "2017-01-28"
    },
    {
      "question_key": "dc3c",
      "number": 21.87
    },
    {
      "question_key": "dc3d",
      "file": {
        "name": "answer.pdf",
        "data": "SGVsbG8h....SbGh"
      }
    }
  ]
}

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:

keytypedescription
type (required)stringOne 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
usernamestringThe candidate's username
url (required)stringThe 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
Authentication
Header
URL
Click Try It! to start a request and see the response here!