fastify-xplaid

identity.get

Get identity data — names, emails, phone numbers, and addresses — for all accounts on a Plaid Item.

identity.get

Returns identity information associated with the accounts on a Plaid Item — full names, email addresses, phone numbers, and mailing addresses as held by the financial institution. Requires the identity product to have been enabled when creating the Link token.

Signature

fastify.xplaid.identity.get(
  accessToken: string,
  options?: {
    accountIds?: string[]
  }
): Promise<{
  accounts: PlaidAccountWithOwners[]
  item: PlaidItem
  requestId: string
}>

Params

Name	Type	Required	Description
`accessToken`	`string`	Yes	The Item's permanent access token.
`options.accountIds`	`string[]`	No	Restrict results to specific account IDs. Omit to return identity for all accounts.

Returns

Promise<{ accounts: PlaidAccountWithOwners[], item: PlaidItem, requestId: string }>

Each account in accounts extends the standard PlaidAccount shape with an owners array:

Field	Type	Description
`account_id`	`string`	Stable Plaid account identifier.
`name`	`string`	Account display name.
`owners`	`Identity[]`	One or more identity records for account owners.
`owners[].names`	`string[]`	Legal names on the account.
`owners[].emails`	`Email[]`	Email addresses with `data` and `type` fields.
`owners[].phone_numbers`	`PhoneNumber[]`	Phone numbers with `data` and `type` fields.
`owners[].addresses`	`Address[]`	Mailing addresses with `data` (street, city, region, postal_code, country) and `primary`.

Throws

[xPlaid] accessToken is required and must be a non-empty string — when accessToken is missing or empty.
Plaid API errors wrapped via wrapPlaidError — shape: { message, statusCode, plaidError }.
PRODUCTS_NOT_SUPPORTED Plaid error if identity was not included in the Link token's products.
ITEM_LOGIN_REQUIRED Plaid error if the Item needs re-authentication.

Examples

Basic — retrieve owner names and emails

const { accounts } = await fastify.xplaid.identity.get(accessToken);

for (const account of accounts) {
  for (const owner of account.owners) {
    console.log(owner.names);     // ["Jane Doe"]
    console.log(owner.emails);    // [{ data: "jane@example.com", type: "primary" }]
    console.log(owner.addresses); // [{ data: { street: "...", city: "..." }, primary: true }]
  }
}

Realistic — KYC verification route

fastify.get("/kyc/identity", async (request, reply) => {
  const item = await db.plaidItems.findFirst({ where: { userId: request.user.id } });
  if (!item) return reply.status(404).send({ error: "No linked account" });

  try {
    const { accounts } = await fastify.xplaid.identity.get(decrypt(item.accessToken));

    // Collect all unique identity data across all accounts
    const owners = accounts.flatMap((a) => a.owners);
    const names = [...new Set(owners.flatMap((o) => o.names))];
    const emails = [...new Set(owners.flatMap((o) => o.emails.map((e) => e.data)))];
    const phones = [...new Set(owners.flatMap((o) => o.phone_numbers.map((p) => p.data)))];
    const primaryAddress = owners
      .flatMap((o) => o.addresses)
      .find((a) => a.primary)?.data;

    return { names, emails, phones, primaryAddress };
  } catch (error) {
    if (error.plaidError) {
      const { error_type, error_code } = error.plaidError;
      if (error_type === "ITEM_ERROR") {
        return reply.status(428).send({ error: "reauth_required", error_code });
      }
      request.log.error({ error_code }, "Identity fetch failed");
      return reply.status(error.statusCode ?? 500).send({ error: error.message });
    }
    throw error;
  }
});

Filter to a specific account

const { accounts } = await fastify.xplaid.identity.get(accessToken, {
  accountIds: ["9Bgamla7y6FnMkVb4XWvIqDo3yBxLPCDgmGoN"],
});
const primaryAddress = accounts[0]?.owners[0]?.addresses.find((a) => a.primary)?.data;

AI Context

package: "@xenterprises/fastify-xplaid"
method: fastify.xplaid.identity.get(accessToken, options?)
use-when: Get identity data (names, emails, phone numbers, addresses) from the linked bank account — requires "identity" product
returns: { accounts: [ { account_id, owners: [ { names, emails, phone_numbers, addresses } ] } ] }

Edit this pageorReport an issue

auth.get

Get ACH routing numbers and account numbers for all accounts on a Plaid Item.

investments.getHoldings(accessToken, options?)

Get current investment holdings and security metadata for a Plaid Item.