Most documentation assumes one customer means one connector. For a meaningful share of mid-market and enterprise customers it does not, and a data model built on the one-to-one assumption is expensive to unwind later.
Why one customer needs several connectors
origin_id is the thread between them
You set origin_id when generating the Magic Link, and it should be your own stable tenant identifier - not a name, not an email. It is carried on the connector, appears in every webhook payload, and is a filter on the connector list:
That one request returns every connector belonging to that customer, which is what makes the fan-out tractable. Three entities under “Acme Corp.” share one origin_id and come back together.
So the grouping is not absent from the platform - you supply the key, and Bindbee stores, returns and filters on it. What the platform does not do is attach any meaning to it.
What stays your job
Each connector authorizes separately, syncs on its own schedule, holds its own credentials, and can break on its own. Sharing an origin_id changes none of that.
Health is per connector. One broken connector means partial data, and your monitoring has to express that. A customer with three connectors, one broken for a month, looks fine at a glance and is missing a third of their people.
Coverage is the intersection. If one entity runs a system that does not expose benefits, that capability is absent for those employees no matter what the other connectors support.
Reads fan out. Employees for a customer means reading every connector under that origin_id and combining the results yourself.
People appear more than once
The same human employed by two entities in a group, or present in both an HRIS and a payroll system, exists as separate records under separate connectors with different identifiers.
Bindbee will not merge them - identity is resolved within a connector and nowhere else. Deduplicating across connectors is your application’s job, and it needs a matching strategy that does not lean on the source identifier, since each system assigns its own.
Headcount and any billing derived from record counts must deduplicate across connectors. Counting records across a multi-entity customer overstates their size, sometimes substantially.
Why it works this way
The platform gives you the key but not the semantics, because only you know what the grouping means.
Whether two tenants are one customer or two depends on your contract, your billing, and how you model the relationship - and different products in the same position answer it differently. A group with three subsidiaries might be one account or three. origin_id lets you assert the answer; inferring it would mean guessing.
Keeping connectors independent underneath that also keeps failure isolated. One entity’s credentials expiring does not affect the others, and the customer re-authorizes just that one rather than everything.
The cost is that you own the fan-out - aggregating health, intersecting coverage, deduplicating people. That work follows from the grouping being yours to define; what the platform can do is make each connector behave predictably in isolation, and give you one identifier to gather them by.
What this means for you
- Set
origin_id to your internal tenant ID at Magic Link time. It is the join key back to your own database, and it is hard to correct later.
- Model customer-to-connectors as one-to-many from the start. Retrofitting is expensive.
- Fan out with
origin_id rather than maintaining your own connector-to-customer mapping table.
- Aggregate connector health per customer. One broken connector is partial data, not total failure.
- Deduplicate people across connectors using stable attributes rather than source identifiers.
- Do not derive headcount or billing from raw record counts for multi-entity customers.
