Credential:  
None
  • None
  • Manage Credentials
Launch IDE ↗

Stitch API

4.9. Identity vs Accountholders

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 the BankAccount.accountHolder field? The query below shows that they share many of the same fields, after all. What gives?

The 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.

The 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.

When should I use identity

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 accountHolder is generally preferred for most use cases.

When should I use Account Holder

The accountHolder field is more versatile (supports the Business type), and is tied to the account itself, so should be preferred in scenarios where bank account verification is also desired.

Using filtering to query Account Holders effectively

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: