NAV
Developers Home
json

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. &amp;lt;p&amp;gt;Any HTML included through the hosted job application editor will be automatically converted into corresponding HTML entities.&amp;lt;/p&amp;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. &amp;lt;p&amp;gt;Any HTML included through the hosted job application editor will be automatically converted into corresponding HTML entities.&amp;lt;/p&amp;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
email 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:

  1. Submit the attachment via direct upload using multipart/form-data.
  2. Submit the attachment via direct upload using application/json.
  3. Submit a path to the attachment on an external server.
  4. 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:

  1. The applicant begins typing a location in your location text box.
  2. 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).
  3. Your app displays the suggested location names to the applicant.
  4. The applicant selects a suggested location.
  5. 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.
  6. Your app populates the hidden latitude and longitude 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:

Field validations:

Attachments:

json