Work with identity data

The identity endpoint returns customer profile information retrieved from an institution as part of a consent. This page explains the structure of the response and how it behaves when a user has connected multiple institutions.

Person vs organisation identities

An institution returns a customer identity as either a person or an organisation — not both. The type is determined by the kind of account held at that institution: a retail customer produces a person identity, while a business account holder produces an organisation identity.

Identity data is scoped per consent. If a user grants consent for a business account at one institution and a personal account at another, each returns its own identity type.

The identity endpoint

GET /v1/common/identity?end_user_id={end_user_id}

The response contains an identities array with the customer identities available for that end user. You can pass an optional institution_id query parameter to scope the result to a single institution. See the API reference for the full schema.

Handling multiple identities

When a user has connected more than one institution, you may receive multiple identity objects rather than a single merged profile. Don't assume they refer to the same person — one may be a person identity and another an organisation identity, depending on what each institution returned.

Your application should handle the array and select the identity most relevant to your use case — for example, the identity from the most recently created consent, or from the primary institution your product relies on.

Fields returned

• Persons: given names, family name, middle names, prefix and suffix, occupation, and phone, email, and address details.
• Organisations: organisation name, business identifiers, industry classification, and contact details.

Not all institutions return all fields. Some values may be null or absent even when an identity object is present.

Why identity data can be missing

An empty result for a given consent can mean:

• The institution hasn't returned the customer data yet — the initial sync may still be in progress.
• The institution doesn't support the customer identity endpoint.
• The consent's scope didn't include identity data.