Skip to main content
This is the path a successful Bindbee setup follows. Three steps are optional; the rest apply to every integration.
Before you start
  • You have a Bindbee account and an API key for the environment you’re building against.
  • You know which models your use case needs.

​
Steps

1

Set up scoping for your use case

Turn on only the models and fields you actually need. Scoping decides what syncs, so it is easier to get right now than to change later.Result: The connector requests your models and nothing else. See Scoping.
2

Create the connector

Pick one path - a Magic Link you send to the customer, or the Embedded SDK inside your own product.Result: The customer authorizes, and the connector moves to COMPLETE. See Connection methods.
3

Subscribe to connector.sync.started (Optional)

Fires the moment a sync begins, which is what you need to show “importing your data…” in your UI.Result: Your endpoint receives an event at the start of every run. See Create a webhook.
4

Poll the Connectors API (Optional)

Reads status and sync_status for a connector when you need to check where a connection stands.
Result: The current state of every connection. See Get Connectors.
5

Fetch attached custom fields (Optional)

Where you have mapped custom fields, read the mappings so you know what extra data arrives with each record.Result: The list of extensions on each model. See Custom fields via API.
6

Subscribe to connector.sync.completed (Recommended)

This is the signal that a sync has finished and the data is ready to read. Verify the signature on every request and reply within 10 seconds.Result: You learn the moment a connector’s data is complete, rather than polling for it. See Webhook events.
7

Read once the webhook arrives

Pull the models you scoped, paging until cursor is null.Result: The full census for that customer.
The limit is 200 requests per minute per connector, counted against the connector token. Set your own concurrency below that - see Rate limits.

​
After the first sync

The first full read gives you the complete census. From then on you only need the delta, and there are two ways to get it:
  • Subscribe to the created and updated events of each model you read, such as hris.employee.updated, and read the record IDs they hand you - see Webhook events.
  • Pass modified_after with the highest modified_at you saw on the previous run.
Either way, upsert on id - you will receive the same record more than once.

​
Frequently Asked Questions

The first sync runs on connection, and a large population takes time. Check the run in Sync status before assuming the webhook failed.
You can, but the data is incomplete until the run finishes. Gate on connector.sync.completed rather than a timer - see Syncing.
Read its per-model status on the run. Skipped and Not Supported both return an empty set with no error - see Sync status.