Stitch aims to build an intuitive API. However, our API also needs to model how the real world behaves. These two goals sometimes conflict.
One nuance that we've found sometimes confuses people, is what is the difference between the
User.identity field and
BankAccount.accountHolder field? The query below shows that they
share many of the same fields, after all. What gives?
identity field makes a best-effort to verifiably retrieve the details of the human
who actually linked their bank with Stitch. Sometimes retrieving these details is not possible.
accountHolder field, in contrast, returns the entity who actually is the registered owner
of the account. This may in many cases have the same value as the
identity field, but could
also be a
Business, or perhaps even another
Individual if the linked user had been granted delegate
access to another human's account.
You should use the
identity field only if you want to verify the identity of the
individual who linked their account with Stitch.
It is not always possible to determine the user identity, so
is generally preferred for most use cases.
accountHolder field is more versatile (supports the
and is tied to the account itself, so should be preferred in scenarios
where bank account verification is also desired.
Stitch's comprehensive filtering API makes it a lot more ergonomic to work with account holders.
For example if you're only interested in
Business account holders,
you can filter by typename to have the API only return business accounts: