Account Owner Identification
Account Owner Identification is offered in the context of the Atrium API and relies on the resources of that RESTful API to function properly. Specifically, this means following the general workflow below:
- Creating a
user; - Creating a
memberusing the correct institution code and credentials required by that institution; setskip_aggregationtotrue; - Polling the member's
connection_statusand answering MFA if necessary; - Reading the member's
account_owners(you may begin with this step for members that already exist); - Calling the identify endpoint, if needed;
- Repeating steps 3 and 4.
If an identification is already running, a 202 Accepted status will be returned. If another aggregation-type process is already running — like standard aggregation or extended transaction history — a 409 Conflict will be returned.
For more information on other similar processes, please see our developer guide
For important information on errors, standards and conventions, and resource structure in Atrium, please see our technical reference page.
Create a User
For further details on users, click here.
Endpoint: POST /users
Get the Institution Code
Only certain institutions support identification. To get a list of all institutions which support identification, append the following query string to your request URL: supports_account_identification=true.
For further details on institutions, click here.
Endpoint: GET /institutions
Get The Institution's Required Credentials Using the Institution Code
Endpoint: GET /institutions/{institution_code}/credentials
Create a Member Using The Institution Code and The Required Credentials
Creating a member automatically starts a standard aggregation unless the skip_aggregation parameter is set to true. On already-existing members, you can use the identify endpoint described below.
For further details on members, click here
Endpoint: POST /users/{user_guid}/members
Poll The Connection Status
A connection status of CONNECTED means that the member was successfully authenticated and aggregation has begun. The is_being_aggregated field will tell you whether aggregation has completed; the field will be true while aggregation is taking place and returns to false when aggregation is complete.
Endpoint: GET /users/{user_guid}/members/{member_guid}/status
If the aggregation has triggered MFA, the response will contain a field called challenges which contains an array of MFA questions that must be answered. There are several different types of challenges, each of which has an example to the right.
For further information on connection_status and related fields, click here.
Endpoint: GET /users/{user_guid}/members/{member_guid}/credentials
Answer MFA, If Necessary
If the connection_status returns as CHALLENGED during polling, it will be necessary to answer multi-factor authentication in order to continue. This requires calling the list member MFA challenges endpoint and the resume aggregation from MFA endpoint, then polling the connection_status again.
Further details on MFA, see our technical reference or our troubleshooting guide.
Endpoint: PUT /users/{user_guid}/members/{member_guid}/resume
Identify The Member
The identify endpoint begins an identification process for an already-existing member.
Endpoint: POST /users/{user_guid}/members/{member_guid}/identify
List The Account Owners
ENdpoint: GET /users/{user_guid}/members/{member_guid}/account_owners
Testing Account Owner Identification
To test your setup without incurring the cost of calling the identify endpoint, Atrium has test endpoints available.
Simply modify the URL to contain the user GUID test_atrium and the member GUID test_atrium_member.
The endpoint URLs will then be as follows:
/users/test_atrium/members/test_atrium_member/identify
/users/test_atrium/members/test_atrium_member/account_owners