Making your first API request

Overview

You’ve recently received StackOne access and wanted to initiate your first API call using Unified API. As an introduction to StackOne Unified API, you’ve tried testing account connection through StackOne Dashboard.

Now you want to integrate a specific provider into your existing application and test the integration. In this example, you will be trying to:
– list applications for the Greenhouse account
– get particular contact for the HubSpot account
– create an employee for the BambooHR account

Prerequisites

1. API key created in StackOne Dashboard and copied to a safe place

   ⚠️

   Important:

   Keep your API key protected, and do NOT share it insecurely.

2. Integration of needed provider was enabled

3. Account linked

4. (Optional) Install and use Postman

Getting account ID

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

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

2. To filter results by specific provider account (e.g., ATS Greenhouse), you have to define the provider param, e.g.
   – provider=greenhouse
   – provider=hubspot
   – provider=bamboohr
3. From the /accounts API call, you received the id value. Copy it to a clipboard.

ATS: list applications in Greenhouse

1. Specify the list applications’ URL and header details:
   – https://api.stackone.com/unified/ats/applications
   – x-account-id:<id_from_Accounts_call>

   📝

   Note:

   Authorization remains the same

2. As a result, you’ve received a collection of existing applications with such crucial data:
   – application id
   – candidate id
   – job id
   – location id
   – status
   – created and updated timestamps, etc.

3. (Optional) Now you can use the data from the previous step to create applications by POSTing your changes via API.

CRM: get contact in HubSpot

1. Specify the list contacts’ URL and header details:
   – https://api.stackone.com/unified/crm/contacts/
   – x-account-id:<id_from_Accounts_call>

2. Choose a required contact from the entire contacts collection and copy its id to a clipboard.

3. Paste id inside URL.

4. You’ve received 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, etc.

HRIS: create employee in BambooHR

1. Specify the list employees’ URL and header details to see a sample employee array:
   – https://api.stackone.com/unified/hris/employees
   – x-account-id:<id_from_Accounts_call>

2. In a separate tab, open POST method request with the same URL, Authorization, and x-account-id header.

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

{
  "first_name": "John",
  "last_name": "Doe",
  "name": "John Doe",
  "display_name": "Dr. John Doe",
  "work_email": "[email protected]",
  "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"
    }
  }
}

4. In a normal scenario, you've received 🟢 201 Status Code with the message Record created successfully and its timestamp.

5. (Optional) To verify the record creation, modify GET request from step 1 to include the newly created employee id.

References

1. List Accounts
2. List Applications
3. Create Application
4. Supported Providers
5. Get Contact
6. Create an Employee
7. StackOne Unified API collection in Postman