Introduction
With our Job Board API, you will have easy access to a simple JSON representation of your company's offices, departments, and published jobs. Since we give you access to the raw data, you can build careers pages with a unique look and feel, construct department-level pages, and more!
We support JSONP callbacks, and have a POST method which can be used to build your own online job application form.
JSONP
<script
type="text/javascript"
src="https://boards-api.greenhouse.io/v1/example/method/url?callback=">
</script>
To call a method via JSONP (http://en.wikipedia.org/wiki/JSONP), insert the script tag below into your HTML document with an appropriate method URL and provide your own method name in the "callback" querystring parameter. NOTE: The callback name may only contain numbers, letters, underscore, and period.
Authentication
Only the application submission endpoint
(POST https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs/{id}
) requires Basic Auth. The Job Board API Key must be Base64 encoded before it can be used to post applications.
Read more.
Jobs
List jobs
{
"jobs": [
{
"id":127817,
"internal_job_id":144381,
"title":"Vault Designer",
"updated_at":"2016-01-14T10:55:28-05:00",
"requisition_id": "50",
"location":{
"name":"NYC"
},
"absolute_url":"https://boards.greenhouse.io/vaulttec/jobs/127817",
"metadata":null
}
],
"meta": {
"total": 1
}
}
When
?content=true
:
{
"jobs": [
{
"id":127817,
"internal_job_id":144381,
"title":"Vault Designer",
"updated_at":"2016-01-14T10:55:28-05:00",
"requisition_id": "50",
"location":{
"name":"NYC"
},
"absolute_url":"https://boards.greenhouse.io/vaulttec/jobs/127817",
"metadata":null,
"content":"This is the job description. &lt;p&gt;Any HTML included through the hosted job application editor will be automatically converted into corresponding HTML entitites.&lt;/p&gt;",
"departments":[
{
"id":13583,
"name":"Department of Departments",
"parent_id":null,
"child_ids":[
13585
]
}
],
"offices":[
{
"id":8304,
"name":"East Coast",
"location":"United States",
"parent_id":null,
"child_ids":[
8787
]
},
{
"id":8787,
"name":"New York City",
"location":"New York, NY, United States",
"parent_id":8304,
"child_ids":[
]
}
]
}
],
"meta": {
"total": 1
}
}
Returns the list of all job posts. The id
field contains the unique identifier for the job post, while internal_job_id
contains the unique identifier for the job itself. Any job custom fields you have selected to be exposed in the job board API will be shown in the metadata
attribute.
Prospect posts include a null value for internal_job_id
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Optional Querystring Parameters
Parameter | Description |
---|---|
content | If set to true , include the full post description, department, and office of each job post. |
Retrieve a job
{
"id":44444,
"title":"Product Engineer",
"updated_at":"2013-07-02T19:39:23Z",
"requisition_id": "50",
"location":{
"name":"San Francisco, CA"
},
"content":"This is the job description. &lt;p&gt;Any HTML included through the hosted job application editor will be automatically converted into corresponding HTML entitites.&lt;/p&gt;",
"absolute_url":"http://your.co/careers?gh_jid=444444",
"internal_job_id":55555,
"location_questions": [
{
"label": "Location",
"fields": [
{
"name": "location",
"type": "input_text",
"values": []
}
],
"required": true
},
{
"label": "Latitude",
"fields": [
{
"name": "latitude",
"type": "input_hidden",
"values": []
}
],
"required": true
},
{
"label": "Longitude",
"fields": [
{
"name": "longitude",
"type": "input_hidden",
"values": []
}
],
"required": true
},
],
"questions":[
{
"required":true,
"label":"First Name",
"fields":[
{
"name":"first_name",
"type":"input_text"
}
]
},
{
"required":true,
"label":"Resume",
"fields":[
{
"name":"resume",
"type":"input_file"
},
{
"name":"resume_text",
"type":"textarea"
}
]
},
{
"required":false,
"label":"Do you like apples?",
"fields":[
{
"name":"question_2222",
"type":"multi_value_single_select",
"values":[
{
"value":0,
"label":"No"
},
{
"value":1,
"label":"Yes"
}
]
}
]
}
],
"metadata":[
{
"id":12345,
"name":"Field Name",
"value_type":"text",
"value":"Some value"
}
],
"data_compliance": [
{
"type": "gdpr",
"requires_consent": true,
// To be deprecated. Use if your organization doesn't have single-purpose consent configured, otherwise use separate values for processing and retention
"requires_processing_consent": true,
"requires_retention_consent": true,
"retention_period": 12345
}
],
"pay_input_ranges": [
{
"min_cents":5000000,
"max_cents":7500000,
"currency_type":"USD",
"title":"NYC Salary Range",
"blurb":"In order to provide transparency..."
}
]
}
When demographic questions are enabled:
{
"id": 44444,
"title": "Product Engineer",
...
"demographic_questions": {
"header": "Diversity and Inclusion at Acme Corp.",
"description": "<p>Acme Corp. is dedicated to...</p>",
"questions": [
{
"id": 1,
"label": "Favorite Color",
"required": false,
"type":"multi_value_multi_select",
"answer_options": [
{
"id": 100,
"label": "Red",
"free_form": false
},
{
"id": 101,
"label": "Green",
"free_form": false
},
{
"id": 102,
"label": "Blue",
"free_form": false
},
{
"id": 102,
"label": "Prefer to Type My Own",
"free_form": true
}
]
}
]
}
}
Returns a job post. Setting the questions querystring parameter to
"true"
will include the list of job application fields; these fields
can be used to dynamically construct your own job application form.
Any job custom fields you have selected to be exposed in the job board API will be shown in the metadata
attribute.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs/{job_id}
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
job_id | ID of the job to retrieve |
Querystring Parameters
Parameter | Description |
---|---|
*questions | If set to true , include additional fields in the response:- questions : An array of custom questions defined for this job post- location_questions : An array of questions used to capture the applicant's location (included only if the job post has the location configured as "optional" or "required")- compliance : An array of questions used by government contractors to capture applicant information to comply with EEOC regulations (included only if the job post has EEOC questions enabled)- demographic_questions : An object containing demographic questions and related information (included only if your organization has Greenhouse Inclusion, and the job post has demographic questions enabled) |
*pay_transparency | If set to true , include an array of pay_input_ranges with the pay range information defined for this job post. |
Questions / Location Questions / Compliance
Possible field types:
Type | How to represent |
---|---|
input_file | Represent with an input of type file |
input_text | Represent with an input of type text |
input_hidden | Represent with an input of type hidden |
textarea | Represent with a textarea |
multi_value_single_select | Can be represented as either a set of radio buttons or a select |
multi_value_multi_select | Can be represented as either a set of checkboxes or a multi-select |
Please note that it is possible for multiple fields to be aggregated beneath a single question. The "Resume" field is a prime example, with both an input_file and textarea type accepted. If marked as required, then we expect at least one of these fields to contain a valid value when your form is submitted to the application submission endpoint.
Demographic Questions
Type | How to represent |
---|---|
multi_value_single_select | Can be represented as either a set of radio buttons or a select |
multi_value_multi_select | Can be represented as either a set of checkboxes or a multi-select |
For organizations using Greenhouse Inclusion, the response may contain demographic questions. Each question contains an array of answer options that may be rendered based on the question 'type' defined in the table above. The candidate must select an answer option for questions with required
set to true
. If an answer option is selected that has free_form
set to true
, the candidate must be allowed to type a free-form response. This free-form response is only required if no other answer options have been selected by the candidate.
Data Compliance
For organizations with GDPR rules configured and operating with a legal basis of explicit consent, the response may contain data_compliance objects. These objects will include whether a response is required and the data retention period in days as configured by the appropriate rule.
Board-level Introductions and Conclusions
For organizations with Default Descriptions authored on the Job Board, the content
field will include the Board-level Introduction, Post-level Description, and Board-level Conclusion as a single concatenated string.
Offices
List offices
With
render_as=list
(default)
{
"offices":[
{
"id":10201,
"name":"West Coast",
"departments":[
],
"child_ids":[
11111
]
},
{
"id":11111,
"name":"San Francisco",
"departments":[
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"parent_id":null,
"child_ids":[
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[
],
"parent_id":null,
"child_ids":[
]
},
],
"parent_id":10201,
"child_ids":[
]
},
]
}
With
render_as=tree
{
"offices":[
{
"id":10201,
"name":"West Coast",
"departments":[
],
"children":[
{
"id":11111,
"name":"San Francisco",
"departments":[
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"children":[
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[
],
"children":[
]
},
]
"children":[
]
},
]
},
]
}
Returns a list of all of your organization's departments and jobs, grouped by office.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/offices
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
render_as | No | string | This parameter defines how to represent the list of offices. The default value is 'list'. |
Allowed render_as
values:
Value | Description |
---|---|
list | (Default). The offices are returned as a list of objects and they include parent_id and child_ids . |
tree | The offices are returned as a list of trees with children . |
Retrieve an office
With
render_as=list
(default)
{
"id":11111,
"name":"San Francisco",
"departments":[
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[]
}
],
"parent_id":10201,
"child_ids":[
]
}
With
render_as=tree
{
"id":11111,
"name":"San Francisco",
"departments":[
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[]
}
],
"children":[
]
}
Returns a list of your organization's departments and jobs for the given office_id
.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/offices/{office_id}
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
office_id | ID of the office to retrieve |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
render_as | No | string | This parameter defines how to represent the list of offices. The default value is 'list'. |
Allowed render_as
values:
Value | Description |
---|---|
list | (Default). |
tree | The children offices are returned as a tree. |
Departments
List departments
With
render_as=list
(default)
{
"departments":[
{
"id":77777,
"name":"R & D",
"jobs":[
],
"parent_id":null,
"child_ids":[
33333
]
},
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"parent_id":77777,
"child_ids":[
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[
],
"parent_id":null,
"child_ids":[
]
},
]
}
With
render_as=tree
{
"departments":[
{
"id":77777,
"name":"R & D",
"jobs":[
],
"children":[
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"children":[
]
},
]
},
{
"id":22222,
"name":"Account Management",
"jobs":[
],
"children":[
]
},
]
}
Returns a list of your organization's departments and jobs.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/departments
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
render_as | No | string | This parameter defines how to represent the list of departments. The default value is 'list'. |
Allowed render_as
values:
Value | Description |
---|---|
list | (Default). The departments are returned as a list of objects and they include parent_id and child_ids . |
tree | The departments are returned as a list of trees with children . |
Retrieve a department
With
render_as=list
(default)
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"parent_id":null,
"child_ids":[
77777
]
}
With
render_as=tree
{
"id":33333,
"name":"Engineering",
"jobs":[
{
"id":44444,
"title":"Product Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Mobile Engineer - iOS",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
],
"children":[
{
"id":77777,
"name":"Mobile Development",
"jobs":[
],
"children":[
]
}
]
}
Returns a list of jobs for a given department_id
.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/departments/{department_id}
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
department_id | ID of the department to retrieve |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
render_as | No | string | This parameter defines how to represent the list of departments. The default value is 'list'. |
Allowed render_as
values:
Value | Description |
---|---|
list | (Default). |
tree | The children departments are returned as a tree. |
Prospect Post Sections
List sections
{
"sections":[
{
"id":14128,
"name":"Don't see a job you like?",
"jobs":[
{
"id":44444,
"title":"Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Product Manager",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
]
},
{
"id":85764,
"name":"General Application",
"jobs":[
{
"id":888888,
"title":"Prospect",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=888888"
}
]
}
]
}
Returns a list of your organization’s sections and prospect posts. Prospect posts can be listed under a specific department or section. To view all prospect posts, list jobs and filter results by null internal_job_id
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/sections
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Retrieve a section
{
"id":14128,
"name":"Don't see a job you like?",
"jobs":[
{
"id":44444,
"title":"Engineer",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=444444"
},
{
"id":55555,
"title":"Product Manager",
"location":{
"name":"San Francisco, CA"
},
"updated_at":"2013-07-02T19:39:23Z",
"absolute_url":"http://your.co/careers?gh_jid=55555"
}
]
}
Returns a list of prospect posts for a given section_id
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/sections/{section_id}
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
section_id | ID of the section to retrieve |
Educations
This is a list of endpoints which can be used to populate Education data for candidate applications. Instructions for posting applications that include Education information can be found under Applications.
List Degrees
{
"items": [
{
"id": 5494452,
"text": "High School"
},
{
"id": 5494478,
"text": "Associate's Degree"
},
{
"id": 5494516,
"text": "Bachelor's Degree"
},
{
"id": 5494551,
"text": "Master's Degree"
},
{
"id": 5494580,
"text": "Master of Business Administration (M.B.A.)"
},
{
"id": 5494607,
"text": "Juris Doctor (J.D.)"
},
{
"id": 5494638,
"text": "Doctor of Medicine (M.D.)"
},
{
"id": 5494662,
"text": "Doctor of Philosophy (Ph.D.)"
},
{
"id": 5494689,
"text": "Engineer's Degree"
},
{
"id": 5494710,
"text": "Other"
}
],
"meta": {
"total_count": 10,
"per_page": 100
}
}
Returns a list of all of your organization's degrees.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/education/degrees
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
term | No | string | Returns any degrees containing this string in their name. |
page | No | string | A cursor for use in pagination. Returns the n-th chunk of objects (100 per page). |
List Disciplines
{
"items": [
{
"id": 5494865,
"text": "Accounting"
},
{
"id": 5494892,
"text": "African Studies"
},
{
"id": 5494917,
"text": "Agriculture"
},
{
"id": 5494940,
"text": "Anthropology"
},
{
"id": 5494964,
"text": "Applied Health Services"
},
{
"id": 5495009,
"text": "Architecture"
},
{
"id": 5495033,
"text": "Art"
},
{
"id": 5495051,
"text": "Asian Studies"
},
{
"id": 5495074,
"text": "Biology"
},
{
"id": 5495101,
"text": "Business"
}
],
"meta": {
"total_count": 71,
"per_page": 100
}
}
Returns a list of all of your organization's disciplines.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/education/disciplines
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
term | No | string | Returns any disciplines containing this string in their name. |
page | No | string | A cursor for use in pagination. Returns the n-th chunk of objects (100 per page). |
List Schools
{
"items": [
{
"id": 5417077,
"text": "Abraham Baldwin Agricultural College"
},
{
"id": 5417117,
"text": "Academy of Art University"
},
{
"id": 5417156,
"text": "Acadia University"
},
{
"id": 5417194,
"text": "Adams State University"
},
{
"id": 5417217,
"text": "Adelphi University"
},
{
"id": 5417245,
"text": "Adrian College"
},
{
"id": 5417295,
"text": "Adventist University of Health Sciences"
},
{
"id": 5417331,
"text": "Agnes Scott College"
},
{
"id": 5417366,
"text": "AIB College of Business"
},
{
"id": 5417384,
"text": "Alaska Pacific University"
}
],
"meta": {
"total_count": 2464,
"per_page": 100
}
}
Returns a list of all of your organization's schools.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}/education/schools
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Querystring Parameters
Parameter | Required | Type | Description |
---|---|---|---|
term | No | string | Returns any schools containing this string in their name. |
page | No | string | A cursor for use in pagination. Returns the n-th chunk of objects (100 per page). |
Job Boards
Retrieve job board
{
"name": "Your Organization",
"content": "<p>...</p>"
}
Returns your organization's name and job board content.
HTTP Request
GET https://boards-api.greenhouse.io/v1/boards/{board_token}
URL Parameters
Parameter | Description |
---|---|
board_token | Job Board URL token |
Applications
Submit an application
This endpoint can take a multipart form-data POST. You should use this if you need to upload a resume or cover letter.
<!--
EXAMPLE FORM BELOW (simplified):
Please keep in mind that the HTTP Basic Auth API token is a secret key. Any form posts should be proxied by your own servers. Any direct post to the /applications POST method would reveal your secret key to anybody that views source--which would be a very bad thing.
-->
<form method="POST" action="!!REQUEST MUST BE PROXIED ON YOUR SERVERS!!" enctype='multipart/form-data'>
<!-- represents the ID of the job post -->
<input type="hidden" name="id" value="55555" />
<!-- place the value of the gh_src URL parameter in the field below -->
<input type="hidden" name="mapped_url_token" value="token12345" />
<label>First Name <input type="text" name="first_name" /></label><br/>
<label>Last Name <input type="text" name="last_name" /></label><br/>
<label>Email <input type="text" name="email" /></label><br/>
<label>Phone <input type="text" name="phone" /></label><br/>
<label>Resume <input type="file" name="resume" /></label><br/>
<label>Cover Letter <input type="file" name="cover_letter" /></label><br/>
<label>LinkedIn Profile <input type="text" name="question_5555" /></label><br/>
<label>Some dropdown
<select name="question_3333">
<option></option>
<option value="1">Yes</option>
<option value="0">No</option>
</select>
</label><br/>
<label>Multi select with checkboxes<br/>
<label><input type="checkbox" name="question_2222[]" value="2" /> Red</label><br/>
<label><input type="checkbox" name="question_2222[]" value="5" /> Orange</label>
</label><br/>
<label>
<input type="checkbox" name="data_compliance[gdpr_consent_given]" value="1" />
<!-- `gdpr_consent_given` to be deprecated. Use if your organization doesn't have single-purpose consent configured, otherwise use separate checkboxes for processing and retention -->
<input type="checkbox" name="data_compliance[gdpr_processing_consent_given]" value="1" />
<input type="checkbox" name="data_compliance[gdpr_retention_consent_given]" value="1" />
{{ORGANIZATION}} has my consent to collect, store, and process my data for the purpose
of considering me for employment.
</label>
<input type="submit" />
</form>
cURL equivalent:
curl -X POST \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" \
-F "first_name=Sammy" \
-F "last_name=McSamson" \
-F "email=sammy@example.com" \
-F "phone=3337778888" \
-F "location=110 5th Ave New York, NY, 10011" \
-F "latitude=40.7376671" \
-F "longitude=-73.9929196" \
-F "resume=@/path/to/resume/ADA084551.pdf" \
-F "cover_letter=@/path/to/coverletter/blah.pdf" \
-F "educations[][school_name_id]=5417077" \
-F "educations[][degree_id]=5494452"\
-F "educations[][discipline_id]=5494865" \
-F "educations[][start_date][month]=8" \
-F "educations[][start_date][year]=2012" \
-F "educations[][end_date][month]=5" \
-F "educations[][end_date][year]=2016" \
-F "employments[][company_name]=Business Co" \
-F "employments[][title]=Sales Manager" \
-F "employments[][start_date][month]=1" \
-F "employments[][start_date][year]=2016" \
-F "employments[][end_date][month]=2" \
-F "employments[][end_date][year]=2018" \
-F "employments[][current]=false"
-F "mapped_url_token=token12345" \
-F "question_12349_url=http://dropbox.com/dl/attachment.pdf" \
-F "question_12349_url_filename=attachment.pdf" \
-F "question_12350_content=SGVsbG8sIHdvcmxkIQo=" \
-F "question_12350_content_filename=something_else.txt" \
-F "demographic_answers[][question_id]=87" \
-F "demographic_answers[][answer_options][][answer_option_id]=194" \
-F "demographic_answers[][question_id]=88" \
-F "demographic_answers[][answer_options][][answer_option_id]=212" \
-F "demographic_answers[][answer_options][][text]=Free-form Answer" \
-F "data_compliance[gdpr_consent_given]=true" \ # `gdpr_consent_given` to be deprecated. Use if your organization doesn't have single-purpose consent configured, otherwise use separate values for processing and retention
-F "data_compliance[gdpr_processing_consent_given]=true" \
-F "data_compliance[gdpr_retention_consent_given]=true" \
"https://boards-api.greenhouse.io/v1/boards/very_awesome_inc/jobs/127817"
or, you can POST a JSON encoded body (with
Content-Type: application/json
):
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic MGQwMzFkODIyN2VhZmE2MWRjMzc1YTZjMmUwNjdlMjQ6" \
-d '{
"first_name": "Sammy",
"last_name": "McSamson",
"email": "sammy@example.com",
"phone": "3337778888",
"location": "110 5th Ave New York, NY, 10011",
"latitude": "40.7376671",
"longitude": "-73.9929196",
"resume_text": "I have many years of experience as an expert basket weaver...",
"cover_letter_text": "I have a very particular set of skills, skills I have acquired over a very long career. Skills that make me...",
"gender": 2,
"race": 4,
"veteran_status": 3,
"disability_status": 3,
"question_12345": "Here is some short text for the first question",
"question_12346": 1,
"question_12347": 5869311,
"question_12348": [5869319,5869317],
"question_12349_url": "http://dropbox.com/dl/attachment.pdf",
"question_12349_url_filename": "attachment.pdf",
"question_12350_content": "SGVsbG8sIHdvcmxkIQo=",
"question_12350_content_filename": "something_else.txt",
"educations": [
{
"school_name_id" : "1403524",
"degree_id": "1403534",
"discipline_id": "1403605",
"start_date": { "month": "1", "year": "1989"},
"end_date": { "month": "2", "year": "1990"}
},
{
"school_name_id" : "1401063",
"degree_id": "1403525",
"discipline_id": "1403608",
"start_date": { "month": "1", "year": "2011"},
"end_date": { "month": "2", "year": "2012"}
}
],
"employments": [
{
"company_name": "Business Co.",
"title": "Sales Manager",
"start_date": {
"month": "1",
"year": "2016"
},
"end_date": {
"month": "2",
"year": "2018"
},
"current": "false"
}
],
"mapped_url_token":"token12345",
"demographic_answers":[
{
"question_id": 87,
"answer_options": [
{
"answer_option_id": 194
}
]
},
{
"question_id": 88,
"answer_options": [
{
"answer_option_id": 212,
"text": "Free-form Answer"
}
]
}
]
},
"data_compliance": {
"gdpr_consent_given": true, // To be deprecated. Use if your organization doesn't have single-purpose consent configured, otherwise use separate values for processing and retention
"gdpr_processing_consent_given": true
"gdpr_retention_consent_given": true
}' \
"https://boards-api.greenhouse.io/v1/boards/very_awesome_inc/jobs/127817"
Use this endpoint to submit a new application. This endpoint accepts a multipart form POST representing a job application. Application forms are job-specific and will be constructed via the "questions" array available via the Job method. Please see the Job method documentation for instructions on submitting location information through the API.
Note that when submitting an application through this method, Greenhouse will not confirm the inclusion of required fields. Validation for required fields must be done on the client side, as Greenhouse will not reject applications that are missing required fields.
HTTP Request
POST https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs/{id}
Parameter | Description |
---|---|
board_token | Job Board URL token. If you're submitting an application for a job post on an internal job board, use "internal" . |
id | Job post ID. Both internal and external job posts are allowed. |
Request Headers
Parameter | Description |
---|---|
Authorization | This header should include a basic authorization with a Base64 encoded API key |
Content-Type | Required if the request contains an attachment |
Request Parameters
Parameter | Description |
---|---|
*mapped_url_token | If present, the gh_src URL parameter, which is used to indicate the referral source of this application. |
first_name | Applicant's first name |
last_name | Applicant's last name |
Applicant's email address | |
*phone | Applicant's phone number |
*location | Applicant's street address |
*latitude | Applicant's home latitude. This is a hidden field and should not be exposed directly to the applicant. |
*longitude | Applicant's home longitude. This is a hidden field and should not be exposed directly to the applicant. |
*resume | Please see below for details. |
*cover_letter | Please see below for details. |
*educations | An array of education objects. Each education object should have five fields: school_name_id , degree_id , discipline_id , start_date , and end_date . You can get the school_name_id , degree_id , discipline_id from our List Schools, List Degrees, and List Disciplines endpoints. start_date and end_date will use a hash of month and year. |
*employments | An array of employments objects. Each employment object should have: company_name , title , start_date , and current (must be true or false ). If current is false , must have end_date . start_date and end_date will use a hash of month and year. |
*demographic_answers | An array of demographic answer objects, applicable only if your organization has Greenhouse Inclusion and demographic questions are enabled on the job post. Each object must have a question_id field. The answer_options field is an array of objects, one for each answer_option_id the candidate selected. For answer options which support free-form responses, a text field may also be supplied with the candidate's hand-typed answer. Note that these questions are always optional, so the answer_options array may be empty, null, or omitted if the candidate did not make any selections. |
*data_compliance | An object representing a candidate’s answers to required data compliance questions. This field is dependent on your organization’s privacy and compliance configuration. If your organization doesn’t have single-purpose consent configured, use {"gdpr_consent_given": true} . Otherwise use separate consent values, like {"gdpr_processing_consent_given":true} or {gdpr_retention_consent_given":false.} . |
Submitting Attachments
We support 4 methods of uploading attachments when submitting a candidate application:
- Submit the attachment via direct upload using multipart/form-data.
- Submit the attachment via direct upload using application/json.
- Submit a path to the attachment on an external server.
- Submit the plaintext file contents.
Resume Attachments
Method | Content-Type | Required Fields | Example |
---|---|---|---|
Direct upload | multipart/form-data | "resume" | "resume": "@/Users/UserName/Documents/resume.pdf" (this example is specific to cURL) |
Direct upload | application/json | "resume_content", "resume_content_filename" | "resume_content": "SGVsbG8sIHdvcmxkIQo=", "resume_content_filename": "resume.pdf" |
Path to file on external server | multipart/form-data or application/json | "resume_url", "resume_url_filename" | "resume_url": "https://example.com/resume.pdf", "resume_url_filename": "resume.pdf" |
Plaintext file contents | multipart/form-data or application/json | "resume_text" | "resume_text": "This is my awesome resume!" |
Cover Letter Attachments
Method | Content-Type | Required Fields | Example |
---|---|---|---|
Direct upload | multipart/form-data | "cover_letter" | "cover_letter": "@/Users/UserName/Documents/coverletter.pdf" (this example is specific to cURL) |
Direct upload | application/json | "cover_letter_content", "cover_letter_content_filename" | "cover_letter_content": "SGVsbG8sIHdvcmxkIQo=", "cover_letter_content_filename": "coverletter.pdf" |
Path to file on external server | multipart/form-data or application/json | "cover_letter_url", "cover_letter_url_filename" | "cover_letter_url": "https://example.com/coverletter.pdf", "cover_letter_url_filename": "coverletter.pdf" |
Plaintext file contents | multipart/form-data or application/json | "cover_letter_text" | "cover_letter_text": "This is my awesome cover letter!" |
Custom Question Attachments
Method | Content-Type | Required Fields | Example |
---|---|---|---|
Direct upload | multipart/form-data | "question_12345" | "question_12345": "@/Users/UserName/Documents/attachment.pdf" (this example is specific to cURL) |
Direct upload | application/json | "question_12345_content", "question_12345_content_filename" | "question_12345_content": "SGVsbG8sIHdvcmxkIQo=", "question_12345_content_filename": "attachment.pdf" |
Path to file on external server | multipart/form-data or application/json | "question_12345_url", "question_12345_url_filename" | "question_12345_url": "https://example.com/attachment.pdf", "question_12345_url_filename": "attachment.pdf" |
Collecting Applicant Location
Here is the suggested workflow for populating location
, latitude
and longitude
:
- The applicant begins typing a location in your
location
text box. - As the applicant types, your app makes a call to the Google Places Autocomplete API
to retrieve suggested location names (e.g. New York, NY, United States)
and the
place_id
associated with each location (e.g.ChIJOwg_06VPwokRYv534QaPC8g
). - Your app displays the suggested location names to the applicant.
- The applicant selects a suggested location.
- Your app uses the
place_id
from the previous API call to retrieve the latitude and longitude for the selected location using the Google Place Details API. - Your app populates the hidden
latitude
andlongitude
fields with the result of this API call.
Note that all 3 fields must be included. If only location
is sent and latitude
and longitude
are omitted, location
will be ignored entirely.
Validations on POST Requests
Job validations:
- The job must be live and published
- The job board must be live and published
- The job post ID must exist on the job board with the supplied board_token
Field validations:
first_name
,last_name
, andemail
fields are requiredfirst_name
,last_name
, andemail
fields cannot be greater than 255 characters longfirst_name
,last_name
, andphone
fields must not contain a URLemail
field must contain a valid email addresseducations
object must contain validschool_name_id
,degree_id
,discipline_id
,start_date
, andend_date
employments
object must containcompany_name
,title
,start_date
andcurrent
(must betrue
orfalse
). If current=false, must containend_date
start_date
must be beforeend_date
- Field values must match the field type specified on the job post question
Attachments:
- Must be a supported file type (pdf, doc, docx, txt, rtf)
- File size must be > 0 bytes