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 either an active Onboarding API key or Onboarding API credentials, 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

Creating an API key generates an access key and secret key, which are used for basic auth on your API requests. This is separate from API credentials (client ID and client secret). To create API credentials instead, see the section below.

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.

Create Onboarding API credentials

Creating API credentials generates a client ID and client secret. This is separate from an API key (access key and secret key). To create an API key instead, see the section above.

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

Click API Management on the left.

Click into the API Credentials tab, then choose Create new API credentials.

Enter a descriptive name for your credentials, click Create credentials. 

After the the credential is created, click Copy, and paste the credentials in a secure location to provide to the integration later. Once you've done that, check the box next to I have stored the client credentials and click Finish if you wish to exit.

If you want to change the scopes that credential has access to, click Manage permissions.

From this page, you can edit the description and manage the data this set of credentials can access.

Click Save when finished.

If you need to rotate your client secret, navigate to the Client secret tab from here and choose Rotate secret. 

Confirm in the dialog box that you want to Rotate. A new client secret will be generated and displayed.

Update any external systems or integrations using the previous client secret with the new value to prevent service disruptions.

Once rotated, the previous client secret can no longer be used to authenticate 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