BambooHR Employee and Dataset Sync

Overview

Design a resumable read pipeline for employee data. Prefer BambooHR's dataset v2 contract for new bulk data work, minimize fields at the source, and treat missing fields as a possible permission decision rather than automatically as data loss.

Prerequisites

• The target repository or integration path and the requested operator outcome.
• The tenant, identity, and data scope only when approved live work is in scope.
• The current evidence register plus customer-specific permissions and agreements.

Current Contract

• Employee endpoints include list, get, create, and update operations.
• POST /api/v2/datasets/{datasetName}/data accepts fields, OData-style filter, orderBy, page, and pageSize and returns data, links, and meta; page size is at most 1000 in the reviewed OpenAPI.
• Dataset v1 data calls are deprecated. Dataset discovery and field discovery use v1.2 endpoints in the current OpenAPI.
• Legacy custom-report endpoints carry deprecation notices. Do not start a new pipeline on them merely because old examples do.

Authentication

Use OAuth scope report where the documented dataset operation requires it, or a dedicated API-key user with access only to selected fields. Bind credentials, checkpoint, and destination namespace to one tenant.

Instructions

1. Define the business purpose, legal basis, tenant, destination, data owner, refresh target, and exact employee fields before making a request.
2. Discover the dataset and its field definitions from current endpoints. Save field IDs and semantic mappings as reviewed configuration, not assumptions.
3. Query dataset v2 with deterministic ordering. Keep every ordered field in the requested fields list and bound pageSize to the documented maximum.
4. Follow returned pagination metadata or links until completion. Persist a checkpoint only after the destination transaction commits.
5. Upsert by a stable tenant-scoped employee identifier. Distinguish absent, null, redacted, future-dated, and inactive values.
6. Reconcile source count, received count, accepted count, rejected count, and destination count. Quarantine schema or permission drift instead of deleting.
7. Encrypt retained HR data and delete raw page bodies after the approved retention window.

Tool Discipline

Use Read, Glob, and Grep to inspect mappings, schemas, and checkpoints. Use Write/Edit only for approved pipeline code, configuration, and tests. Do not use this skill to fetch production employee data or mutate a downstream system.

Approval Boundaries

Require approval for the field set, inactive/future employee inclusion, production tenant, destination, retention policy, and any employee create or update operation. Reads do not authorize writes.

Output

Return dataset and field selection, auth identity, pagination and checkpoint design, mapping contract, reconciliation counts, retention controls, tests, and all unapproved live operations.

Error Handling

• 403: re-check field-level permission and requested dataset; do not request broader access without a business owner.
• 413: reduce page size or field set; never silently drop records.
• 422: reject the invalid filter/order contract and preserve the checkpoint.
• Missing field with 200: compare requested and returned schemas because some report paths omit inaccessible fields without failing.

Examples

• "Sync active employees to the warehouse" produces a minimized dataset v2 plan.
• "Copy every employee field" pauses for field necessity and retention approval.

Resources

Read official evidence before selecting endpoints.