MX Statements API

openapi: 3.2.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: 'The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.


    ## What''s Changed?


    Several endpoints, headers, and fields changed in `v20250224`. For more on breaking changes, refer to our [versioning](/api-reference/platform-api/overview/versioning#v20250224) and [migration](/api-reference/platform-api/overview/migration) guides.


    ## Version Header

    Versions are set in the `Accept-Version` header of API requests. Version numbers correspond with the date associated with that version.  The example below uses the version `v20250224`.


    ```

    -H ''Accept: application/json''

    -H ''Accept-Version: v20250224''

    ```


    ---

    '
  title: MX Platform Statements API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: statements
  description: 'With Statements, you can retrieve a user''s monthly account statements in PDF format. This data can be used for solutions like personal financial management or risk analysis.

    '
paths:
  /users/{user_identifier}/members/{member_identifier}/fetch_statements:
    post:
      description: Use this endpoint to fetch the statements associated with a particular member.
      operationId: fetchStatements
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/memberIdentifier'
      - $ref: '#/components/parameters/userIdentifier'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponseBody'
          description: Accepted
      summary: Fetch statements
      tags:
      - statements
  /users/{user_guid}/members/{member_guid}/statements:
    get:
      description: Use this endpoint to get an array of available statements.
      operationId: listStatementsByMember
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementsResponseBody'
          description: OK
      summary: List statements by member
      tags:
      - statements
  /users/{user_guid}/members/{member_guid}/statements/{statement_guid}:
    get:
      description: Use this endpoint to read a JSON representation of the statement.
      operationId: readStatementByMember
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/statementGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementResponseBody'
          description: OK
      summary: Read statement by member
      tags:
      - statements
  /users/{user_guid}/members/{member_guid}/statements/{statement_guid}.pdf:
    get:
      description: Use this endpoint to download a specified statement PDF.
      operationId: downloadStatementPDF
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/statementGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+pdf:
              schema:
                format: binary
                type: string
          description: OK
      summary: Download statement pdf
      tags:
      - statements
components:
  parameters:
    memberGuid:
      description: The unique id for a `member`.
      example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
      in: path
      name: member_guid
      required: true
      schema:
        type: string
    memberIdentifier:
      description: Use either the member `id` you defined or the MX-defined member `guid`. See [MX-Defined GUIDs vs IDs Defined by You](/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you).
      name: member_identifier
      in: path
      required: true
      schema:
        type: string
    statementGuid:
      description: The unique id for a `statement`.
      example: STA-737a344b-caae-0f6e-1384-01f52e75dcb1
      in: path
      name: statement_guid
      required: true
      schema:
        type: string
    userGuid:
      description: The unique identifier for a `user`, beginning with the prefix `USR-`.
      example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
      in: path
      name: user_guid
      required: true
      schema:
        type: string
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    recordsPerPageMax1000:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `1000`. If the value exceeds `1000`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    userIdentifier:
      description: Use either the user `id` you defined or the MX-defined user `guid`. See [MX-Defined GUIDs vs IDs Defined by You​](/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you).
      in: path
      required: true
      name: user_identifier
      schema:
        type: string
  schemas:
    StatementResponseBody:
      properties:
        statement:
          $ref: '#/components/schemas/StatementResponse'
      type: object
    MemberResponse:
      properties:
        aggregated_at:
          description: 'The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component.


            A job will automatically be started when a member is created or its credentials are updated, unless the `skip_aggregation` parameter is used.


            Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget.


            A job can be a normal aggregation, or a premium job such as identification, verification, fetching statements, or fetching an extended transaction history.


            If a member is deleted and then re-created with the `skip_aggregation` parameter set to `true` or if it is re-created within the throttle window (typically three hours), the previous value will be returned.

            '
          example: '2016-10-13T18:07:57.000Z'
          type:
          - string
          - 'null'
        background_aggregation_is_disabled:
          description: Indicates whether background aggregation is disabled for the `member`.
          example: false
          type: boolean
        connection_status:
          description: The status of a user's connection to an institution. See [Member Connection Status](/api-reference/platform-api/reference/members#member-connection-statuses).
          example: CONNECTED
          type:
          - string
          - 'null'
          enum:
          - null
          - CREATED
          - PREVENTED
          - DENIED
          - CHALLENGED
          - REJECTED
          - LOCKED
          - CONNECTED
          - IMPEDED
          - RECONNECTED
          - DEGRADED
          - DISCONNECTED
          - DISCONTINUED
          - CLOSED
          - DELAYED
          - FAILED
          - UPDATED
          - DISABLED
          - IMPORTED
          - RESUMED
          - EXPIRED
          - IMPAIRED
          - PENDING
        connection_status_message:
          description: A human-readable message describing the connection status. See [Member Connection Status](/api-reference/platform-api/reference/members#member-connection-statuses).
          example: Connected to MX Bank
          type:
          - string
          - 'null'
        error:
          type:
          - object
          - 'null'
        guid:
          description: The unique identifier for the member. Defined by MX.
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          type:
          - string
          - 'null'
        id:
          description: The unique partner-defined identifier for the member.
          example: unique_id
          type:
          - string
          - 'null'
        institution_code:
          description: The code identifying a financial institution.
          example: mxbank
          type:
          - string
          - 'null'
        institution_guid:
          description: The unique identifier for the institution. Defined by MX.
          example: INST-12345678-90ab-cdef-1234-567890abcdef
          type: string
        is_being_aggregated:
          description: Indicates whether the member was being aggregated at the time of the request.
          example: false
          type:
          - boolean
          - 'null'
        is_managed_by_user:
          description: Indicates whether the member is managed by the user or the MX partner. Members created with the managed member feature will have this field set to `false`.
          example: false
          type:
          - boolean
          - 'null'
        is_manual:
          description: Indicates whether the transaction was manually created or belongs to a manual account.
          example: false
          type:
          - boolean
          - 'null'
        is_oauth:
          description: Indicates whether the member uses OAuth to authenticate. Defaults to `false`.
          example: false
          type:
          - boolean
          - 'null'
        metadata:
          description: Additional information you stored about the `member`.
          example: '\"credentials_last_refreshed_at\": \"2015-10-15\'
          type:
          - string
          - 'null'
        most_recent_job_detail_code:
          description: (Deprecated) This field is no longer used and will be removed at a future date.
          example: null
          type:
          - integer
          - 'null'
        most_recent_job_detail_text:
          description: (Deprecated) This field is no longer used and will be removed at a future date.
          example: null
          type:
          - boolean
          - 'null'
        most_recent_job_guid:
          description: The unique identifier for the most recent job. Defined by MX.
          example: JOB-12345678-90ab-cdef-1234-567890abcdef
          type:
          - string
          - 'null'
        name:
          description: The name of the `member`.
          example: MX Bank
          type:
          - string
          - 'null'
        needs_updated_credentials:
          description: Internal field used by MX in some circumstances. When set to `true`, MX will not attempt to aggregate the member. It will be set to `false` automatically when the member's credentials are updated.
          example: false
          type:
          - boolean
          - 'null'
        oauth_window_uri:
          description: When connecting a member using OAuth, this field will contain the URL to send the user to in order to authenticate, otherwise it will be blank.
          example: 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
          type:
          - string
          - 'null'
        successfully_aggregated_at:
          description: The date and time when the member was last successfully aggregated, represented in ISO 8601 format with a timestamp.
          example: '2016-10-13T17:57:38.000Z'
          type:
          - string
          - 'null'
        use_cases:
          type: array
          description: The use case associated with the member. Valid values are `PFM` and/or `MONEY_MOVEMENT`. Only set this if you've met with MX and have opted in to using this field.
          items:
            type: string
            enum:
            - MONEY_MOVEMENT
            - PFM
          example:
          - PFM
        user_guid:
          description: The unique identifier for the user. Defined by MX.
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          type:
          - string
          - 'null'
        user_id:
          description: The unique partner-defined identifier for the user.
          example: u-1234
          type:
          - string
          - 'null'
      type: object
    StatementsResponseBody:
      properties:
        statements:
          items:
            $ref: '#/components/schemas/StatementResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    PaginationResponse:
      properties:
        current_page:
          description: The page delivered by the current response.
          example: 1
          type: integer
        per_page:
          description: The number of records delivered with each page.
          example: 25
          type: integer
        total_entries:
          description: The total number of records available.
          example: 1
          type: integer
        total_pages:
          description: The total number of pages available.
          example: 1
          type: integer
      type: object
    MemberResponseBody:
      properties:
        member:
          $ref: '#/components/schemas/MemberResponse'
      type: object
    StatementResponse:
      properties:
        account_guid:
          description: The unique identifier for an account. Defined by MX.
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          type: string
        content_hash:
          description: An SHA-256 hash value of the statement's byte payload.
          example: ca53785b812d00ef821c3d94bfd6e5bbc0020504410589b7ea8552169f021981
          type:
          - string
          - 'null'
        created_at:
          description: The date and time the statement was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the `statement`. Defined by MX.
          example: STA-737a344b-caae-0f6e-1384-01f52e75dcb1
          type:
          - string
          - 'null'
        member_guid:
          description: The unique identifier for the member. Defined by MX.
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          type:
          - string
          - 'null'
        updated_at:
          description: 'The date and time the resource was last updated in ISO 8601 format with a timestamp.


            For categories, this field will always be `null` when `is_default` is `true`.

            '
          example: '2025-02-13T18:09:00+00:00'
          type:
          - string
          - 'null'
        uri:
          description: A URI for accessing the byte payload of the `statement`.
          example: uri/to/statement
          type:
          - string
          - 'null'
        user_guid:
          description: The unique identifier for the user. Defined by MX.
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          type:
          - string
          - 'null'
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
      description: 'The MX Platform API requires basic access authentication using your `client_id` and `api_key`. These credentials must be Base64 encoded and included in the Authorization header of each API request to ensure secure access.


        Here''s an example using curl to access `v20250224`. Replace `https://int-api.mx.com/endpoint` with the actual API endpoint you wish to access and your Base64 encoded `client_id` and `api_key`.


        ```

        curl -L -X POST `https://int-api.mx.com/endpoint'' \

        -H ''Content-Type: application/json'' \

        -H ''Accept: application/json'' \

        -H ''Accept-Version: v20250224''

        -H ''Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}''

        ```

        '
    bearerAuth:
      type: http
      scheme: bearer