Permissions: Owners

Product tier: Available for the Greenhouse Onboarding subscription tier

Onboarding API can be used to retrieve and modify your employee profiles and company information in Greenhouse Onboarding. Onboarding API is typically used to build HR integrations. Unlike a traditional REST API, Onboarding API only supports graphQL, which means your queries can be as exact as you need.

To connect to Onboarding API, you need an active Onboarding API key, and if necessary, allowlisted access to Greenhouse's server IPs.

Definitions

Onboarding API only supports graphQL, which lets you retrieve information with queries and transform information with mutations. Check out the definitions below to get started using graphQL.

Query

Similar to GET requests in RESTful API, queries return data from Greenhouse Onboarding according to the arguments you provide. Check out our Onboarding API queries.

Example – The Eucalyptus organization can use the employees query to retrieve information about their employees from Greenhouse Onboarding.

#  Sample request
{ employees(first: 1) { pageInfo { hasNextPage endCursor } edges { node { id email } cursor } } }

# Sample response
{
"data": {
"employees": {
"pageInfo": {
"hasNextPage": true,
"endCursor": "MQ=="
},
"edges": [
{
"node": {
"id": "123456",
"email": "e.m.rogers@ymail.com"
},
"cursor": "MQ=="
}
]
}
}
}

Argument

Use arguments to specify the exact data you need in your return. Arguments follow your query.

In the employees query above, the Eucalyptus organization filtered the return with an argument to only include the first employee in their data. Each query will accept its own unique arguments.

Mutation

Similar to POST, PATCH, or DELETE requests in RESTful API, mutations transform or update information in your Greenhouse Onboarding instance. Check out the mutations available in Onboarding API.

Example – The Eucalyptus organization can use the add department mutation to add new departments to Greenhouse Onboarding.

#  Sample request
mutation {
  addDepartment(
    addDepartmentInput: {
      name: "Engineering"
      externalId: "123"
    }
  ) {
    department {
      id
      name
      externalId
    }
  }
}

# Sample response

{
"data": {
"addDepartment": {
"department": {
"id": "102732",
"name": "Engineeering",
"externalId": "123"
}
}
}
}

Type

Types are used to build queries or mutations, and they tell the API which data to action. Check out all the types in Onboarding API.

Input objects

Queries and mutations take input objects as arguments. These arguments have names and values. The value will either be a scalar or a more complex structured input. Check out the available input objects in Onboarding API.

Example – The Eucalyptus organization can filter the employees query with a DepartmentFilter input object so that their response will only return employees in certain departments.

Create an Onboarding API key

Note: In order to create an Onboarding API key, you'll need to be an owner in Greenhouse Onboarding.

To create an Onboarding API key, click Settings on your navigation bar.

The Settings button is highlighted on Greenhouse Onboarding by a marigold emphasis box

Click API Management on the left.

The Settings page shows API Management button highlighted in a marigold emphasis box

Click Create a new API key.

The API Management page shows create a new API key button highglighted in a marigold emphasis box

Enter a descriptive name for your API key, and click Create.

The create a new API key page shows an example name for a new Api key called Employee update API key and the Create button is highlighted in a marigold emphasis box

Copy the secret key and access key to a secure location. You won't be able to retrieve these credentials once you close the window.

The create a new API key box shows an example generated API key highlighted in a marigold emphasis box

When finished, click Close.

Your Onboarding API key is configured and ready for use! Use the access key and secret key values for the basic auth header on your API requests.

Allowlist Greenhouse server IP addresses

Depending on your organization's security practices, you may need to allowlist Greenhouse server IP addresses in order to make Onboarding requests. Learn more about allowlisting server access here.

Make Onboarding API requests

When you're ready, you can make Onboarding API requests using your API development tool.

  1. Authenticate your request with basic auth, using your Onboarding API access key and secret key for the header values.
  2. Query the endpoint with the method you prefer.

In its most simple form, your request payload will consist of a JSON object with a single key: query. The corresponding value for the query key is the graphQL query itself, and it's expressed as a string.

Common API requests

Goal Method
Get alerted when employees are created in Greenhouse Onboarding.

Use the employees(EmployeeConnection) query; limit your query with the createdAt argument. 

Retrieve a list of employees with a specific start date range. Use the employees(EmployeeConnection) query; limit your query with the startDateFilter argument. 
Change information on an employee profile. Use the updateEmployeeProfile mutation.
Retrieve information about your employees. Use the employees(EmployeeConnection) query.
Add or update a department. Use the addDepartment or updateDepartment mutation.
Retrieve signed e-signature documents. Use the employee query for a single employee or the employees(EmployeeConnection) query for multiple employees.