Skip to main content

​
Documentation Restructure - Handoff Notes

Restructure of the Bindbee docs against the Bindbee API Doc & DX Assessment, using the Diátaxis framework (Tutorials / How-To / Reference / Explanation). Date: 2026-07-31

​
What changed

Replaced the four mixed-axis anchors (Documentation / SDK / Webhooks / Custom Fields, with five sub-tabs mixing intent-based and product-based grouping) with four intent-based tabs:
Integrations & Coverage and the Platform Tour sit inside Get Started rather than in a separate Resources tab - “Resources” read as a synonym for Get Started and split the evaluator’s path across two tabs. Fixes the three UX problems in §5 of the assessment: On model grouping: an intermediate category layer (Core / Compensation & Payroll / Benefits / Time & Attendance / Banking, and the ATS and LMS equivalents) was built and then removed by request, to keep the sidebar at two levels - product → model → endpoints. The models are therefore a flat list again, but ordered logically instead of alphabetically, which retains most of the benefit: related models are adjacent, and Employee - the hub model almost everything hangs off - is first rather than buried between Dependent Benefits and Employee Payroll Runs. The residual cost is scanning: HRIS has 18 model groups and ATS 16 in a single ungrouped column. If that proves hard to scan in practice, restoring the category layer for HRIS only is a two-line change. Also added:
  • contextual.options (copy, view, chatgpt, claude) - the unused Mintlify AI features in §4.2. This gives the per-page “copy as markdown / open in Claude” menu, addressing the “can I give context to my coding agent?” builder gap.
  • Global anchors linking to status.bindbee.dev and trust.bindbee.dev (§2.1 security question).

​
API Reference is five groups

Platform holds everything that is not scoped to a product category, matching the assessment’s §7.1 tree (“Platform - fixed for all selector changes”, with Custom Fields and Supplemental nested inside it). An earlier draft broke Webhooks, Custom Fields and Supplemental out as siblings of HRIS/ATS/LMS, which wrongly implied they were peers of the product APIs. Nesting is capped at two levels everywhere: group → resource → endpoints. Every top-level group carries a FontAwesome icon.
Mintlify constraint: the expanded property only affects nested groups. Top-level groups always render expanded and cannot be collapsed. So API Basics / Platform / HRIS / ATS / LMS are permanent section headers; the resource groups inside them (Employee, Connectors, Passthrough…) are the collapsible dropdowns, collapsed by default. To make the products themselves collapsible they would have to become nested groups under a single top-level wrapper - which re-adds the nesting level removed earlier. Not done; flagged as a trade-off.

​
Custom Fields pages split by type

The Custom Fields section mixed reference and guidance. It is now split by what each page is: No files moved on disk - URLs unchanged. See open item 8 for the content overlap this exposes.

​
One page merged, one redirect added

sdk/integrations.mdx and the connector coverage page were merged into a single /integrations page - slugs, connection type, models, and how to check a live connector’s real coverage now live in one place. A redirect from /sdk/integrations keeps the old URL working. Every other existing URL is unchanged: no other files were moved or renamed, only re-parented in navigation.

​
New content (32 pages)

Get Started (get-started/) - the 2/10 Tutorials quadrant
  • what-is-bindbee.mdx
  • quickstart.mdx - signup → first unified employee record, ~10 min, with a troubleshooting table
  • core-concepts.mdx
  • tutorials/connect-your-first-customer.mdx
  • tutorials/read-employee-data.mdx
  • tutorials/read-benefits-and-payroll-data.mdx
  • tutorials/handle-webhooks.mdx
  • tutorials/write-data-back.mdx
Explanation (explanation/) - the other 2/10 quadrant
  • how-syncing-works.mdx
  • connector-lifecycle.mdx
  • data-freshness.mdx
  • hris-model-relationships.mdx
  • benefits-models.mdx - Benefit vs Employer Benefit vs Dependent Benefit
  • field-semantics.mdx - answers “why is [field] null?” and “modified_at updated but the data didn’t change”, both marked Not addressed in the assessment
  • passthrough-when-and-why.mdx
  • custom-fields-mental-model.mdx
  • meta-api-schema-discovery.mdx
  • sftp-vs-api.mdx
  • webhooks-vs-polling.mdx
  • security-and-compliance.mdx
How-To (how-to/)
  • authenticate.mdx - the step-by-step path the assessment flagged as broken
  • install-sdks.mdx
  • paginate.mdx
  • filter-with-modified-after.mdx
  • map-custom-fields.mdx
  • use-passthrough.mdx
  • handle-errors.mdx
  • validate-webhook-signatures.mdx
  • monitor-sync-status.mdx
  • force-a-resync.mdx
  • go-live-checklist.mdx
Root
  • integrations.mdx - merged integration slug list + coverage guidance

​
Roadmap coverage (assessment §6)

​
Open items needing product/engineering confirmation

These are the places where the repo did not contain enough information to write something verifiable. Everything else in the new content is grounded in spec.json, existing pages, or the OpenAPI schemas.

​
1. Connector coverage matrix - per-connector model/field support

integrations.mdx lists every integration, its slug, and its connection type (API vs SFTP) - all verifiable from the previous integrations page. It does not contain a per-connector × per-model support grid, because that data lives in the portal, not in this repo. The page currently teaches readers to query coverage themselves via /api/{category}/v1/integrations and per-model probe requests. That is honest and useful, but it is not the searchable matrix the assessment asks for. To finish it: export the model/field support data from the portal and render it as a filterable table. If an endpoint exposing it exists or is planned, the page should link to it.

​
2. SDK claim (Python / Node / Go)

The assessment notes the website mentions SDKs that aren’t in the docs. I could only verify two Bindbee-published packages in this repo:
  • @bindbee/react-link (npm) - frontend Embed hook
  • https://cdn.bindbee.dev/initialize.min.js - frontend Embed via CDN
I found no evidence of server-side SDKs for Python, Node or Go. how-to/install-sdks.mdx therefore documents the two verified frontend packages and provides a production-shaped HTTP client (retry, pagination, both auth headers) in Python, Node and Go instead of claiming SDKs that may not exist. Action required: confirm whether server-side SDKs exist.
  • If they do → replace the hand-rolled clients on that page with install instructions.
  • If they don’t → the website claim should be corrected.

​
3. Changelog - dropped by request

The changelog page was removed. This leaves the assessment’s maintainer question “Did Bindbee change something? Where’s the changelog?” unanswered - it was a P0 with “Exists for all” competitors. Two notes if it is ever revisited:
  • The gap is real but it is a process problem, not a docs problem. A changelog only helps if entries ship with the change; a stale one is worse than none.
  • The breaking-change policy is the part builders actually need, and it now has no home. Specifically: new enum values are additive and ship without notice, which is why field-semantics tells readers never to write an exhaustive switch over a Bindbee enum. Consider stating that policy somewhere permanent.

​
4. Sync internals

explanation/how-syncing-works.mdx describes the sync lifecycle from observable behaviour - status fields, sync_progress, webhook events, the 24-hour default. It deliberately does not claim whether syncs are full or incremental upstream, because the repo doesn’t say. If Bindbee does incremental extraction, saying so would strengthen the page. Worth an engineering review pass.

​
5. Security certifications

explanation/security-and-compliance.mdx covers API-level security (credential scope, environment isolation, regions, webhook signing, shared responsibility) and points at trust.bindbee.dev as the authority for SOC 2 / HIPAA / GDPR rather than restating claims that would go stale. Confirm that is the preferred posture.

​
6. modified_after endpoint coverage

how-to/filter-with-modified-after.mdx notes the parameter is available across unified list endpoints. It is confirmed on /api/hris/v1/employees in spec.json; a sweep confirming which endpoints accept it would let that hedge be removed.

​
8. Custom Fields content overlap

Re-filing the Custom Fields guides by type put them next to the new pages, which makes a real duplication visible: Both pairs are now adjacent in the sidebar, so a reader sees two answers to the same question. The existing pages are good and were written recently - this is not a quality problem, it is a “say it once” problem. Suggested resolution: keep custom-fields/overview.mdx as the conceptual page and fold the unique parts of the new mental-model page into it; keep how-to/map-custom-fields.mdx as the task page and let dashboard.mdx / api-workflow.mdx become the tool-specific detail it links to. Left alone pending a decision, since it means editing pages that were not part of this restructure.

​
7. Help Center

The assessment proposes help.bindbee.dev (§7.2). It does not appear to exist yet, so it is not linked from the nav - a dead nav link is worse than an absent one. Add the global anchor once it’s live.

​
Pre-existing issues found (not introduced by this work)

None were changed, since they’re outside the restructure scope. The Discord-hosted images are the most urgent - those URLs expire.

​
Verification performed

Recommend a mintlify dev run before merging to confirm rendering.