In this guide, we will show you how to easily get started using the StackOne Unified API. Let's get started with some terminology:
Project: this is the construct that binds all of your StackOne integrations together and where your credentials for each Provider integration are stored.
StackOne API Key: this is the API key that you will use to authenticate for all calls to StackOne.
Provider: a company with a SaaS offering in any of our supported verticals such as HRIS, ATS, CRM, etc
The overall model can be summarised in the following diagram:
There are 4 steps to setup your first integration:
The rest of this document will walk you through the process of configuring your first StackOne integration.
To create a Project, navigate to the StackOne Dashboard and select New Project in the top-left dropdown. Give your Project a name and select the most local geographic region that your traffic will come from.
Click the blue Create Project button to continue.
Projects support multiple integrations so if you have already created a Project you can skip this step and reuse an existing Project.
The next step is to create a StackOne API Key for your Project. To do this, make sure your project is selected in the projects drop-down in the top-left of the dashboard and click on API Keys in the left navigation. To begin the creation, click the Create API Key button.
In the popup dialog, give your key a name. This name is only used as a label for your key but cannot be changed later.
When you click Generate, your StackOne API Key will be generated and displayed on-screen as shown:
Copy and save the StackOne API Key securely.
This is the only time that the StackOne API Key will be displayed in its entirety and it cannot be retrieved in future, even by StackOne support staff. If you lose this key you will need to generate another key.
The newly created API Key will now be listed in the API Keys tab.
You have successfully created a Project and a StackOne API Key to connect to your project. Next, we will integrate your project with a Provider.
In this step, we will configure an Integration for your Project. This involves working with one of our Providers to set up your sandbox account and credentials with them before storing those credentials in your Project and activating them in a process we call Account Linking.
Each of our Providers follows a slightly different process for setting up the integration so we have documented them all here:
Please follow the detailed process described for your desired Provider and then return to this page.
For our example, we will enable an integration with BambooHR.
You can get a free bamboohr trial account or request temporary access to a StackOne sandbox account
From the dashboard, click on the Integrations menu in the left-navigation and you will see several tabs, each of which contains our available partner integrations for that vertical.
Click on BambooHR and you will be presented with a pop-up where you can enter any information that StackOne needs at this stage in the Credentials section. For BambooHR, we do not need any further information, so we can click to Enable the integration and then Save Integration.
The BambooHR icon will now be enabled as shown:
The final step is to link your sandbox BambooHR account with your project. To do this, click on Accounts in the left-navigation and then on Link Account button on the top-right:
You will be presented with a selection showing currently un-linked integrations; in our example case BambooHR will be the only option on the list:
Click on the BambooHR icon and you will be presented with a screen to enter some final details. Each Provider requires slightly different information here, but for BambooHR this is an API Key and the Company Domain you generated on the BambooHR site. Enter these credentials and click Connect to complete the process.
If the linking process is successful, you should see a confirmation as shown:
In your Accounts you should now also see the BambooHR provider is listed as Active and a Test Connection button will be enabled on the row.
Click on the Test Connection button to open the Test Account Connection dialog. From this dialog, you can select different actions to perform against the StackOne Unified API, which will now be retrieving and transforming data directly from BambooHR on your behalf.
To test this, select List Employees from the Action dropdown and click the Send Request button. The response will be displayed on the right panel as shown:
When you click on Send Request, the UI will make a request to the StackOne Unified API on behalf of your Project, just like you had used your StackOne API Key to hit the API. StackOne then converts this request into BambooHR's format and makes a call to the BambooHR API using the credentials you configured in the Link Account process. Finally, the response data is transformed into the StackOne Unified API format and returned to the UI.
Updated 2 months ago