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

# Fetch Account Owner Data

> Get the name, address, and contact information for the owner of an account

<Note>
  **LEGACY GUIDE**

  This guide is for Platform API v2011101. For guidance on the newest version, see [Connectivity Integration Guides](/products/connectivity/overview/connectivity-integration-guides/).
</Note>

This guide takes you through the process of creating a user, connecting them to their financial institution, and returning Account Owner Identification (AOI) data using our API.

You can also use the Connect Widget for this, but not as a standalone process. When using the Connect Widget, you can only aggregate AOI data after aggregating data for Account Aggregation or Instant Account Verification. As such, this guide covers API-only flows. See our [aggregation](/products/connectivity/account-aggregation) and [IAV](/products/connectivity/instant-account-verification) guides for info on including AOI in Connect Widget integrations.

<Warning>
  **WARNING**

  Account Owner Identification data is not available for Capital One Credit Card accounts.
</Warning>

The workflow for getting AOI data is as follows:

1. Create a user.
2. Search for an institution.
3. Get the credentials required by the institution.
4. Create an OAuth or non-OAuth member, which connects the user to the institution.
5. Load the OAuth URI (if you created an OAuth member).
6. Start aggregating data.
7. Poll the member's connection status.
8. Answer multifactor authentication, if necessary.
9. Poll the member's connection status again until it reaches an end state. A successful end state is when the `connection_status` is `CONNECTED` and the `is_aggregating` field changes from `true` to `false`.
10. List the member's owner information or read a particular owner's information.

## 1. Create a User

A user represents your end user in the MX Platform. Make a request to the [Create User](/api-reference/platform-api/reference/create-user) endpoint (`POST /users`).

We recommend that you include a unique [`id`](/api-reference/platform-api/overview/formats-requirements#identifiers-and-metadata) of your choice with the request. You may also include `metadata`, such as the date the `user` was created or the end user's name. Don't include any sensitive information here, such as credentials.

<Info>
  **INFO**

  None of these parameters are required, but the `user` object can't be empty. We recommend that you always set the `id` parameter when creating a user.
</Info>

In the response, the API gives each new `user` an MX-defined `guid` (or `user_guid` when appearing outside the `user` object). Between your `id` and the `guid`, you can map between your system and ours. You'll need the user `guid` for nearly every request on the MX API, at least when using basic authorization.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i -X POST 'https://int-api.mx.com/users' \
    -u 'client_id:api_key' \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -H 'Content-Type: application/json' \
    -d '{
      "user": {
        "id": "partner-2345",
        "is_disabled": false,
        "email": "example@example.com",
        "metadata": "Some metadata"
      }
    }'

    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
    "user": {
    "email": "totally.fake.email@notreal.com",
    "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "id": "partner-2345",
    "is_disabled": false,
    "metadata": "Yada yada yada"
    }
    }

    ```
  </Tab>
</Tabs>

## 2. Search for an Institution

To create a member, you need to know what financial institution the member should be connected to and what type of credentials the institution expects to get.

First, search for an institution using query parameters on the [List Institutions endpoint](/api-reference/platform-api/reference/list-institutions) (`GET /institutions?name={string}&supports_account_identification=true`).

<Info>
  **INFO**

  The example searches for our test institution MX Bank (see [Testing](/resources/test-platform) for more information). It also limits results to institutions that support AOI.
</Info>

The response returns a paginated list of institutions that match the string you send in the `name` query parameter. Make a note of the `code` you find in the example response; you'll need this for the next step.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i 'https://int-api.mx.com/institutions?name=mx&supports_account_identification=true' \
    -u 'client_id:api_key' \
    -H 'Accept: application/vnd.mx.api.v1+json'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "institutions": [
        {
          "code": "mxbank",
          "forgot_password_url": null,
          "forgot_username_url": null,
          "instructional_text": null,
          "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_tax_document": false,
          "supports_transaction_history": true,
          "trouble_signing_in_url": null,
          "url": "https://www.mx.com"
        },
        {
          "code": "bank_of_mx_oauth",
          "forgot_password_url": null,
          "forgot_username_url": null,
          "instructional_text": null,
          "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
          "name": "Bank of MX (OAuth)",
          "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
          "supports_account_identification": true,
          "supports_account_statement": false,
          "supports_account_verification": true,
          "supports_oauth": false,
          "supports_tax_document": false,
          "supports_transaction_history": true,
          "trouble_signing_in_url": null,
          "url": "https://banksy.kube.int.internal.mx"
        }
      ],
      "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total_entries": 2,
        "total_pages": 1
      }
    }
    ```
  </Tab>
</Tabs>

## 3. Get the Institution's Required Credentials

<Info>
  **INFO**

  If you plan on creating an OAuth member, you can [skip this step](#4-create-a-member) since the user will instead log in directly through the financial institution's site.
</Info>

Each institution requires different types of credentials. Some require an email and a password, some require a username and a password, and some may require other types of credentials.

Make a request to the [List Institution Credentials endpoint](/api-reference/platform-api/reference/list-institution-credentials) (`GET /institutions/{institution_code}/credentials`). Include the institution code retrieved from the previous step in the request path.

This endpoint returns the `GUID` for each required credential, which is used to match the credentials the end user provides to the required credential type when creating a member.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -u 'client_id:api_key'

    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
    "credentials": [
    {
      "display_order": 1,
      "field_name": "LOGIN",
      "field_type": "LOGIN",
      "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
      "label": "Username"
    },
    {
      "display_order": 2,
      "field_name": "PASSWORD",
      "field_type": "PASSWORD",
      "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
      "label": "Password"
    }
    ]
    }

    ```
  </Tab>
</Tabs>

## 4. Create a Member

You can create an OAuth or non-OAuth member.

Before you can use OAuth, you must register with the financial institution, unless you're using one of our test institutions. See [Registration](/resources/oauth-guide/#registration) for more info.

<Accordion title="Create a non-OAuth member">
  For this step, you need to have already gathered the values needed for each credential from the end user. The following example uses the MX Bank institution and requires a username and a password; it sets the username to `mxuser` and the password to `password`, which are the MX Bank credentials for the test user.

  Make a request to the [Create Member endpoint](/api-reference/platform-api/reference/create-member) (`POST /users/{user_guid}/members`). The response includes the newly created `member`.

  In your request:

  * **Required** Put the `user_guid` in the path.
  * **Required** Include the credential GUIDs and their values in the `credentials` array.
  * **Recommended** Set `id` to a unique value when creating a member so you can sync between your systems and ours.
  * **Recommended** Set `metadata`.
  * **Optional** If you don't want account and transaction data, disable its aggregation, which is automatically started when a member is created. To do this, set `"skip_aggregation": true`.

  ```shell Request theme={null}
  curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
  -u 'client_id:api_key' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -d '{
      "member": {
        "credentials": [
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "mxuser"
          },
          {
            "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
            "value": "password"
          }
        ],
        "id": "member-9876",
        "institution_code": "mxbank",
        "metadata": "some metadata",
        "skip_aggregation": true
      }
    }'
  ```

  ```json Response theme={null}
  {
  "member": {
    "aggregated_at": null,
    "background_aggregation_is_disabled": false,
    "connection_status": "CREATED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": "member-9876",
    "institution_code": "mxbank",
    "is_being_aggregated": false,
    "is_managed_by_user": true,
    "is_oauth": false,
    "metadata": "some metadata",
    "name": "MX Bank",
    "successfully_aggregated_at": null,
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "user_id": "partner-2345"
  }
  }
  ```
</Accordion>

<Accordion title="Create an OAuth member">
  Make a request to the [Create Member endpoint](/api-reference/platform-api/reference/create-member) (`POST /users/{user_guid}/members`). The response includes the newly created `member`.

  In your request:

  * **Required** Put the `user_guid` in the path.
  * **Required** Set `"is_oauth": true`.
  * **Required** Set `client_redirect_url` so we can send you UI messages with the right scheme. This can be any string, but we'll use `https://mx.com` in this guide.
  * **Required** Set `institution_code`, which you got from step 2.
  * **Recommended** Set `id` to a unique value when creating a member so you can sync between your systems and ours.
  * **Recommended** Set `metadata`.
  * **In a mobile implementation only** Set `"referral_source": "APP"`. This tells MX to use the `client_redirect_url` you provided so you can get back to your app.
  * **Optional** If you don't want account and transaction data, disable its aggregation, which is automatically started when a member is created. To do this, set `"skip_aggregation": true`.

  <Warning>
    **WARNING**

    Don't set `"oauth_referral_source": "APP"` in browser implementations — this will break OAuth flows. This setting is intended for use in a mobile configuration. In typical browser environments, you can remove that field, or set it to "BROWSER".
  </Warning>

  Remember that you can't include end-user credentials in your request body when creating an OAuth member. The idea is to never share those with a third party.

  This request will return a one-time use `oauth_window_uri`.

  <Tabs>
    <Tab title="Request">
      ```shell theme={null}
      curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
      -u 'client_id:api_key' \
      -H 'Accept: application/vnd.mx.api.v2+json' \
      -H 'Content-Type: application/json' \
      -d '{
            "member": {
              "institution_code": "mxcu_oauth",
              "id": "unique_id",
              "is_oauth": true
            }
          }'
      ```
    </Tab>

    <Tab title="Response">
      ```json theme={null}
      {
        "member": {
            "aggregated_at": null,
            "connection_status": "PENDING",
            "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
            "id": "unique_id",
            "institution_code": "mx_bank_oauth",
            "is_being_aggregated": false,
            "is_managed_by_user": true,
            "is_oauth": true,
            "metadata": "Additional information",
            "name": "MX Bank (Oauth)",
            "oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
            "successfully_aggregated_at": null,
            "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
            "user_id": "unique_user_id",
        }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

<Warning>
  **WARNING**

  Do not add multiple members that connect to the same `institution` using the same `credentials` on the same `user`. This will result in a `409 Conflict` error.
</Warning>

## 5. Load the OAuth URI (if you created an OAuth member)

<Info>
  **INFO**

  If you created a non-OAuth member, you can [skip this step](#6-start-aggregating-data).
</Info>

If you created an OAuth member, the `oauth_window_uri` field in the last step returned a link that the end user will open to log into their financial institution and successfully connect their data to our API.

If you're following this guide for testing purposes, you must enter the credentials mentioned in one of the [MXCU testing guides](/resources/test-platform/mxcu/). MXCU is our recommended institution for testing OAuth flows.

## 6. Start Aggregating Data

Now we can actually begin the process of gathering AOI data.

Make a request to the [Identify Member endpoint](/api-reference/platform-api/reference/identify-member) (`POST /users/{user_guid}/members/{member_guid}/identify`). This request only starts the process of aggregating AOI data (actually reading the aggregated data comes later). The response will be a `member` object with information about the state of the AOI aggregation that just started.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/identify' \
      -H 'Accept: application/vnd.mx.api.v1+json' \
      -H 'Content-Type: application/json' \
      -u 'client_id:api_key'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "member": {
        "aggregated_at": "2023-04-10T08:50:10Z",
        "background_aggregation_is_disabled": false,
        "connection_status": "CREATED",
        "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
        "id": "member-9876",
        "institution_code": "mxbank",
        "is_being_aggregated": true,
        "is_managed_by_user": true,
        "is_oauth": false,
        "metadata": "some metadata",
        "name": "MX Bank",
        "successfully_aggregated_at": null,
        "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
        "user_id": "partner-2345"
      }
    }
    ```
  </Tab>
</Tabs>

## 7. Check the Connection Status

Check the connection status of the member to get information on the state of the connection. Important fields include `connection_status`, `is_being_aggregated`, and `successfully_aggregated_at`. The `is_being_aggregated` field will tell you whether the process is ongoing or complete. When you see `connection_status: CONNECTED` and `is_being_aggregated: false` at the same time, the process is done and you can move on to the next step. The `successfully_aggregated_at` field will give the exact time the process completed successfully, but of course will not update if the process fails.

You may need to check the connection status several times until an end state is reached.

Make a GET request to the `/users/{user_guid}/members/{member_guid}/status` endpoint. The response in the example shows a successful end state.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -u 'client_id:api_key'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "member": {
        "aggregated_at": "2020-05-07T22:01:00Z",
        "connection_status": "CONNECTED",
        "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
        "is_authenticated": true,
        "is_being_aggregated": false,
        "successfully_aggregated_at": "2020-05-07T22:01:25Z"
      }
    }
    ```
  </Tab>
</Tabs>

## 8. Deal with Multifactor Authentication

Aggregating data may trigger multifactor authentication (MFA) from the institution associated with the member. This is indicated by `"connection_status": "CHALLENGED"`.

See the section on [answering MFA challenges](/products/connectivity/overview/mfa) for more information.

For this guide, we'll assume there was no MFA and move on to the next step.

## 9. List Account Owners

The aggregation was successful and you can now list all account owners associated with the member.

Make a request to the [List Account Owners by Member endpoint](/api-reference/platform-api/reference/list-account-owners-by-member) (`GET /users/{user_guid}/members/{member_guid}/account_owners`).

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_owners' \
      -H 'Accept: application/vnd.mx.api.v1+json' \
      -u 'client_id:api_key'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "account_owners": [
        {
          "account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
          "address": "123 This Way",
          "city": "Middlesex",
          "country": "US",
          "email": "donnie@darko.co",
          "first_name": "Donnie",
          "guid": "ACO-63dc7714-6fc0-4aa2-a069-c06cdccd1af9",
          "last_name": "Darko",
          "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
          "owner_name": "Donnie Darko",
          "phone": "555-555-5555",
          "postal_code": "00000-0000",
          "state": "VA",
          "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
        }
      ],
      "pagination": {
        "current_page": 1,
        "per_page": 25,
        "total_entries": 1,
        "total_pages": 1
      }
    }
    ```
  </Tab>
</Tabs>

<Check>
  **SUCCESS**

  You've successfully returned Account Owner Identification data!
</Check>