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": "jj_botha@fakemail.com",
    "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": "jj_botha@fakemail.com",
    "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":"john.doe@samplemail.com",
      "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":"john.doe@samplemail.com",
      "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":"john.doe@samplemail.com",
      ....
      "disqualified":true
      ....
   }
}