API Reference
API Reference

/candidates/:id

patch https://{subdomain}.workable.com/spi/v3/candidates/

Partially updates a candidate. Required scope: w_candidates. Accessible with all token types.

This can help a user keep the candidate DB in sync with another system.

Here is a list of fields that can be provided:

keytypedescription
firstnamestringThe candidate's first name
lastnamestringThe candidate's last name
emailstringThe 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
texting_consentstringThe candidate's texting_consent. Either forced or declined.
cover_letterstringThe candidate's cover letter
resumeobjectExplained below
imageobjectExplained below
education_entriesarrayExplained below
experience_entriesarrayExplained below
skillsstring (list)The candidate's skills.
tagsarrayA list of the candidate's tags
social_profilesarrayExplained below

❗️

Attention!

For all array keys (education_entries, experience_entries, social_profiles, tags) this works like a PUT request; i.e the end result will match exactly your input. Any pre-existing entries or values that are not included in the request will be deleted. If you provide an empty array as a value, all entries will be deleted. If you don't provide the top level keys, their values will remain as is.

Here is the structure of a complete example:

{
  "candidate": {
    "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",
    "texting_consent": "forced",
    "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.",

    "resume": { "name": "jjBotha.rtf", data: "SGVsbG8h" },
    "image": { "name": "me.jpg", data: "SGVsbG8h" },
    
    "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"
      }
    ],

    "tags": [ "globetrotter", "adventurer" ],
    
    "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 update the candidate’s resume along with the candidate information?

You can update 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

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 update the candidate’s image along with the candidate information?

keytypedescription
image_urlstringa url pointing to the candidate's image
image_sourcestringIf the image is not provided by the candidate (e.g. collected from a social network profile), you can also send the image_source. It can be 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, skype, slideshare, stackexchange, stackoverflow, tumblr, twitter, typepad, vk, wordpress, xing

or alternatively

keytypedescription
image/namestringthe candidate's image name
image/datastringthe candidate's image encoded in base64
image/sourcestringThe source of the candidate's image

How can I update the candidate’s education?

❗️

Attention!

This works like a PUT request; i.e. the end result will match exactly your input. Any pre-existing entries or values that are not included in the request will be deleted.

Candidate’s education is a list of entries. To update an entry you must use the id. Each entry may contain the following fields:

keytypedescription
id (optional)stringThe education id. If it is provided, the corresponding education entry will be updated. If not, a new entry will be created.
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 update the candidate’s experience?

❗️

Important!

This works like a PUT request; i.e. the end result will match exactly your input. Any pre-existing entries or values that are not included in the request will be deleted.

Candidate’s experience is a list of entries. To update an entry you must use the id key. Each entry may contain the following fields:

keytypedescription
id (optional)stringThe experience id. If it is provided the corresponding experience entry will be updated. If not, a new entry will be created.
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

Can I also update the candidate's social profiles?

❗️

Attention!

This works like a PUT request; i.e. the end result will match exactly your input. Any pre-existing entries or values that are not included in the request will be deleted.

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, skype, slideshare, stackexchange, stackoverflow, tumblr, twitter, typepad, vk, wordpress, xing
usernamestringThe candidate's username
url (required)stringThe candidate's URL
Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!