---
name: Bindbee
description: Use when building integrations with HRIS, Payroll, ATS, or LMS systems; reading or writing employee, candidate, or learning data; configuring custom fields; managing connectors; or setting up webhooks for real-time sync notifications.
metadata:
    mintlify-proj: bindbee
    version: "1.0"
---

# Bindbee Skill

## Product summary

Bindbee is a unified API platform for B2B integrations with HRIS, Payroll, ATS, and LMS systems. It abstracts away 100+ third-party integrations behind standardized endpoints, so you can read and write employee data, candidate records, and learning information without building connector-specific code. Key files and endpoints: API keys stored in dashboard settings; connectors created via Magic Link; data accessed via `/api/{category}/v1/{model}` endpoints (HRIS, ATS, LMS categories); custom fields configured via `/api/v1/custom-fields` endpoints; webhooks managed in dashboard. Primary docs: https://docs.bindbee.dev

## When to use

Reach for this skill when:
- Building integrations that read employee, payroll, candidate, or learning data from third-party systems
- Creating or updating records (employees, candidates, time off, payroll runs) in customer systems
- Extending unified models with custom fields to capture integration-specific data
- Setting up real-time sync notifications via webhooks
- Debugging connector issues, viewing logs, or checking sync status
- Configuring connectors for end users via Magic Link
- Working with Development or Production environments and managing API keys

## Quick reference

### Authentication headers

| Use case | Header | Format |
|----------|--------|--------|
| Organization-level API calls | `Authorization` | `Bearer YOUR_API_KEY` |
| End-user data access | `X-Connector-Token` | `END_USER_CONNECTOR_TOKEN` |
| Idempotent writes | `X-Idempotency-Key` | Any unique string per request |

### API categories and base URLs

| Category | Base URL | Models |
|----------|----------|--------|
| HRIS | `https://api.bindbee.dev/api/hris/v1` | employees, benefits, payroll runs, time off, compensation, etc. |
| ATS | `https://api.bindbee.dev/api/ats/v1` | candidates, jobs, applications, offers, interviews, etc. |
| LMS | `https://api.bindbee.dev/api/lms/v1` | users, courses, enrollments, completions, skills, etc. |

### Common query parameters

- `page_size`: Number of results per page (max 200, default 50)
- `cursor`: Pagination cursor for next page
- `include_raw_data`: Include original third-party payload (boolean)
- `include_custom_fields`: Include custom field values (boolean)
- `modified_after`: Filter by modification date (ISO 8601)

### Rate limits

- 200 requests per minute per API key
- Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
- 429 status code when exceeded; retry after reset time

### Connector states

| Status | Meaning |
|--------|---------|
| COMPLETE | Connector linked and ready |
| INCOMPLETE | Connector not yet fully authorized |
| RELINK_NEEDED | Credentials expired; user must re-authorize |

### Sync status

| Status | Meaning |
|--------|---------|
| Syncing | Data sync in progress |
| Done | Last sync completed successfully |
| Failed | Last sync encountered an error |

## Decision guidance

### When to use Organization-level vs Connector-scoped custom fields

| Scenario | Use organization-level | Use connector-scoped |
|----------|------------------------|---------------------|
| Same field across all connectors of an integration | ✓ | |
| Field mapping differs per connector instance | | ✓ |
| Replicating config across environments | ✓ | |
| One-off override for a specific customer | | ✓ |

### When to use Dashboard vs API for custom fields

| Task | Dashboard | API |
|------|-----------|-----|
| Ad-hoc field setup | ✓ | |
| Exploring raw payloads interactively | ✓ | |
| Infrastructure-as-code / version control | | ✓ |
| Automating field provisioning | | ✓ |
| Replicating config across environments | | ✓ |

### When to use Magic Link vs direct connector creation

| Scenario | Magic Link | Direct API |
|----------|-----------|-----------|
| End-user authorization flow | ✓ | |
| Programmatic connector creation | | ✓ |
| Testing in Development environment | Either | |
| Production customer integrations | ✓ | |

## Workflow

### Typical task: Read employee data from a customer's HRIS

1. **Verify connector exists and is active**
   - Call `GET /api/hris/v1/connectors` with your API key to list connectors
   - Check `status` is `COMPLETE` and `sync_status` is `Done`
   - Extract the `connector_token` from the response

2. **Fetch employees**
   - Call `GET /api/hris/v1/employees` with `X-Connector-Token` header
   - Use `page_size` and `cursor` for pagination
   - Add `include_raw_data=true` to debug field mappings
   - Add `include_custom_fields=true` if custom fields are configured

3. **Handle pagination**
   - Check response `cursor` field; if not null, more results exist
   - Use cursor value in next request to fetch next page

4. **Verify data quality**
   - Check `modified_at` timestamps to confirm sync freshness
   - If `raw_data` is included, inspect it against custom field JMESPath expressions
   - Review logs in dashboard if data looks incorrect

### Typical task: Create a custom field for employee data

1. **Discover available models and integrations**
   - Call `GET /api/v1/lookup/models?category=HRIS` to list available models
   - Call `GET /api/v1/lookup/integrations?category=HRIS` to list integrations

2. **Inspect raw upstream payload**
   - Call `GET /api/v1/custom-fields/raw-data?category=HRIS&model=employee&integration_slug=workday`
   - Examine the JSON structure to identify the field path

3. **Validate JMESPath expression (optional but recommended)**
   - Call `POST /api/v1/custom-fields/preview` with your JMESPath
   - Confirm `resolved_value_type` matches your expectation
   - If `raw_data_source` is `integration_sample`, connector hasn't synced yet

4. **Create the custom field**
   - Call `POST /api/v1/custom-fields` with `name`, `category`, `model`, optional `description`
   - Store the returned `id`

5. **Create a mapping**
   - Call `POST /api/v1/custom-fields/mapping` with `custom_field_id`, `json_path`, and either `integration_slug` (org-level) or `connector_token` (connector-level)

6. **Verify configuration**
   - Call `GET /api/v1/custom-fields/configuration?connector_token=...&category=HRIS&model=employee`
   - Confirm `json_path` is set and `source` shows which mapping is active
   - Check for unmapped fields with `json_path: null`

### Typical task: Set up webhooks for sync notifications

1. **Navigate to Webhooks in dashboard**
   - Go to https://app.bindbee.dev/webhooks
   - Click "New webhook"

2. **Configure destination and events**
   - Enter your endpoint URL (must respond within 10 seconds)
   - Select webhook type: Production or Development
   - Check desired events: sync started, sync error, sync completed, employee data changed, connector data modified

3. **Secure your endpoint**
   - Retrieve your webhook signature key from the Security section
   - On incoming POST, compute HMAC-SHA256 of request body with signature key
   - Compare computed digest (base64-encoded) with `X-Bindbee-Webhook-Signature` header
   - Reject if signatures don't match

4. **Handle retries**
   - Bindbee retries failed webhooks up to 4 times within 60 seconds
   - Each attempt has 10-second timeout
   - Respond with 2xx status to acknowledge receipt

## Common gotchas

- **Forgetting connector token in data requests**: All end-user data reads/writes require `X-Connector-Token` header, not just the API key. 403 errors usually mean wrong token or wrong API category.
- **Using development key in production**: Dev and prod API keys are environment-specific and cannot be mixed. Regenerating a key immediately invalidates the old one.
- **Connector status RELINK_NEEDED**: Credentials expired; user must re-authorize via Magic Link. No data operations will succeed until relinked.
- **Development connectors don't auto-sync**: Syncs are manual or programmatic only in Development. Use `POST /api/embedded/v1/connectors/resync` to trigger manually.
- **Invalid JMESPath in custom fields**: If expression is invalid or fails to resolve, responses contain `"INVALID_JSON_PATH"` instead of raising an error. Always preview before saving.
- **Connector-level mappings override org-level**: If both exist for the same field, connector-scoped mapping wins. Check `source` field in configuration response to see which is active.
- **Rate limit headers are advisory**: `X-RateLimit-Remaining` tells you how many requests are left; use `X-RateLimit-Reset` to know when to retry after hitting 429.
- **Pagination cursor is opaque**: Don't parse or construct cursor values; use them as-is from the response.
- **Custom field names must be snake_case**: Names like `guardian_mobile` are valid; `guardianMobile` or `guardian-mobile` will fail.
- **Webhook signature verification is mandatory**: Always validate `X-Bindbee-Webhook-Signature` to prevent accepting spoofed webhooks.

## Verification checklist

Before submitting work with Bindbee:

- [ ] API key is stored securely and never committed to version control
- [ ] Correct environment (dev vs prod) API key is used for the target environment
- [ ] All data requests include `X-Connector-Token` header when accessing end-user data
- [ ] Connector status is `COMPLETE` and sync status is `Done` before reading data
- [ ] Custom field JMESPath expressions have been previewed and validated
- [ ] Custom field mappings are scoped correctly (org-level vs connector-level)
- [ ] Webhook endpoint responds within 10 seconds and returns 2xx status
- [ ] Webhook signature validation is implemented and tested
- [ ] Pagination is handled correctly (cursor-based, not offset-based)
- [ ] Rate limit headers are monitored; retry logic respects `X-RateLimit-Reset`
- [ ] Error responses are logged; 422 validation errors include field-level details
- [ ] Idempotency keys are used for write operations to prevent duplicates
- [ ] Raw data and custom fields are only requested when needed (performance)

## Resources

- **Full page navigation**: https://docs.bindbee.dev/llms.txt
- **API Authentication**: https://docs.bindbee.dev/api-reference/basics/authentication
- **Custom Fields Guide**: https://docs.bindbee.dev/custom-fields/overview
- **Webhooks Setup**: https://docs.bindbee.dev/webhooks/overview

---

> For additional documentation and navigation, see: https://docs.bindbee.dev/llms.txt