NAV
Examples

Introduction

Our Greenhouse Onboarding API allows you to query and modify your employee, and query company information.

If you are not using our Onboarding product and would like to know more, please visit our site.

This documentation is open source! Feel free to leave feedback as issues in the GitHub repo or fork it and contribute changes!

GraphQL

Greenhouse Onboarding only supports GraphQL; we do not have a traditional REST API.
We made the decision to use GraphQL because it allows us you to:

Authentication

$ curl https://onboarding-api.greenhouse.io/graphql \
  -X POST \
  -u your_access_key:your_secret_key \
  -d '{"query":"{\n  rateLimit {\n    limit\n  }\n}"}' \
  -H "Content-Type: application/json"

...

> GET /graphql HTTP/1.1
> Host: onboarding-api.greenhouse.io
> Authorization: Basic eW91cl9hY2Nlc3Nfa2V5OnlvdXJfdmFsdWU=

The Greenhouse Onboarding API is secured with HTTP Basic Authentication over HTTPS. Clients are required to supply both a username and password. Credentials can be generated inside of the Greenhouse Onboarding product on the Settings > API Management screen. Only Super Admins can generate or revoke API keys. Use the Access Key field as the username and the Secret Key field as the password.

API Management

Using the Greenhouse Onboarding API provides access to all of your company’s information. There is no way to limit the scope of an API key. Only share your API key with people that you trust. API keys can be revoked at any time on the API Management screen.

Rate Limiting

The Greenhouse Onboarding API imposes limits on the the number of requests a single client can send us, as well as the complexity of these requests. This is done to ensure our servers can always service requests as quickly as possible.

Request Costs

{
  "errors": [
    {
      "message": "Rate limit reached.",
      "limit": 100,
      "remaining": 0,
      "resetAt": "2018-01-01T01:00:00Z"
    }
  ]
}

GraphQL gives clients the ability to specify the exact data to be returned in each request. This means that some requests can query lots of data, while others are much simpler and only return a handful of fields. For this reason, a simple rate-limiting protocol of “X requests per hour” is not a good fit.

Instead, each API key is given a budget of “API points” that can be spent on requests. Each request can have a separate cost. Once the API key has run out of points, all further requests will return an error message stating that requests are now being throttled.

This message indicates the total number of API points this API key has in its budget and when the API points will be restored to the maximum limit.

{
  employee(id: 1) {
    email
  }

  rateLimit {
    cost
    limit
    remaining
  }
}
{
  "data": {
     "employee": {
       "email": "test@example.com"
    },
    "rateLimit": {
      "cost": 1,
      "limit": 100,
      "remaining": 99
    }
  }
}

Clients can ask for this information before their requests have been throttled by querying for the rateLimit object. In general, the more complex a query, the higher its cost. We reserve the right to change the costs for each query, and the budgets for API keys, at any time.

Maximum Depth

The Greenhouse Onboarding API limits the maximum depth of any request to 10.

Pagination

{
  employees(first: 2, after: "NQ==") { # Please fetch the next 2 records, starting after the "NQ==" cursor
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        email
      }
    }
  }
}

# Returns:

{
  "data": {
    "employees": {
      "pageInfo": {
        "endCursor": "MTA=",
        "hasNextPage": true
      },
      "edges": [
        {
          "node": {
            "email": "kima@example.com"
          }
        },
        {
          "node": {
            "email": "omar@example.com"
          }
        }
      ]
    }
  }
}

For performance reasons, some result sets will be limited in size. For example, when requesting employee profile information we limit the number of employees returned in a single query. The API will return a “page” of records along with an object that describes how to get the next page.

We are using the pagination system recommended by the GraphQL documentation. Paginated connections return the following pieces of information:

To fetch the next page of information, pass the endCursor value into the after filter on the connection. To the right you can see an example on how to fetch employees via the employees connection.

When requesting a paginated resource, you will always need to provide a value for either the first or last arguments. You’ll use these arguments to specify the number of records that should be included on a page. If you provide a value larger than our maximum, you will receive the maximum number of records.

As a general rule, we attempt to avoid nested sets of pagination. For example, the list of CustomFieldValue records for each employee will be a simple array instead of another paginated connection.

Errors and Validation

{
  employee(id: 100000000) {
    email
  }
}
{
  "data": {
    "employee": null
  },
  "errors": [
    {
      "message": "Unable to find Employee with id 100000000",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "employee"
      ],
      "errorCode": "NotFound"
    }
  ]
}

Unlike REST APIs, GraphQL will return an HTTP status of 200, even in cases where there are errors. You can see an example of an error message to the right. The data and errors properties are siblings. It’s possible for a request to generate a response that has both data and errors. However, if there is ever an errors key in the response, the request failed (despite the return code of 200).

The message will let you know what’s wrong. The locations property has the line number and column where the error starts. In this example, it’s the 2nd line, 3rd column, which is the start of the word employee. The fields property is a breadcrumb trail of how to get to the problem. Here, the problem can be found on the top-most employee selection.

When we can, we’ll also provide an errorCode key for every entry in the errors list. Here’s a table of current errorCodes:

Error ScenarioError Code
Authentication FailureAuthentication
Validation FailureValidation
Resource Not FoundNotFound
Server ErrorServer
Rate Limit ExceededRateLimit

There are undefined error scenarios in which we’re unable to provide a code. In these cases, refer to the contents of the error list.

Queries

contactRelationships ([String])

The list of valid options for the ‘Contact’ custom field type

countries ([Country])

The list of countries

ArgumentTypeDescriptionRequired
countryCodes[String]

customField (CustomField)

A custom field

ArgumentTypeDescriptionRequired
idID

customFields (CustomFieldConnection)

A collection of custom fields

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
fieldTypes[CustomFieldTypes]
firstIntReturns the first n elements from the list.
ids[ID]
lastIntReturns the last n elements from the list.

department (Department)

A single department

ArgumentTypeDescriptionRequired
idInt

departments (DepartmentConnection)

All departments

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.

employee (Employee)

# Request an employee and limit their customFieldValues to those with specific permanentFieldIds.
# The permanentFieldIds argument can be used when you are interested in only getting a handful of
# customFieldValues for the employee.
{
  employee(id: 20) {
    customFieldValues(permanentFieldIds: ["emergency_contact", "favorite_food"]) {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Request an employee and limit their customFieldValues to those that have been updated after 2018-04-14 1PM UTC
{
  employee(id: 20) {
    customFieldValues(updated: { after: "2018-04-04T13:00:00Z" }) {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Request an employee and limit their customFieldValues to those that have been updated before 2018-04-14 1PM UTC
{
  employee(id: 20) {
    customFieldValues(updated: { before: "2018-04-04T13:00:00Z" }) {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Request an employee and limit their signatureRequests to those that are waiting on a signature or being processed
{
  employee(id: 20) {
    signatureRequests(statuses: [WAITING_FOR_SIGNATURE, BEING_PROCESSED]) {
      counterSigner {
        id
        email
      }
      file {
        file_url
      }
      signatureRequestTemplate {
        publicName
      }
    }
  }
}

An Onboarding employee record

ArgumentTypeDescriptionRequired
idInt

employees (EmployeeConnection)

# Request only those employees that have title "Account Manager". For each employee that fits the criteria,
# return their id and email
{
  employees(first: 25, title: "Account Manager") {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        email
      }
    }
  }
}

# Request only those employees that have a startDate between 2017-03-25 and 2018-03-25.
# These dates are exclusive (e.g. someone who started on 2017-03-25 or 2018-03-25 would not be included.
{
  employees(first: 25, startDate: { after: "2017-03-25", before: "2018-03-25" }) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        email
        startDate
      }
    }
  }
}

# Request only those employees that have a value set for the "favorite_food" Custom Field. For these employees, return
# ALL of their customFieldValues.
{
  employees(first: 25, customFieldValues: [{permanentFieldId: "favorite_food"}]) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

# Request only those employees that have "Hot Dogs" or "Chicken Nuggets" set for their "favorite_food" Custom Field
{
  employees(
    first: 25,
    customFieldValues: [{permanentFieldId: "favorite_food", textValues: ["Hot Dogs", "Chicken Nuggets"]}]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

# Request only those employees that have any value set for their "favorite_food" Custom Field and "Blue" for their
# "favorite_color" Custom Field
{
  employees(
    first: 25,
    customFieldValues: [{permanentFieldId: "favorite_food"}, {permanentFieldId: "favorite_color", textValues: "Blue"}]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

# Request employees that have any value set for "favorite_food" and that value has been updated after "2018-04-13"
{
  employees(first: 25, customFieldValues: [{permanentFieldId: "favorite_food", valueUpdated: {after: "2018-04-13"}}]) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues(permanentFieldIds: ["favorite_food"]) {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

# Request employees that have a date value between "2017-04-13" and "2018-04-13" (exclusive) for the
# "one_year_anniversary" Custom Field
{
  employees(
    first: 25,
    customFieldValues: [{permanentFieldId: "one_year_anniversary", dateValue: {after: "2017-04-13", before: "2018-04-13"}}]
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

# Request employees that have Employee 35 or Employee 40 set as the value for the "mentor" Custom Field
{
  employees(first: 25, customFieldValues: [{permanentFieldId: "mentor", idValues: [35, 40]}]) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        customFieldValues {
          custom_field {
            permanentFieldId
          }
          value
        }
      }
    }
  }
}

A collection of Onboarding employee records

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
customFieldValues[CustomFieldValuesInput]
dateOfBirthDateFilter
departmentIds[Int]
emails[String]
employmentStatuses[EmploymentStatus]
firstIntReturns the first n elements from the list.
hrManagerIds[Int]
lastIntReturns the last n elements from the list.
locationIds[Int]
managerIds[Int]
personalEmails[String]
startDateDateFilter
titles[String]
updatedAtDateTimeFilter
workCountryCodes[String]

location (Location)

A single location

ArgumentTypeDescriptionRequired
idInt

locations (LocationConnection)

All locations

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.

otherCriteria (OtherCriterionConnection)

All other criteria

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.

otherCriterion (OtherCriterion)

A single other criterion

ArgumentTypeDescriptionRequired
idInt

rateLimit (RateLimit)

Information about your current API quota

team (Team)

A single team

ArgumentTypeDescriptionRequired
idInt

teamCategories (TeamCategoryConnection)

All team categories

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.

teamCategory (TeamCategory)

A single team category

ArgumentTypeDescriptionRequired
idInt

teams (TeamConnection)

All teams

ArgumentTypeDescriptionRequired
afterStringReturns the elements in the list that come after the specified global ID.
beforeStringReturns the elements in the list that come before the specified global ID.
firstIntReturns the first n elements from the list.
lastIntReturns the last n elements from the list.

Mutations

addPendingHire (PendingHire)

# Create a PendingHire with a value for a text, long text, confirmable, or multiple_choice Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        { permanentFieldId: "favorite_food", value: "Egg McMuffins" }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

# Create a PendingHire with a value for a multiple select Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        { permanentFieldId: "equipment_required", value: "[\"Ergonomic Keyboard\", \"Standing Desk\"]" }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

# Create a PendingHire with a value for a Team Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        { permanentFieldId: "primary_social_club", value: 14 }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

# Create a PendingHire with a value for an Address Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        {
          permanentFieldId: "primary_address",
          value: "{\"address_line_1\":\"123 Test Street\",\"address_line_2\":\"Apartment 1\",\"city\":\"Pawnee\", \"state\":\"IN\", \"zipcode\":\"12345\",\"country\":\"USA\"}"
        }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

# Create a PendingHire with a value for a Contact Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        {
          permanentFieldId: "emergency_contact",
          value: "{\"first_name\": \"Joe\", \"last_name\": \"Schmoe\", \"email\":\"jschmoe@aol.com\", \"phone\": \"123.456.7890\", \"relationship\": \"Other\"}" }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

# Create a PendingHire with a value for a date Custom Field
mutation {
  addPendingHire(
    addPendingHireInput: {
      firstName: "Joe"
      lastName: "Schmoe"
      email:"joe@example.com"
      workCountryCode: "USA"
      customFieldValues: [
        { permanentFieldId: "fully_vested", value: "2019-12-12" }
      ]
    }
  ) {
    firstName
    lastName
    email
    workCountryCode
    customFieldValues {
      custom_field { permanentFieldId }
      value
    }
  }
}

Add a Pending Hire to Greenhouse Onboarding

ArgumentTypeDescriptionRequired
pendingHireInfoAddPendingHireInput!Required

updateEmployeeProfile (Employee)

# Update/create the value for a text, long text, confirmable, or multiple_choice Custom Field
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
        { permanentFieldId: "favorite_food", value: "Egg McMuffins" }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Update/create the value for a multiple select Custom Field
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
                { permanentFieldId: "equipment_required", value: "[\"Ergonomic Keyboard\", \"Standing Desk\"]" }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Update/create the value for a Team Custom Field
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
                { permanentFieldId: "primary_social_club", value: 14 }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Update/create the value for an Address Custom Field. Note that the value is a serialized JSON string (with quotes
# escaped).
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
                {
                  permanentFieldId: "primary_address",
                  value: "{\"address_line_1\":\"123 Test Street\",\"address_line_2\":\"Apartment 1\",\"city\":\"Pawnee\", \"state\":\"IN\", \"zipcode\":\"12345\",\"country\":\"USA\"}"
                }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Update/create the value for a Contact Custom Field. Note that the value is a serialized JSON string (with quotes
# escaped).
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
            {
              permanentFieldId: "emergency_contact",
              value: "{\"first_name\": \"Joe\", \"last_name\": \"Schmoe\", \"email\":\"jschmoe@aol.com\", \"phone\": \"123.456.7890\", \"relationship\": \"Other\"}" }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

# Update/create the value for a date Custom Field
mutation {
  updateEmployeeProfile(
    id: 20,
    employeeUpdates: {
      customFieldValues: [
        { permanentFieldId: "fully_vested", value: "2019-12-12" }
      ]
    }
  ) {
    customFieldValues {
      custom_field {
        permanentFieldId
        fieldType
      }
      value
    }
  }
}

Update an employee’s profile

ArgumentTypeDescriptionRequired
idID!Required
employeeUpdatesUpdateEmployee!Required

Types

Country

A country

FieldTypeDescription
countryCodeString
nameString
states[State]

CustomField

Represents a single CustomField record for your company. CustomFields can be stored and displayed in a variety of ways. The types are described via the CustomFieldTypes enum.

FieldTypeDescription
createdAtDateTime
customFieldGroupCustomFieldGroup
fieldTypeCustomFieldTypesThe field type determines how users input and view the data for this field.
idStringA unique identifier for this CustomField.
multipleChoiceOptions[String]
nameStringThe name of this custom field as users would see it inside Greenhouse Onboarding.
teamCategoryTeamCategory
updatedAtDateTime

CustomFieldConnection

The connection type for CustomField.

FieldTypeDescription
edges[CustomFieldEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

CustomFieldEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeCustomFieldThe item at the end of the edge.

CustomFieldGroup

A Group of Custom Field

FieldTypeDescription
idID
nameString

CustomFieldValue

A Custom Field Value Record

FieldTypeDescription
createdAtDateTime
customFieldCustomField
updatedAtDateTime
valueValueA different type of value will be stored based upon the field type of the CustomField. Some types have the data stored as a nested object. Note that the type is a scalar named Value. Even though it appears to be an object, you are not able to use GraphQL to determine its shape.
valueUpdatedAtDateTimeThe time of the most recent update to this field.

Department

Represents a single department in your company. Employees may belong to zero or one department. Departments are used in a variety of ways in Greenhouse Onboarding, including permissions and onboarding plans.

FieldTypeDescription
createdAtDateTime
descriptionString
idID
nameString
updatedAtDateTime

DepartmentConnection

The connection type for Department.

FieldTypeDescription
edges[DepartmentEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

DepartmentEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeDepartmentThe item at the end of the edge.

Document

Represents a single document attached to an Employee.

FieldTypeDescription
createdAtDateTime
fileFileContains the file payload.
idID
updatedAtDateTime

Employee

A single Employee that works for your company.

FieldTypeDescription
aboutStringA brief description of the employee. This information is displayed on both the employee’s profile and is also featured prominently in the Welcome Experience for any new hires that report to this employee.
createdAtDateTime
customFieldValues[CustomFieldValue]A list of all other profile information for this employee. Administrators can configure these fields on the Settings > Custom Fields page.
dateOfBirthDateNote that only administrators can see the birth year for employees
dateOfTerminationDateThis information is only available on terminated employees
departmentDepartment
documents[Document]These are documents that came over from Greenhouse Recruiting, were attached directly to the employee profile, or attached to a task. This does not include E-Signature requests.
emailStringThe employee’s work email. They need this in order to sign in
employmentStatusEmploymentStatus
firstNameString
hrManagerEmployeeThe employee’s HR Manager.
idID
lastNameString
locationLocation
managerEmployeeThis employee’s direct manager.
middleNameString
otherCriteria[OtherCriterion]
personalEmailStringThe employee’s personal email.
phoneNumberString
preferredFirstNameStringThis is the name that your employee prefers to go by. If this value is set, Greenhouse Onboarding will display this name everywhere in the product instead of the employee’s legal name.
preferredLastNameString
profileImageFileA file containing the employee’s profile image. This image is displayed in emails, reports and directory pages.
signatureRequests[SignatureRequest]These are E-Signature requests initiated through Greenhouse Onboardinging. Keep in mind that these requests can be in a number of different states in their lifecycle and may not always have a signed document available to download.
startDateDate
suffixString
titleStringThe employee’s job title.
updatedAtDateTime
workCountryCodeString

EmployeeConnection

The connection type for Employee.

FieldTypeDescription
edges[EmployeeEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

EmployeeEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeEmployeeThe item at the end of the edge.

File

A File record

FieldTypeDescription
expiresAtDateTimeThe time when the URL will expire. After this time, you will need to generate a new URL.
fileNameStringThe original name of the file.
fileSizeIntThe file size, in bytes
fileUrlStringAn expiring URL you can use to download the file.

Location

Represents a single location in your company. Employees may belong to zero or one location. Locations are used in a variety of ways in Greenhouse Onboarding, including permissions and onboarding plans.

FieldTypeDescription
createdAtDateTime
descriptionString
idID
nameString
updatedAtDateTime

LocationConnection

The connection type for Location.

FieldTypeDescription
edges[LocationEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

LocationEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeLocationThe item at the end of the edge.

Mutation

FieldTypeDescription
addPendingHirePendingHireAdd a Pending Hire to Greenhouse Onboarding
updateEmployeeProfileEmployeeUpdate an employee’s profile

OtherCriterion

A tag that can be used to refine on onboarding plan

FieldTypeDescription
createdAtDateTime
idID
nameString
updatedAtDateTime

OtherCriterionConnection

The connection type for OtherCriterion.

FieldTypeDescription
edges[OtherCriterionEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

OtherCriterionEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeOtherCriterionThe item at the end of the edge.

PageInfo

Information about pagination in a connection.

FieldTypeDescription
endCursorStringWhen paginating forwards, the cursor to continue.
hasNextPageBoolean!When paginating forwards, are there more items?
hasPreviousPageBoolean!When paginating backwards, are there more items?
startCursorStringWhen paginating backwards, the cursor to continue.

PendingHire

A Pending Hire Record

FieldTypeDescription
aboutString
createdAtDateTime
customFieldValues[CustomFieldValue]
dateOfBirthDate
departmentDepartment
emailString
employmentStatusEmploymentStatus
firstNameString
hrManagerEmployee
idID
lastNameString
locationLocation
managerEmployee
personalEmailString
phoneNumberString
preferredFirstNameString
preferredLastNameString
startDateDate
titleString
updatedAtDateTime
workCountryCodeString

RateLimit

Information about your current API quota

FieldTypeDescription
costIntThe cost of this query. This amount was deducted from your previous quota.
limitIntYour quota for the given period.
remainingIntThe remaining balance for your quota. Any calls that exceed this value will be throttled.
resetAtDateTimeThe time when your quota is reset to its maximum value.

SignatureRequest

An E-Signature Request for assigned to an Employee.

FieldTypeDescription
counterSignerEmployeeThe employee responsible for counter-signing this document, if applicable.
createdAtDateTime
fileFileThis is available only for completed signatures.
idID
signatureRequestTemplateSignatureRequestTemplate!
statusSignatureRequestStatus
updatedAtDateTime

SignatureRequestTemplate

A template used when assigning signature requests.

FieldTypeDescription
counterSignerEmployeeThe default employee responsible for counter-signing documents created from this template, if applicable. Individual SignatureRequest objects can override the counter signer.
createdAtDateTime
nameStringThe name of the template. This is the label administrators will see.
publicNameStringThe public-facing name of the template. This is the name the new hire will see. If this is null, new hires will see the name field.
updatedAtDateTime

State

A state

FieldTypeDescription
countryCountry
nameString
stateCodeString

Team

A Team record

FieldTypeDescription
descriptionString
emailString
idID
locationString
nameString
teamCategoryTeamCategory

TeamCategory

A Team Category Record

FieldTypeDescription
idID
nameString

TeamCategoryConnection

The connection type for TeamCategory.

FieldTypeDescription
edges[TeamCategoryEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

TeamCategoryEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeTeamCategoryThe item at the end of the edge.

TeamConnection

The connection type for Team.

FieldTypeDescription
edges[TeamEdge]A list of edges.
pageInfoPageInfo!Information to aid in pagination.

TeamEdge

An edge in a connection.

FieldTypeDescription
cursorString!A cursor for use in pagination.
nodeTeamThe item at the end of the edge.

Input Objects

AddPendingHireInput

Specify the properties of a new PendingHire

ArgumentTypeDescriptionRequired
aboutString
customFieldValues[UpdateCustomFieldValue]
dateOfBirthDate
departmentID
emailString
employmentStatusEmploymentStatus
firstNameString!Required
hrManagerID
lastNameString!Required
locationID
managerID
middleNameString
personalEmailString
phoneNumberString
preferredFirstNameString
preferredLastNameString
startDateDate
suffixString
titleString
workCountryCodeString!Required

CustomFieldValuesInput

Limit employees to those that satisfy the specified CustomFieldValue criteria

ArgumentTypeDescriptionRequired
dateValueDateFilter
idString!Required
idValues[Int]
textValues[String]

DateFilter

Specify a range of dates using after (exclusive >), before (exclusive <), or on (exact match)

ArgumentTypeDescriptionRequired
afterDate
beforeDate
onDate

DateTimeFilter

Specify a range of datetimes using after (exclusive >), before (exclusive <)

ArgumentTypeDescriptionRequired
afterDateTime
beforeDateTime

UpdateCustomFieldValue

Used to update an employee’s Custom Field Value

ArgumentTypeDescriptionRequired
idID!Required
valueValue

UpdateEmployee

The input object used to update an Employee.

ArgumentTypeDescriptionRequired
aboutString
customFieldValues[UpdateCustomFieldValue]
dateOfBirthDate
departmentID
emailString
employmentStatusEmploymentStatus
firstNameString
hrManagerID
lastNameString
locationID
managerID
middleNameString
otherCriteria[ID]
personalEmailString
phoneNumberString
preferredFirstNameString
preferredLastNameString
profileImageURL
startDateDate
suffixString
titleString
workCountryCodeString

Scalars

Boolean

Represents true or false values.

Date

Representation of a date in YYYY-MM-DD format.

DateTime

Representation of datetime in ISO8661.

Float

Represents signed double-precision fractional values as specified by IEEE 754.

ID

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

Int

Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.

URL

A URL-formatted String

Value

The actual value of a Custom Field Value. This type is capable of holding both Strings and Integers. Its content will depend on the fieldType of its corresponding customField.

text, long_text, confirmable

multiple_choice

multiple_select

team

employee

address

contact

date

Enums

NOTE: Enums are unquoted in user input but quotes in API output.

CustomFieldTypes

Possible type values for CustomFieldValues

ValueDescription
ADDRESSDisplayed as group of inputs. Stored as JSON.
CONFIRMABLEDisplayed as a text field where the user has to enter the value twice. Stored as a String.
CONTACTDisplayed as group of inputs. Stored as JSON.
DATEDisplayed as a datepicker. Stored as a DateTime
EMPLOYEEDisplayed as a dropdown of employees. Stored as an Employee ID.
LONG_TEXTDisplayed as a multiline text box. Stored as a String.
MULTIPLE_CHOICEDisplayed as a dropdown. Stored as a String.
MULTIPLE_SELECTDisplayed as a tag field. Stored as an Array of Strings.
TEAMDisplayed as a dropdown of teams. Stored as a Team ID.
TEXTDisplayed as a single line text field. Stored as a String.

EmploymentStatus

Possible employment statuses for an employee

ValueDescription
CONTRACTOR
FULL_TIME
INTERN
PART_TIME
TEMPORARY
TERMINATED

SignatureRequestStatus

Possible status values for a Signature Request

ValueDescription
BEING_PROCESSEDDocument is being processed by our E-Signature Vendor.
CANCELEDSignature request has been terminated.
COMPLETEDDocument has been successfully signed and verified.
ERRORCould not be completed due to an error processing the E-Signature.
WAITING_FOR_COUNTER_SIGNATUREDocument awaiting counter-signer signature.
WAITING_FOR_SIGNATUREWaiting for the employee to sign the document.