Kombo - Technical documentation and guidelines for customers

Executive summary

Teamspective’s HRIS integrations are powered by Kombo, Teamspective’s third‑party integration partner. You connect your HRIS from inside Teamspective, grant read access to the required HR data (ideally via a dedicated HRIS “service user”), and then Teamspective syncs users and groups so you can reduce manual admin work and analyse engagement results using HR attributes.

Using Kombo provides many benefits:

Low implementation cost
Kombo’s user experience is designed towards self-service, which reduces implementation effort and need for costly external integration services.
Low maintenance cost
Kombo provides a unified API which Teamspective is able to utilize across all integrations. This means that maintenance cost is divided between all our customers, not only you.
Dedicated integration specialists
Kombo’s integrations are maintained by integration specialists, meaning dedicated expertise and ability for Teamspective’s team to focus on building a better platform for you.
Security and compliance
Kombo publicly states ISO 27001 and SOC 2 Type II, GDPR adherence, and encryption in transit (TLS) and at rest; it also supports EU/US regional deployments and data‑minimisation controls such as scopes and employee filtering.

Teamspective uses Kombo because it enables broad HRIS coverage (60+ HR platform integrations), and because the integration is maintained by integration specialists (including technical support).

Technically (high level, non‑proprietary): Kombo provides a unified HRIS API and connector layer. It connects to your HRIS using the authentication method that HRIS supports (commonly OAuth 2.0, API keys, or other enterprise patterns such as SAML‑based OAuth token exchange), periodically syncs and normalises the data into its own region‑specific platform, and then Teamspective reads from Kombo’s unified API. Kombo can also push “data‑changed” notifications to Teamspective via signed webhooks to minimise polling and keep data current.

Security and compliance are a core part of the design: Kombo publicly states ISO 27001 and SOC 2 Type II, GDPR adherence, and encryption in transit (TLS) and at rest; it also supports EU/US regional deployments and data‑minimisation controls such as scopes and employee filtering. Teamspective’s Privacy Policy and DPA describe controller/processor roles and list Kombo as a sub‑processor for HRIS integrations.

Why Teamspective uses Kombo

Teamspective’s goal is to give you a reliable HRIS integration you can set up quickly, without bespoke implementation work for each HRIS vendor. Teamspective uses Kombo as its integration partner to

(a) support 60+ HR platform integrations,

(b) provide an integration “purpose built” for customer needs, and

HRIS integrations automatically manage users/teams and help unlock richer insights by combining engagement results with HR attributes (for example tenure/seniority—depending on what you choose to import). Only workspace admins and other users with granted permissions can access attribute based result segmentation. Fewer than 5 results are hidden to help maintain anonymity.

Kombo’s value to Teamspective (and therefore to the end customer) is that Kombo standardises and operates the “hard part” of HRIS integrations: dozens of varying APIs and credential types, data model differences, sync logic, reliability during upstream outages, and ongoing connector maintenance. Kombo explicitly describes itself as a unified API provider (“one API”) that lets a product integrate once and then support many tools, receiving data “in the same format” across systems.

How the Teamspective–Kombo HRIS integration works

Architecture and connector model

At a practical level, there are three layers:

Your HRIS (source of truth): Workday, HiBob, BambooHR, Oracle HCM, SuccessFactors etc.
Kombo (integration platform): connector/adapters per HRIS, sync engine, unified models, unified API, webhooks, and operational tooling.
Teamspective (consumer): reads HR data needed for user/group provisioning and analytics cohorting.

Kombo’s model is not “pass‑through only”: Kombo explicitly states it stores data to deliver faster API responses and to enable features like filtering, change tracking, deletion tracking, and resilience during upstream outages.

Data flow diagram

This diagram reflects Kombo’s documented approach: scheduled syncing, optional upstream webhooks for near‑real‑time, and downstream “data‑changed” notifications so the consuming app fetches only changes.

Core HRIS data shapes

Teamspective mainly needs a stable representation of people and the organisation structure. Kombo’s HRIS API positions “Employees” as the core object and notes that it includes employment status and manager relationships (among other attributes).

A simple conceptual view:

This is a high‑level conceptual diagram for how most HRIS systems represent org structures; exact fields depend on your HRIS and the configured data scope.

Authentication and authorisation methods you may see

There are two different authentication “planes” to understand:

(a) Teamspective ↔ Kombo, and

(b) Kombo ↔ your HRIS.

For Teamspective ↔ Kombo, Kombo’s unified API uses an API key (Bearer token) and an integration identifier header (X-Integration-Id) to target your specific HRIS connection.

For Kombo ↔ your HRIS, the method depends on the HRIS vendor and what your organisation has enabled. Common patterns include:

API key / Basic auth (example: BambooHR provides a REST API and references Basic Authentication and OAuth in its API getting‑started documentation).
Service user + token (example: HiBob documents creating “API service users” and authenticating with an ID + token; permissions are assigned via permission groups).
OAuth 2.0 (example: Oracle documents using OAuth to establish connections to Oracle Fusion Applications endpoints; Google documents OAuth 2.0 service accounts for server‑to‑server access).
SAML‑assisted OAuth token generation (example: SAP SuccessFactors documents generating an OAuth token using a SAML assertion plus an API key in the client configuration).

Kombo’s embedded connection flow guides you through what’s needed for your chosen HRIS and encourages creating stable credentials (Teamspective specifically recommends setting up a service user in your HRIS to maintain a stable connection).

Sync scheduling, webhooks, latency, rate limits, and “what happens when things fail”

Default sync behaviour. Kombo documents different sync types and default frequencies: full syncs every 10 hours when delta syncs are supported (or every 3 hours when they are not), and delta syncs every 3 hours.

Near real‑time updates (where supported). Kombo provides “real‑time data” via upstream webhooks when the connected HRIS supports webhook events; for systems without webhook support, faster sync frequencies (on certain plans) are the route to “near real‑time”.

When upstream webhooks are enabled and you subscribe to Kombo’s downstream data-changed webhook, Kombo reduces scheduled sync frequency from 3 hours to 24 hours because most updates arrive via webhooks (and you can usually expect events within ~10–20 seconds). Kombo also retries delivery to your system up to 5 times with exponential backoff.

Downstream notifications instead of polling. Kombo’s data-changed webhook is designed to reduce polling: it fires whenever data changes in Kombo and supports an incremental fetch approach using the updated_after filter. Kombo debounces data-changed with a 30‑second window (at most one event every 30 seconds) and may send multiple events during a sync because it does not wait for sync completion.

Initial sync duration. The first sync could take from seconds up to multiple hours depending on scope configuration, the HRIS system, and upstream rate limits, so customer experience should allow for some waiting time.

API rate limits. Kombo documents a rate limiter of 300 requests per 60 seconds (and that rate limit information is exposed via response headers).

Failure modes and recovery (transparent but reassuring). Typical recoverable issues include expired credentials, permission changes, upstream outages, and rate limiting. Kombo provides explicit guidance on which errors are safe to retry (for example rate limit exceeded and service unavailable) and recommends exponential backoff (ideally with jitter).

For credential problems specifically, Kombo documents that after three consecutive days of failing authentication checks (performed before syncs), Kombo will pause scheduling syncs and prompt reconnection; Kombo recommends detecting this programmatically via the integration-state-changed webhook.

Data mapping, custom fields, and filtering

Kombo supports multiple (customer‑friendly) levels of data shaping:

Scopes (what data is extracted and stored). Kombo recommends restricting synced data in production for privacy and security. Scopes can enable/disable entire models and fields.
Employee filtering (which employees are included). Kombo offers a filtering UI where customers can select, for example, “Active employees” and specific locations/departments; Kombo states it only persists data for employees matching the configured filter afterwards.
Custom fields (mapping HRIS-specific attributes into stable keys). Kombo describes a custom_fields JSON object where you can map any property from an integration to a customer‑defined key, allowing you to unify naming differences across customers/tools.
Integration fields / passthrough (selective raw-field exposure). Kombo supports enabling passthrough for selected raw fields so they appear in responses as integration_fields after the next sync.
Passthrough API (edge cases). For rare integration-specific needs, Kombo provides a Passthrough API to call the underlying tool’s native API while Kombo handles tool-specific authentication.

Monitoring, auditing, and supportability

Kombo provides monitoring and audit features intended to make integrations supportable at scale:

Operational logs. Kombo documents logs in its dashboard to monitor and troubleshoot integrations.
Audit logs. Kombo documents audit logs as an optional feature (available on and above the Scale plan) retained for one year by default (up to three years on higher plans).
Webhook security and observability. Webhooks are signed (HMAC) using a per-environment secret, and Kombo documents precise validation steps; Kombo also automatically disables webhooks if it receives 404/410 for more than 7 days.

Connector maintenance and versioning

From your point of view, the key point is ownership: Teamspective has chosen a model where integration maintenance is handled by specialists (Kombo + Teamspective), rather than by each customer building and running their own connector.

Kombo also documents operational practices such as credential “revisions” (new revisions become the latest, and new integrations use the latest revision), and recommends testing new revisions in development before using them in production—illustrating an explicit versioning/rollout concept for integration configuration.

Security, compliance, privacy, and legal assurances

Compliance and certifications

Kombo publicly states it maintains ISO 27001 certification, SOC 2 Type II compliance, and GDPR adherence.

For context, ISO 27001 is an information security management system (ISMS) standard focused on systematic risk management, cyber resilience, and operational excellence.
SOC 2 is an assurance report on controls relevant to security, availability, processing integrity, confidentiality, and/or privacy.

Encryption in transit and at rest

Kombo states that data is encrypted in transit using TLS and encrypted at rest.

Data residency and regional processing

Kombo documents EU and US regions with separate endpoints (api.kombo.dev for EU and api.us.kombo.dev for US) and notes that resources (including API keys) are region‑specific and cannot be shared across regions.

Kombo also positions regional deployments as part of compliance and data protection.

Access controls and least privilege

Kombo documents role-based access at the Kombo environment level (Admin/Developer/Operator) with explicit restrictions for production operators (for example: operators can create integrations and map custom fields but cannot delete integrations, change scopes, or review audit logs).

Teamspective’s HRIS integration workflow also emphasises permissions and stability: you must be a Teamspective workspace admin and have HRIS admin rights, and Teamspective recommends creating a service user in your HRIS to maintain a stable connection.

Data minimisation, retention, and deletion

Good HRIS integrations minimise data by design. This is supported in three ways:

Minimise what’s synced (Scopes): Kombo recommends restricting what data is extracted and stored in production.
Minimise who is included (Filtering): you can limit shared data to specific employee segments, and Kombo documents that it deletes employee data that becomes out-of-scope of filtering.
Minimise how long operational traces exist (Deletion policy): Kombo documents deleting request/response log data after 30 days on non‑enterprise plans and deleting statistics about syncs/write actions after 60 days.

From a legal/privacy principles perspective, GDPR’s Article 5 includes data minimisation (“adequate, relevant and limited to what is necessary”) and storage limitation (“no longer than necessary”).

Legal/contractual positioning (Teamspective, you, and Kombo)

Teamspective’s Privacy Policy states that when your organisation uses Teamspective, your organisation is the data controller and Teamspective is the data processor; it also notes that data may be imported from HRIS integrations at your request.

Teamspective’s DPA lists Kombo Technologies GmbH as a sub‑processor for “HRIS integrations” and indicates processing location details in the annex.

If you need clarity on controller/processor responsibilities, UK/EU regulators publish plain-language explanations of these roles (useful for internal DPIAs and procurement).

Privacy implications in Teamspective (anonymity and access)

Engagement survey answers are anonymous and results are hidden for responder groups with small response counts; the default minimum is 4 responses per question (configurable).

For HRIS-based attributes specifically, segments with fewer than 5 results are hidden and only workspace admin users or others with purposely assigned permissions can access attribute data and segmentation of results.

Integration options, restrictions, and risk‑reducing mitigations

Your integration options with Teamspective

Option	What you do	Typical freshness	When to choose it	Key restrictions
HRIS integration inside Teamspective (powered by Kombo)	Connect HRIS via Teamspective UI, grant permissions, accept user sync.	Scheduled sync (every 24h) plus optional near real‑time where upstream webhooks are supported and enabled.	Best default: fastest time-to-value, broad HRIS coverage, minimal engineering.	Coverage differs by HRIS; some features require setup (e.g., upstream webhooks) and not every HRIS supports the same fields/models.
Customer-built integration using Teamspective Public API	You build/operate your own HRIS connector and push org structure to Teamspective.	Whatever you implement	When you have strict third-party policies or bespoke complex needs	Teamspective import is “full state synchronisation”: it replaces workspace state with what you provide, so you must operate it carefully.
SFTP export to Kombo (if enabled/available)	Export HR data files from HRIS/on‑prem to Kombo via SFTP.	Depends on export schedule; each file transfer triggers sync.	When API credentials are not acceptable or HRIS is constrained; can also support on‑prem export patterns	Requires SSH key pair and customer-side export configuration; availability is plan-dependent.
SCIM (IdP‑driven provisioning)	Use IdP (e.g., Azure AD/Okta) SCIM to sync users/groups	Usually near real‑time identity provisioning	When identity governance is centralised in IdP	SCIM focuses on identity and group provisioning; may not carry the richer HR attributes you might want for analytics segmenting.

Common restrictions (what’s realistic to expect)

Different HRIS systems expose different data and capabilities, and not every HRIS supports webhook events or true delta sync APIs. Kombo explicitly positions webhook-based “real-time data” as available where systems support it; otherwise accelerated sync frequency is how near-real-time is achieved.

Initial sync speed and “freshness” depend on upstream rate limits and scope: Kombo notes the first sync can take up to hours in some cases; it also documents API rate limits (300 requests/60 seconds).

Some integration capabilities can require one-time configuration steps (for example, enabling upstream webhooks via Setup Flow if the HRIS cannot be configured fully via API).

Risks and mitigations (plain-language, practical)

Risks / concerns	Mitigation	What you should do
“A third party is involved in our HRIS connection.”	Teamspective discloses Kombo as the integration partner; Teamspective’s DPA lists Kombo as a sub-processor for HRIS integrations.	Ask Teamspective for the DPA + subprocessor annex; confirm your required Kombo region (EU/US) before onboarding.
“We only want to share the minimum necessary HR data.”	Kombo supports scopes (field/model control) and filtering (employee subset selection), and it recommends restricting production scopes for privacy/security.	Start with a minimal dataset (email, name, manager/group structure, employment status); expand only with a clear purpose and internal approval.
“We need evidence for audits and incident reviews.”	Kombo provides logs; audit logs are available on certain plans with defined retention; Teamspective provides controller/processor documentation via privacy policy and DPA.	Ensure your plan includes the audit features you need; document how to export evidence and who owns incident response steps with Teamspective.
“What if credentials expire or permissions change?”	Kombo documents pausing scheduling after persistent authentication failures and recommends monitoring integration-state-changed and using reconnection flows.	Use a dedicated HRIS service user; set calendar reminders for certificate/token rotation; ensure the right team receives integration-health alerts.
“Are webhooks safe?”	Kombo signs webhooks and documents how to validate signatures; it also auto-disables unreachable webhooks after prolonged 404/410.	Validate signatures server-side, restrict inbound traffic where possible, and keep a weekly “safety net” reconciliation fetch strategy.
“Will this expose individual survey answers?”	Survey answers are anonymous and results are hidden for small groups; HRIS segment data/pivoting is limited to workspace admins or other users with specifically granted permissions.	Keep the minimum group size threshold at a safe level for your organisation; restrict admin access; review cohort attributes for sensitivity.

Practical recommendations and implementation timeline

Recommendations for Teamspective customers (configuration, monitoring, contractual clauses)

Below is a list of useful recommendations to consider when integrating your system of record:

Choose the right “source of truth” and keep it clean. Your system of record (HRIS, EntraID, Okta) should be the authoritative source of truth and Teamspective mirrors that state. Even if you use the Kombo-powered integration, the same governance principle applies: keep system of record data clean and confirm which fields are used to create attributes for results segmentation .
Use a dedicated HRIS service user with least privilege. Teamspective recommends setting up a service user in your HRIS to keep the connection stable. Pair that with least-privilege permissions and explicit review/approval for any sensitive attributes you plan to use for analytics pivoting.
Minimise data by default, expand deliberately. Use filtering and scopes to import only what you need. Kombo recommends restricting production scopes for privacy/security; filtering lets you limit who is included (e.g., active employees, specific locations).
Confirm data residency early. If you are an EU-based organisation or have strict data location requirements, explicitly confirm the Kombo region used for your integration (EU/US regions are distinct and use separate endpoints/resources).
Set up integration health monitoring as “business critical”. Ensure your administrators know what “integration state changed” means and who owns reconnection/credential rotation. Teamspective actively monitors integration state and will reach out to the specified contacts immediately when an error is noticed.