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.
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.
GET requests in RESTful API, queries return data from Greenhouse Onboarding according to the arguments you provide. Check out our Onboarding API queries.
Use arguments to specify the exact data you need in your return. Arguments follow your query.
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.
DELETE requests in RESTful API, mutations transform or update information in your Greenhouse Onboarding instance. Check out the mutations available in Onboarding API.
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.
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.
- Authenticate your request with basic auth, using your Onboarding API access key and secret key for the header values.
- 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
|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.|