> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

1. [Creating a `user`](/api-reference/atrium/reference/members/overview);
2. [Creating a `member`](/api-reference/atrium/reference/members/overview) using the correct institution code and credentials required by that institution; set `skip_aggregation` to `true`;
3. [Polling the member's `connection_status`](/api-reference/atrium/reference/members/connection-status) and answering MFA if necessary;
4. Reading the member's `account_owners` (you may begin with this step for members that already exist);
5. Calling the identify endpoint, if needed;
6. 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](/other/atrium).

For important information on errors, standards and conventions, and resource structure in Atrium, please see our [technical reference page](/api-reference/atrium).

## 1. Create a User

For further details on users, click [here](/api-reference/atrium/reference/members/overview).

**Endpoint**: `POST /users`

<CodeGroup>
  ```shell Request theme={null}
  curl -i -X POST 'https://vestibule.mx.com/users' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'Content-Type: application/json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}' \
    -d '{
          "user": {
            "identifier": "unique_id",
            "metadata": "{\"first_name\": \"Steven\"}"
          }
        }'
  ```

  ```json Response theme={null}
  {
    "user": {
      "guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
      "identifier": "unique_id",
      "is_disabled": false,
      "metadata": "{\"first_name\": \"Steven\"}"
    }
  }
  ```
</CodeGroup>

## 2. 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](/api-reference/atrium/reference/institutions/overview).

**Endpoint**: `GET /institutions`

<CodeGroup>
  ```shell Request theme={null}
  curl -i 'https://vestibule.mx.com/institutions?name=mx' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "institutions": [
      {
        "code": "mxbank",
        "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-1572a04c-912b-59bf-5841-332c7dfafaef_100x100.png",
        "name": "MX Bank",
        "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-1572a04c-912b-59bf-5841-332c7dfafaef_50x50.png",
        "supports_account_identification": true,
        "supports_account_statement": false,
        "supports_account_verification": true,
        "supports_oauth": false,
        "supports_transaction_history": true,
        "url": "https://www.mx.com"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total_entries": 1,
      "total_pages": 1
    }
  }
  ```
</CodeGroup>

## 3. Get The Institution's Required Credentials Using the Institution Code

**Endpoint**: `GET /institutions/{institution_code}/credentials`

<CodeGroup>
  ```shell Request theme={null}
  curl -i 'https://vestibule.mx.com/institutions/mxbank/credentials' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "credentials": [
      {
        "display_order": 0,
        "field_name": "login_email",
        "guid": "CRD-12ce94ad-032b-5441-8cb3-d7ebe3a35676",
        "label": "Email Address",
        "type": "LOGIN"
      },
      {
        "display_order": 1,
        "field_name": "login_password",
        "guid": "CRD-305767e4-f464-765b-8f83-881b5bd307ec",
        "label": "PayPal password",
        "type": "PASSWORD"
      }
    ]
  }
  ```
</CodeGroup>

## 4. 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](/api-reference/atrium/reference/members/overview)

**Endpoint**: `POST /users/{user_guid}/members`

<CodeGroup>
  ```shell Request theme={null}
  curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'Content-Type: application/json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}' \
    -d '{
          "member": {
            "institution_code": "mxbank",
            "credentials": [
              {
                "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
                "value": "ExampleUsername"
              },
              {
                "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
                "value": "Pa$$vv@Rd"
              }
            ],
            "skip_aggregation": true
          }
        }'
  ```

  ```json Response theme={null}
  {
    "member": {
      "aggregated_at": "2016-10-13T17:57:36+00:00",
      "connection_status": "CONNECTED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "unique_id",
      "institution_code": "mxbank",
      "is_being_aggregated": true,
      "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
      "name": "MX Bank",
      "status": "INITIATED",
      "successfully_aggregated_at": null,
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  }
  ```
</CodeGroup>

## 5. 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`

<CodeGroup>
  ```shell Request theme={null}
  curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/status' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "member": {
      "aggregated_at": "2019-06-08T17:21:05Z",
      "connection_status": "CONNECTED",
      "guid": "MBR-a4652b66-3ee5-cb9f-295a-72eddef61db5",
      "has_processed_accounts": true,
      "has_processed_transactions": true,
      "is_authenticated": true,
      "is_being_aggregated": false,
      "status": "COMPLETED",
      "successfully_aggregated_at": "2019-06-07T21:16:03Z"
    }
  }
  ```
</CodeGroup>

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](/api-reference/atrium/reference/members/overview).

**Endpoint**: `GET /users/{user_guid}/members/{member_guid}/credentials`

<CodeGroup>
  ```shell Request theme={null}
  curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/challenges' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "challenges": [
      {
        "field_name": "What city were you born in?",
        "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
        "label": "What city were you born in?",
        "type": "TEXT"
      }
    ]
  }
  ```
</CodeGroup>

## 6. 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](/api-reference/atrium/) or our [troubleshooting guide](/other/atrium/getting-started#aggregating-data-and-dealing-with-mfa).

**Endpoint**: `PUT /users/{user_guid}/members/{member_guid}/resume`

<CodeGroup>
  ```shell Request theme={null}
  curl -i -X PUT 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/resume' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'Content-Type: application/json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}' \
    -d '{
          "member":{
            "challenges":[
              {
                 "guid": "institution-credential-guid",
                 "value": "user-entered-value"
              },
              {
                "guid": "institution-credential-guid",
                 "value": "user-entered-value"
              }
            ]
          }
        }'
  ```

  ```json Response theme={null}
  {
    "member": {
      "aggregated_at": "2016-09-30T14:31:45-06:00",
      "connection_status": "RESUMED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier":"unique_id",
      "institution_code": "mxbank",
      "is_being_aggregated": true,
      "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
      "name": "MX Bank",
      "status": "RECEIVED",
      "successfully_aggregated_at": null,
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  }
  ```
</CodeGroup>

## 7. Identify The Member

The identify endpoint begins an identification process for an already existing `member`.

**Endpoint**: `POST /users/{user_guid}/members/{member_guid}/identify`

<CodeGroup>
  ```shell Request theme={null}
  curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/identify' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'Content-Type: application/json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "member": {
      "aggregated_at": "2018-06-25T20:04:19Z",
      "connection_status": "CONNECTED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "mxbank_ds",
      "institution_code": "mxbank",
      "is_being_aggregated": true,
      "is_oauth": false,
      "metadata": null,
      "name": "MX Bank",
      "status": "INITIATED",
      "successfully_aggregated_at": "2018-06-25T19:45:01Z",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  }
  ```
</CodeGroup>

## 8. List The Account Owners

**Endpoint**: `GET /users/{user_guid}/members/{member_guid}/account_owners`

<CodeGroup>
  ```shell Request theme={null}
  curl -i 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/account_owners' \
    -H 'Accept: application/vnd.mx.atrium.v1+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "account_owners": [
      {
        "guid": "ACO-123",
        "user_guid": "USR-123",
        "member_guid": "MBR-123",
        "account_guid": "ACT-123",
        "owner_name": "Donnie Darko",
        "address": "123 This Way",
        "city": "Middlesex",
        "state": "VA",
        "postal_code": "00000-0000",
        "country": "US",
        "email": "donnie@darko.co",
        "phone": "555-555-5555"
      },
      {
        "guid": "ACO-456",
        "user_guid": "USR-123",
        "member_guid": "MBR-123",
        "account_guid": "ACT-123",
        "owner_name": "Susan Darko",
        "address": "456 That Way",
        "city": "Middlesex",
        "state": "VA",
        "postal_code": "00000-0000",
        "country": "US",
        "email": "susan@darko.co",
        "phone": "555-555-5555"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 25,
      "total_entries": 2,
      "total_pages": 1
    }
  }
  ```
</CodeGroup>

## Testing Account Owner Identification

To [test your setup](/other/atrium/testing-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`