TeamOhana API Reference

1. What does the Headcount Data API do?

The Headcount Data API enables users to retrieve comprehensive headcount information, including historical, current, and future data. It supports a range of use cases, from tracking approved headcounts to understanding the time taken for approval processes. This can be particularly useful for HR, finance, and operations teams looking to perform data analysis and make informed decisions.

Users can opt for either:

• Headcounts data
• Full Forecast data

2. What are the typical use cases that this API solves?

3. How do I authenticate with the API?

The API requires an API key for authentication. Ensure you include the API key in the headers of your request as follows:

Authorization: Bearer YOUR_API_KEY

4. How do I make a request to the API?

To request headcount data, send a GET request to the API endpoint: https://api.teamohana.us/{domain_name}/v1/headcount

Here's an example request with recommended configuration.

Note: Please replace YOUR_DOMAIN_NAME and YOUR_API_KEY with your specific values.

curl -X GET \
  https://api.teamohana.us/YOUR_DOMAIN_NAME/v1/headcount \
  -H 'Accept: application/json' \
  -H 'Accept-Encoding: gzip' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --compressed

5. How do I use filters to get to the specific data of my interest?

1. The Headcount endpoint has support for a wide variety of filters to support your use cases. Please see the updated API spec for the types of filters supported.

2. There is an additional Discovery endpoint. This allows you to find the id you want to use as a filter. Please refer to API Docs.

   • Supported objects: Plan, Division, Department

Some examples of filter usage:

1. Filter by Plan

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'plan-id=YOUR_PLAN_ID'

2. Filter by Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'status=approved'

3. Filter by Hiring Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'hc-hiring-status=in-progress'

4. Filter by multiple Hiring Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'hc-hiring-status=in-progress' \
     --data-urlencode 'hc-hiring-status=offer-sent'

5. Filter by Plan and Department

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'department-id=YOUR_DEPARTMENT_ID' \
     --data-urlencode 'plan-id=YOUR_PLAN_ID'

6. Filter by Plan, Department and Hiring Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'hc-hiring-status=in-progress' \
     --data-urlencode 'department-id=YOUR_DEPARTMENT_ID' \
     --data-urlencode 'plan-id=YOUR_PLAN_ID'

7. Filter by Division, Plan and Hiring Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'hc-hiring-status=in-progress' \
     --data-urlencode 'plan-id=YOUR_PLAN_ID' \
     --data-urlencode 'division-id=YOUR_DIVISION_ID'

8. Filter by Division, Department, Plan and Hiring Status

   curl -G https://api.teamohana.us/<your-domain-name>/v1/headcount \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode 'hc-hiring-status=in-progress' \
     --data-urlencode 'department-id=YOUR_DEPARTMENT_ID' \
     --data-urlencode 'plan-id=YOUR_PLAN_ID' \
     --data-urlencode 'division-id=YOUR_DIVISION_ID'

6. What is the response format?

The API responds with a JSON object. Below is an example of the response structure:

Standard fields:

[
  {
    "hiring-status": "Hired",
    "employee-type": "Full Time",
    "department": "Sales",
    "headcount-approved-date": "2024-07-15T00:00:00Z",
    "target-variable": 1234,
    "priority": "Normal",
    "target-equity": 4321,
    "opening-id": "1234-123",
    "budget-equity": 44000,
    "headcount-id": "ORG-123",
    "budget-salary": 205000,
    "reporting-manager": "John Nash",
    "annualized-budget-salary": 2460000,
    "actual-equity": 4321,
    "actual-variable": 1324,
    "budget-job-level": "L1",
    "headcount-type": "New hire",
    "archived-justification": "Not required",
    "archived-date": "2024-07-15T00:00:00Z",
    "backfill-employee-email": "back.fill@email.com",
    "headcount-denied-date": "2024-07-15T00:00:00Z",
    "target-start-date": "2024-06-27T21:07:14Z",
    "budget-start-date": "2024-08-26T00:00:00Z",
    "division": "Engineering",
    "budget-pay-rate": "YEAR",
    "job-level": "L2",
    "job-name": "GH-1234 - Sales Director, Generative AI",
    "denied-justification": "Not Suitable",
    "actual-salary": 2345,
    "location": "San francisco, USA",
    "reporting-manager-email": "john.nash@email.com",
    "last-updated": "2024-07-15T00:00:00Z",
    "headcount-status": "Approved",
    "actual-start-date": "2024-06-27T21:07:14Z",
    "pay-rate": "YEAR",
    "budget-currency": "USD",
    "job-title": "Software Engineer",
    "backfill-employee": "John Wick",
    "annualized-actual-salary": 28140,
    "backfill-employee-id": 1234,
    "target-salary": 84840,
    "target-currency": "USD",
    "annualized-target-salary": 1018080,
    "employee-name": "John Doe",
    "actual-currency": "USD",
    "budget-variable": 105000,
    "headcount-url": "https://app.teamohana.us/headcount-details/ORG-123",
    "team": "Sales",
    "approval-requested-date": "2024-07-15T00:00:00Z",
    "initiative": "Initiative Name",
    "target-pay-rate": "YEAR",
    "hiring-plan-active": "True",
    "hiring-plan": "DEFAULT"
  }
]

Custom fields:

[
  {
    "custom-fields": {
      "HEADCOUNT": {
        "Field 1": value,
        "Field 2": value,
        "Field 3": value
      },
      "EMPLOYEE": {
        "Field 1": value,
        "Field 2": value,
        "Field 3": value
      },
      "OFFER": {
        "Field 1": value,
        "Field 2": value,
        "Field 3": value
      }
    }
  }
]

7. What should I do if I encounter errors?

In case of errors, the API will return an appropriate HTTP status code along with a message describing the issue. Common error codes include:

• 401 Unauthorized: Request does not contain valid credentials.
• 500 Internal Server Error: Something went wrong at TeamOhana. Please contact support.

8. What is the limit of the number of API requests?

The API rate limit is currently set to 5 requests per second. If you require any adjustments to this limit, please reach out to our support team for assistance.

For more information or assistance with the API, please contact us.

Setup

Pigment allows you to connect to an external API via API Request as an Integration option. Using this, you will be setting up a connection to the TeamOhana Pigment Connector API.

Pre-requisites:

1. An existing Pigment account, and
2. A working import configuration ID.

Set up a new API request connection in Pigment with the following information:

1. POST endpoint URL
   • https://api.teamohana.us/<your name in TeamOhana>/v1/headcount/upload/pigment
2. Headers
   • Authorization: Bearer <your TeamOhana API key>
   • x-pigment-api-key: <your Pigment API key>
3. JSON Body
   • {"import-configuration-id": <your Pigment Import Configuration ID>}

Verification

Once the API request connection has been set up, please set up a way to test the import in a Board where you would like to use it. The Forecast data should now be available for viewing in a Dimension List.

If you want to try the TeamOhana Pigment connector API without the above setup, please execute the following command with any HTTP client of your choice (curl is being used in the example, but any HTTP client would work).

curl -X POST \
  https://api.teamohana.us/<your name in TeamOhana>/v1/headcount/upload/pigment \
  -H 'accept: application/json' \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer <Your TeamOhana API key>' \
  -H 'x-pigment-api-key: <Your Pigment API key>' \
  -d '{"import-configuration-id": <Your Pigment Import Configuration ID>}'

Troubleshooting

1. Triggering an import from Pigment may bring up an error. Usually, this is displayed as a Webhook error.
   • The data might still end up getting imported successfully.
   • The data might not get imported. In that case, please open a support request with TeamOhana.
2. If you do not see some columns you expect in your Pigment Dimension List, please verify that they appear with the same name in the source CSV used to create the Import Configuration.

Process diagram