Greenhouse Onboarding API overview

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.

#  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.

#  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.

Create an Onboarding API key

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

Click API Management on the left.

Click Create a new API key.

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

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.

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