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
  1. Use the Plans Discovery endpoint to get the ID for the Hiring Plan you're interested in.
  2. Use the Hiring Plan ID from #1 to get the Hiring Plan data from the Headcount endpoint. An example request using cURL would look like:

     curl -X GET \
       https://api.teamohana.us/<your-domain-name>/v1/headcount?plan-id='YOUR_PLAN_ID' \
       -H 'Accept: application/json' \
       -H 'Authorization: Bearer YOUR_API_KEY'

     where YOUR_PLAN_ID is the Hiring Plan ID from #1.
• Full Forecast data
  1. Using the Headcount endpoint without the Plan ID from above will give you the full Forecast data.

NOTE: The retrieved data can be further filtered by:

1. Headcount Status
2. Hiring Status
3. Department
4. Division

You can refer to the usage of these filters here.

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

Configure the TeamOhana Role attribute as a group attribute

Follow the same steps as in Configure the TeamOhana Role attribute:

1. In Okta, go to Directory -> Profile Editor.
2. Choose the TeamOhana User app profile from the list.
3. Click Add Attribute.
4. Fill in the popup form with the same values as before:

• Data type: string
• Display name: TeamOhana Role
• Variable name: teamohanaRole
• External name: roles.^[type=='teamohana'].value (copy-paste this exactly as-is)
• External namespace: urn:ietf:params:scim:schemas:core:2.0:User (copy-paste this exactly as-is)

In addition, set Attribute type to Group (instead of the default Personal). This is what lets you set the role's value at the group level.

Click Save.

Assign the TeamOhana app to the Okta Group

Now assign the TeamOhana app to the Okta Group whose members should receive the role.

1. In Okta, go to Directory -> Groups and select the group you want to configure.
2. Open the Applications tab and click Assign Applications.
3. In the popup, find TeamOhana and click Assign.

4. A popup appears with the group's app attributes. In the TeamOhana Role field, enter a valid TeamOhana role name (for example, Hiring Manager), then click Save and Go Back.

5. Back in the list, TeamOhana now shows as Assigned. Click Done.

Every member of this Okta Group will now be provisioned in TeamOhana with the role you set on the group. The same rules apply to the role value as in the per-user flow: it must match the name of a role that exists in your TeamOhana organization, a blank value falls back to the default Employee role, and an unknown value is rejected.