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": falseat 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
sourcedflag 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 |
| answers | 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"
}
],
"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
| 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 |
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
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| body (required) | string | The candidate's response |
Short text questions
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| body (required) | string | The candidate's response (maximum 128 characters) |
Boolean questions
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| checked (required) | boolean | true | false |
Multiple choice questions
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| choices (required) | array | [choices_ids]. For single answer questions provide only one selected choice |
Dropdown questions
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| choices (required) | array | [choices_ids]. Provide only one selected choice |
Date questions
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| date | string | The date in ISO 8601 format (i.e. "2017-05-22") |
Numeric question
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| value | number | The value may be an integer or floating point number (use '.' as decimal point separator) |
File question
| key | type | description |
|---|---|---|
| question_key (required) | string | The question key |
| file_url | string | a 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:
| key | type | description |
|---|---|---|
| name | string | The file name |
| data | string | The 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:
| 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
....
}
}