Making Your First API Request

Learn how to make your first API request with StackOne

Overview

You’ve recently received StackOne access and want to initiate your first API call using our Unified API. As an introduction to the StackOne Unified API, you’ve tested account connection through the StackOne Dashboard.

Now, you want to integrate a specific provider into your existing application and test the integration. In this guide, you will learn how to:

• List Applications for a Greenhouse Account

• Get a Specific Contact from a HubSpot Account

• Create an Employee in a BambooHR Account

Prerequisites

1. API Key created in StackOne Dashboard and copied to a secure location

2. Basic Authentication Setup - Learn how to properly authenticate with StackOne API using your API key

3. Required provider integration enabled

4. Account linked successfully

5. (Optional) Use an SDK or Postman

Getting Account ID

1. Specify the request type, URL, and API Key in the Authorization section (append to the header). cURL example:

Authentication Required: Your API key must be base64 encoded for Basic authentication. See the Basic Authentication Guide for detailed instructions on encoding your API key.

   curl --request GET
        --url https://api.stackone.com/accounts
        --header 'accept: application/json'
        --header 'authorization: Basic base64_encoded_api_key'

1. To filter results by a specific provider account (e.g., ATS Greenhouse), define the providers parameter:

Examples of complete API requests:

# Get all Greenhouse accounts
curl --request GET \
     --url 'https://api.stackone.com/accounts?providers=greenhouse' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key'

# Get all HubSpot accounts
curl --request GET \
     --url 'https://api.stackone.com/accounts?providers=hubspot' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key'

# Get all BambooHR accounts
curl --request GET \
     --url 'https://api.stackone.com/accounts?providers=bamboohr' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key'

2. From the /accounts API call response, copy the id value.

ATS: List Applications in Greenhouse

1. Specify the List Applications URL and header details using the account ID from the previous step:

curl --request GET \
     --url 'https://api.stackone.com/unified/ats/applications' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_greenhouse_account_id_here'

Note: Replace your_greenhouse_account_id_here with the actual ID value from the /accounts API call response

2. The response will contain a collection of existing applications with crucial data including:

   • Application ID
   • Candidate ID
   • Job ID
   • Location ID
   • Status
   • Created and Updated timestamps

3. (Optional) Use the data from the previous step to create new applications by making POST requests via the API.

CRM: Get Contact in HubSpot

1. First, list all contacts to see the available contacts:

curl --request GET \
     --url 'https://api.stackone.com/unified/crm/contacts' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_hubspot_account_id_here'

2. Select the required contact from the contacts collection and copy its ID.

3. Get a specific contact by including the contact ID in the URL path:

curl --request GET \
     --url 'https://api.stackone.com/unified/crm/contacts/contact_id_here' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_hubspot_account_id_here'

4. The response will contain all available data for the specified contact, including:
   • First Name, Last Name
   • Company Name
   • Email(s)
   • Phone Number(s)
   • Associated Account ID
   • Created and Updated timestamps

HRIS: Create Employee in BambooHR

1. First, get a list of existing employees to see the structure:

curl --request GET \
     --url 'https://api.stackone.com/unified/hris/employees' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_bamboohr_account_id_here'

2. Create a new employee using a POST request with the same URL and headers:

curl --request POST \
     --url 'https://api.stackone.com/unified/hris/employees' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_bamboohr_account_id_here' \
     --data '{ Employee JSON data goes here }'

3. Specify employee details in the request body, for example:

{
  "first_name": "John",
  "last_name": "Doe",
  "name": "John Doe",
  "display_name": "Dr. John Doe",
  "work_email": "[e-mail]",
  "job_title": "Consultant",
  "gender": {
    "value": "male"
  },
  "ethnicity": {
    "value": "white"
  },
  "marital_status": {
    "value": "single"
  },
  "employment_type": {
    "value": "full_time"
  },
  "employment_contract_type": {
    "value": "full_time"
  },
  "employment_status": {
    "value": "active"
  },
  "home_location": {
    "country": {
      "value": "AF"
    },
    "state": {
      "value": "AD-07"
    }
  },
  "work_location": {
    "country": {
      "value": "AF"
    },
    "state": {
      "value": "AD-07"
    }
  }
}

1. Upon successful creation, you’ll receive a 🟢 201 Status Code with the message “Record created successfully” and its timestamp.

2. (Optional) To verify the record creation, use the Employee ID returned in the response to get the specific employee:

curl --request GET \
     --url 'https://api.stackone.com/unified/hris/employees/new_employee_id_here' \
     --header 'accept: application/json' \
     --header 'authorization: Basic base64_encoded_api_key' \
     --header 'x-account-id: your_bamboohr_account_id_here'

References

1. Basic Authentication with API Keys

2. List Accounts

3. List Applications

4. Create Application

5. Get Contact

6. Create an Employee

7. Integrations List

8. Libraries & SDKs