Skip to main content

Retrieve Institution User (V2)

Loading...
API endpoint path: /v2/institution-users/{institutionUserId}

Returns profile and relationship data for a single financial institution user, with FI-scoped encryption applied to personally identifiable information (PII). The response includes identity fields (name, email, username), user status, role, user type, associated institution customers, and login activity indicators. For business banking users, entitled location information may also be included.

Use this endpoint to:

  • Look up a user by institution user ID, host user ID (member number), login ID, legacy user GUID, or authentication user ID (authId).
  • Include the institution user's contact methods, postal addresses, sub-users, and identification documents by specifying them in the $expand query parameter using OData expressions.
  • Retrieve FI-encrypted identification documents when the Apigee application includes the institution-users:read_pii scope.

Behavior and capabilities:

  • userIdType defaults to INSTITUTION_USER_ID when not specified. Set it to match the identifier provided in institutionUserId. HOST_USER_ID is not applicable to business banking users.
  • $expand accepts OData expressions provided as a single string. Supported segments include contactMethods, postalAddresses, subUsers, and identificationDocuments. postalAddress is also accepted as an alias for postalAddresses. Optional $filter clauses are supported on each segment.
  • Expanding identificationDocuments requires the institution-users:read_pii scope. Apigee applications that request this segment without this scope receive a 403 Forbidden error.
  • Identification document values are encrypted using the financial institution's encryption key (FI-scoped encryption). A deterministic error is returned if the FI encryption key is not provisioned. Vendors or third-party clients must work with the financial institution to obtain the necessary encryption key for decryption.
  • Bill pay credential retrieval is not supported in V2, see Retrieve Institution User (V1) for more information.

Request​

Responses​

Success