NAV
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://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://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.

Libraries

Greenhouse offers libraries to assist development with our Job Board API.

Jobs

List jobs

{
  "jobs": [
    {
      "id":127817,
      "internal_job_id":144381,
      "title":"Bad Cop",
      "updated_at":"2016-01-14T10:55:28-05:00",
      "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":"Bad Cop",
      "updated_at":"2016-01-14T10:55:28-05:00",
      "location":{
        "name":"NYC"
      },
      "absolute_url":"https://boards.greenhouse.io/vaulttec/jobs/127817",
      "metadata":null,
      "content":"&lt;p&gt;The Rule Enforcement team is dedicated to keeping all employees in line. &amp;nbsp;Rule enforcers use&amp;nbsp;various tactics such as physical intimidation, awkward pauses, and dramatic coffee sips in order to make sure everyone does what they&#39;re told.",
      "departments":[
        {
          "id":13583,
          "name":"Department of Departments",
          "parent_id":null,
          "child_ids":[
            13585
          ]
        },
        {
          "id":13585,
          "name":"Rule Enforcement",
          "parent_id":13583,
          "child_ids":[
          ]
        }
      ],
      "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.

HTTP Request

GET https://boards-api.greenhouse.io/v1/boards/{board_token}/jobs

URL Parameters

ParameterDescription
board_tokenJob Board URL token

Optional Querystring Parameters

ParameterDescription
contentIf set to true, include the description, department and office of each job post.

Retrieve a job

{
  "id":44444,
  "title":"Product Engineer",
  "updated_at":"2013-07-02T19:39:23Z",
  "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 entitites.&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"
    }
  ]
}

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,
        "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

ParameterDescription
board_tokenJob Board URL token
job_idID of the job to retrieve

Querystring Parameters

ParameterDescription
questionsIf 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)

Questions / Location Questions / Compliance

Possible field types:

TypeHow to represent
input_fileRepresent with an input of type file
input_textRepresent with an input of type text
input_hiddenRepresent with an input of type hidden
textareaRepresent with a textarea
multi_value_single_selectCan be represented as either a set of radio buttons or a select
multi_value_multi_selectCan 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

For organizations using Greenhouse Inclusion, the response may contain demographic questions. Each question contains an array of answer options that may be rendered as checkboxes or a multi-select. The candidate may select zero, one, or more answer options per question. If an answer option is selected that has free_form set to true, the candidate must be allowed to type a free-form response. The free-form response is optional.

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

ParameterDescription
board_tokenJob Board URL token

Querystring Parameters

ParameterRequiredTypeDescription
render_asNostringThis parameter defines how to represent the list of offices. The default value is ‘list’.

Allowed render_as values:

ValueDescription
list(Default). The offices are returned as a list of objects and they include parent_id and child_ids.
treeThe 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

ParameterDescription
board_tokenJob Board URL token
office_idID of the office to retrieve

Querystring Parameters

ParameterRequiredTypeDescription
render_asNostringThis parameter defines how to represent the list of offices. The default value is 'list’.

Allowed render_as values:

ValueDescription
list(Default).
treeThe 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

ParameterDescription
board_tokenJob Board URL token

Querystring Parameters

ParameterRequiredTypeDescription
render_asNostringThis parameter defines how to represent the list of departments. The default value is ‘list’.

Allowed render_as values:

ValueDescription
list(Default). The departments are returned as a list of objects and they include parent_id and child_ids.
treeThe 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

ParameterDescription
board_tokenJob Board URL token
department_idID of the department to retrieve

Querystring Parameters

ParameterRequiredTypeDescription
render_asNostringThis parameter defines how to represent the list of departments. The default value is 'list’.

Allowed render_as values:

ValueDescription
list(Default).
treeThe children departments are returned as a tree.

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

ParameterDescription
board_tokenJob Board URL token

Querystring Parameters

ParameterRequiredTypeDescription
termNostringReturns any degrees containing this string in their name.
pageNostringA 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

ParameterDescription
board_tokenJob Board URL token

Querystring Parameters

ParameterRequiredTypeDescription
termNostringReturns any disciplines containing this string in their name.
pageNostringA 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

ParameterDescription
board_tokenJob Board URL token

Querystring Parameters

ParameterRequiredTypeDescription
termNostringReturns any schools containing this string in their name.
pageNostringA 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

ParameterDescription
board_tokenJob 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/>
  <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" \
  "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"
          }
        ]
      }
    ]
  }' \
  "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}

ParameterDescription
board_tokenJob Board URL token. If you’re submitting an application for a job post on an internal job board, use "internal".
idJob post ID. Both internal and external job posts are allowed.

Request Headers

ParameterDescription
AuthorizationThis header should include a basic authorization with a Base64 encoded API key
Content-TypeRequired if the request contains an attachment

Request Parameters

ParameterDescription
mapped_url_tokenIf present, the gh_src URL parameter, which is used to indicate the referral source of this application.
first_nameApplicant’s first name
last_nameApplicant’s last name
emailApplicant’s email address
phoneApplicant’s phone number
locationApplicant’s street address
latitudeApplicant’s home latitude. This is a hidden field and should not be exposed directly to the applicant.
longitudeApplicant’s home longitude. This is a hidden field and should not be exposed directly to the applicant.
resumePlease see below for details.
cover_letterPlease see below for details.
educationsAn 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.
employmentsAn 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_answersAn 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.

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

MethodContent-TypeRequired FieldsExample
Direct uploadmultipart/form-data“resume”“resume”: “@/Users/UserName/Documents/resume.pdf” (this example is specific to cURL)
Direct uploadapplication/json“resume_content”, “resume_content_filename”“resume_content”: “SGVsbG8sIHdvcmxkIQo=”, “resume_content_filename”: “resume.pdf”
Path to file on external servermultipart/form-data or application/json“resume_url”, “resume_url_filename”“resume_url”: “https://example.com/resume.pdf”, “resume_url_filename”: “resume.pdf”
Plaintext file contentsmultipart/form-data or application/json“resume_text”“resume_text”: “This is my awesome resume!”


Cover Letter Attachments

MethodContent-TypeRequired FieldsExample
Direct uploadmultipart/form-data“cover_letter”“cover_letter”: “@/Users/UserName/Documents/coverletter.pdf” (this example is specific to cURL)
Direct uploadapplication/json“cover_letter_content”, “cover_letter_content_filename”“cover_letter_content”: “SGVsbG8sIHdvcmxkIQo=”, “cover_letter_content_filename”: “coverletter.pdf”
Path to file on external servermultipart/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 contentsmultipart/form-data or application/json“cover_letter_text”“cover_letter_text”: “This is my awesome cover letter!”


Custom Question Attachments

MethodContent-TypeRequired FieldsExample
Direct uploadmultipart/form-data“question_12345”“question_12345”: “@/Users/UserName/Documents/attachment.pdf” (this example is specific to cURL)
Direct uploadapplication/json“question_12345_content”, “question_12345_content_filename”“question_12345_content”: “SGVsbG8sIHdvcmxkIQo=”, “question_12345_content_filename”: “attachment.pdf”
Path to file on external servermultipart/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: