StackOne Platform

Important

Before answering platform questions, fetch the latest documentation:

1. Fetch https://docs.stackone.com/llms.txt to discover all available doc pages
2. Fetch the specific page relevant to the user’s question

Do not guess or rely on potentially outdated information in this skill. Always verify against live docs.

Instructions

Step 1: Identify what the user needs

StackOne is a unified API platform for integrating with 200+ SaaS tools across HR, ATS, CRM, LMS, and more. Common platform tasks:

• Setting up: Creating API keys, understanding auth
• Managing accounts: Listing linked accounts, checking status, debugging connections
• API calls: Making requests to the unified API, understanding headers
• Webhooks: Subscribing to account lifecycle events
• Debugging: Investigating failed requests, auth errors, rate limits

Step 2: Authentication

All API calls require Basic auth. The API key goes in the Authorization header:

curl https://api.stackone.com/unified/hris/employees \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)" \
  -H "x-account-id: ACCOUNT_ID"

Key details:

• API keys are created at https://app.stackone.com
• Key format: v1.{region}.xxxxx
• The x-account-id header is required for all data API calls — it identifies which linked account to query
• A linked account = a connection between your customer and a third-party provider (e.g., BambooHR)

Step 3: Account management

Each linked account has:

• id — assigned by StackOne
• provider — the SaaS tool (e.g., bamboohr, greenhouse)
• origin_owner_id — your internal customer identifier
• status — active, error, inactive

To list accounts: GET https://api.stackone.com/accounts To get one account: GET https://api.stackone.com/accounts/{id}

Fetch the accounts API reference for full details: https://docs.stackone.com/platform/api-reference/accounts/list-accounts

Step 4: Fetch category-specific docs as needed

Consult references/api-categories.md for the full list of API categories (HRIS, ATS, CRM, etc.) and their documentation URLs.

Examples

Example 1: User wants to make their first API call

User says: “How do I get a list of employees from BambooHR via StackOne?”

Actions:

1. Confirm they have an API key (created at https://app.stackone.com)
2. Confirm they have a linked BambooHR account (they’ll need the account ID)
3. Show the curl command with proper auth and x-account-id header
4. Fetch https://docs.stackone.com/hris/api-reference/employees/list-employees for the response schema

Result: Working curl command with explanation of the response format.

Example 2: User wants to debug a failing integration

User says: “My StackOne API call is returning 401”

Actions:

1. Check if their API key is correctly base64-encoded (common mistake: forgetting the trailing colon)
2. Verify the key hasn’t been revoked in the dashboard
3. If they get 200 on /accounts but fail on data endpoints, check that x-account-id is present and valid
4. Fetch https://docs.stackone.com/overview/authentication for the latest auth details

Result: Identified root cause with fix.

Troubleshooting

Error: 401 Unauthorized

Cause: Invalid or missing API key.

• Verify the key format is v1.{region}.xxxxx
• The Authorization header must be Basic base64(api_key:) — note the trailing colon before encoding
• Check the key is active at https://app.stackone.com

Error: 400 Bad Request with “account not found”

Cause: The x-account-id header references a non-existent or disconnected account.

• List accounts with GET /accounts to find valid IDs
• Check the account status — it may be error or inactive

Error: 429 Too Many Requests

Cause: Rate limit exceeded.

• StackOne applies rate limits per API key
• Implement exponential backoff
• Fetch https://docs.stackone.com/overview/rate-limits for current limits

API calls return empty data

Cause: The linked account may have limited permissions on the provider side.

• Verify the provider credentials have the right scopes
• Check the account status in the dashboard
• Some providers require additional setup (API tokens, OAuth scopes)

Key URLs