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

<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 statement aggregation process using API endpoints.

## API Workflow

The workflow for performing a statement aggregation is as follows:

1. Create a user.
2. Search for an institution.
3. Get the credentials required by the institution.
4. Create a member.
5. Start the statement job.
6. Poll the member's connection status.
7. Answer multifactor authentication, if necessary.
8. 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.

9. List the member's statement data.
10. Download a statement PDF.

## 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, GET `/institutions?name={string}&supports_account_statement=true`.

The example searches for MX Bank, which is [MX's institution for testing and development](/resources/test-platform). It also limits results to institutions that support statements.

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_statement=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

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

For this step, you need to have already gathered from the end user the values needed for each credential such as their username and password. The following example uses the MX Bank institution and therefore requires a username and a password; it sets the username to `mxuser` and the password to `password` which are the credentials for the test user for MX Bank.

Make a POST request to the `/users/{user_guid}/members` endpoint. The response includes the newly created `member`.

* Put the `user_guid` in the path.
* In the body, include the credential GUIDs and their values in the `credentials` array.
* In the body, set the `skip_aggregation` parameter to `true`.
  * A standard aggregation is kicked off automatically whenever a member is created unless you explicitly prevent it using `skip_aggregation`. Depending on your use case, you may or may not want that automatic agg to happen. Our example shows `skip_aggregation: true`.
* In the body, set the `id` and `metadata` fields as you see fit. This is not required, but is strongly encouraged.
* Optionally, you can disable background aggregation with the `background_aggregation_is_disabled` parameter. It defaults to `false`. In other words, background aggregation is enabled by default.

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

<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.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
      }
    }'
    ```
  </Tab>

  <Tab title="Response">
    ```json 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"
    }
    }
    ```
  </Tab>
</Tabs>

## 5. Fetch Statements

Now we can actually begin the process of gathering the end user's statements.

Make a POST request to the [fetch statements](/api-reference/platform-api/reference/fetch-statements) endpoint. This request only starts the statements process; actually reading the aggregated data comes later. The response will be a `member` object with information about the state of the statements process 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/fetch_statements' \
    -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>

## 6. Check the Connection Status

Check the connection status of the member to get information on the state of the statement aggregation. Important fields include `connection_status`, `is_being_aggregated`, and `successfully_aggregated_at`. The `is_being_aggregated` field will tell you whether the statement aggregation is ongoing or complete.

When you see `"connection_status": "CONNECTED"` and `"is_being_aggregated": false` at the same time, the statement aggregation is done and you can move on to the next step.

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

Make a request to the [Read Member Status endpoint](/api-reference/platform-api/reference/read-member-status) (`GET /users/{user_guid}/members/{member_guid}/status`). 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>

## 7. Deal with Multifactor Authentication

Aggregation-type jobs such as statements may trigger multifactor authentication (MFA) from the institution associated with the member. This is indicated by `connection_status: CHALLENGED`.

Please see the detailed section on [answering MFA challenges](/products/connectivity/overview/mfa) for more information. For this part of the guide, we'll assume there was no MFA and move on to the next step.

## 8. List the Available Statements

You can now see all the statements that are available to download. Make a note of the `uri` field on each statement object: this will be used in the next step to download a particular statement PDF.

Make a GET request to the `/users/{user_guid}/members/{member_guid}/statements` endpoint.

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

  <Tab title="Response">
    ```json theme={null}
    {
    "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
    },
    "statements": [
    {
      "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
      "content_hash": "ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981",
      "created_at": "2016-10-13T18:08:00+00:00",
      "guid": "STA-737a344b-caae-0f6e-1384-01f52e75dcb1",
      "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
      "updated_at": "2016-10-13T18:09:00+00:00",
      "uri": "uri/to/statement",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
    ]
    }
    ```
  </Tab>
</Tabs>

## 9. Download a Statement PDF

Now that you know which statements are available, pick one and use its `uri` to request a PDF of that statement.

Make a GET request `/users/{user_guid}/members/{member_guid}/statements/{statement_guid}.pdf` endpoint. Note the `.pdf` extension in the route, and the `+pdf` extension in the example's accept header.

MX will respond with the bytes of the PDF file.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/statements/STA-737a344b-caae-0f6e-1384-01f52e75dcb1' \
    -H 'Accept: application/vnd.mx.api.v1+json' \
    -u 'client_id:api_key' \
    --output statement_file_name.pdf
    ```
  </Tab>
</Tabs>