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 Members API version: '20250224' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: members description: 'Members represent the connection between an end user and a financial institution. This institution may represent your institution or another one from which MX is aggregating data. For more info, see [Members Overview](docs.mx.com/api-reference/reference/members). ' paths: /users/{user_identifier}/members: get: description: This endpoint returns an array which contains information on every member associated with a specific user. operationId: listMembers parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/recordsPerPageMax1000' - $ref: '#/components/parameters/userIdentifier' - $ref: '#/components/parameters/useCase' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MembersResponseBody' description: OK summary: List members tags: - members post: description: This endpoint allows you to create a new member using the required parameters `institution_code`, `credentials` (if creating a non-OAuth member), and `data_request.products`. When creating a non-OAuth member, include the correct type of credential required by the financial institution and provided by the user. You can find out which credential type is required with the `/institutions/{institution_code}/credentials` endpoint. Once you successfully create a member, MX will immediately validate the provided credentials and attempt to aggregate data. A status of 200 indicates the member was created successfully, and no aggregation was requested. A status of 201 indicates the member was created, but a product within `data_request` failed to aggregate. A status of 202 indicates the member was successfully created, and standard aggregation (no `data_request`) was requested (does not indicate success or failure). operationId: createMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/userIdentifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/MemberCreateRequestBody' description: Member object to be created required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: OK '201': content: application/json: schema: $ref: '#/components/schemas/MemberResponseWithJobErrorBody' description: Created '202': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: Accepted summary: Create member tags: - members /users/{user_identifier}/members/{member_identifier}: delete: description: Accessing this endpoint will permanently delete a member. operationId: deleteMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' responses: '204': description: No Content summary: Delete member tags: - members get: description: Use this endpoint to read the attributes of a specific member. operationId: readMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: OK summary: Read member tags: - members put: description: Use this endpoint to update a members attributes. Only the credentials, id, and metadata parameters can be updated. To get a list of the required credentials for the member, use the list member credentials endpoint. operationId: updateMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/MemberUpdateRequestBody' description: Member object to be updated (While no single parameter is required, the request body can't be empty) required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: OK summary: Update member tags: - members /users/{user_identifier}/members/{member_identifier}/aggregate: post: description: Calling this endpoint initiates an aggregation event for the member. This brings in the latest account and transaction data from the connected institution. If this data has recently been updated, MX may not initiate an aggregation event. operationId: aggregateMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' responses: '202': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: Accepted summary: Aggregate member tags: - members /users/{user_identifier}/members/aggregate_all: post: description: 'This endpoint will kick off a new aggregation job for each member which belongs to the user. If you''ve set the `use_cases` field when creating the member, then the member''s use case must be set to `PFM`, otherwise a 403 will return. The response will include important information about the members'' aggregations including the `is_being_aggregated` and `connection_status` fields. Aggregations can take some time to finish; you can use the the read member or list members endpoints to track the status and completion of each individual aggregation as it progresses. ' operationId: aggregateAllMembers parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/userIdentifier' responses: '202': content: application/json: schema: $ref: '#/components/schemas/MembersResponseBody' description: Accepted summary: Aggregate all members tags: - members /users/{user_identifier}/members/{member_identifier}/challenges: get: description: Use this endpoint for information on what multi-factor authentication challenges need to be answered in order to aggregate a member. If the aggregation is not challenged, i.e., the member does not have a connection status of `CHALLENGED`, then code `204 No Content` will be returned. If the aggregation has been challenged, i.e., the member does have a connection status of `CHALLENGED`, then code `200 OK` will be returned - along with the corresponding credentials. operationId: listMemberChallenges parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/recordsPerPageMax1000' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ChallengesResponseBody' description: OK summary: List member challenges tags: - members /users/{user_identifier}/members/{member_identifier}/check_balance: post: description: This endpoint operates much like the aggregate member endpoint except that it gathers only account balance information; it does not gather any transaction data. operationId: checkBalances 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: Check balances tags: - members /users/{user_identifier}/members/{member_identifier}/credentials: get: description: This endpoint returns an array which contains information on every non-MFA credential associated with a specific member. operationId: listMemberCredentials parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/recordsPerPageMax1000' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/CredentialsResponseBody' description: OK summary: List member credentials tags: - members /users/{user_identifier}/members/{member_identifier}/identify: post: description: The identify endpoint begins an identification process for an already-existing member. operationId: identifyMember 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: Identify member tags: - members /users/{user_identifier}/members/{member_identifier}/resume: put: description: This endpoint answers the challenges needed when a member has been challenged by multi-factor authentication. operationId: resumeAggregation parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' requestBody: content: application/json: schema: $ref: '#/components/schemas/MemberResumeRequestBody' description: Member object with MFA challenge answers required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: Accepted summary: Resume aggregation tags: - members /users/{user_identifier}/members/{member_identifier}/status: get: description: This endpoint provides the status of the members most recent aggregation event. The results returned by this endpoint should determine what you do next in order to successfully aggregate a member. operationId: readMemberStatus parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemberStatusResponseBody' description: OK summary: Read member status tags: - members /users/{user_identifier}/members/{member_identifier}/verify: post: description: The verify endpoint begins a verification process for a member. operationId: verifyMember parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MemberResponseBody' description: OK summary: Verify member tags: - members components: schemas: ChallengeResponse: properties: field_name: example: Who is this guy? type: - string - 'null' guid: example: CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5 type: - string - 'null' image_data: example: Who is this guy? type: - string - 'null' image_options: items: $ref: '#/components/schemas/ImageOptionResponse' type: array label: example: Who is this guy? type: - string - 'null' options: items: $ref: '#/components/schemas/OptionResponse' type: array type: example: IMAGE_DATA type: - string - 'null' type: object CredentialRequest: properties: guid: example: CRD-27d0edb8-1d50-5b90-bcbc-be270ca42b9f type: string value: example: password type: string type: object MemberResponseWithJobError: allOf: - $ref: '#/components/schemas/MemberResponse' - type: object properties: error: type: object properties: error_type: description: The type of error that occurred. type: string example: MEMBER error_code: description: The specific error code. type: string example: REQUEST_FAILED error_message: description: A human-readable message describing the error. type: string example: There was an error attempting to process your request. The Member was created but we were unable to fulfill the data request. user_message: description: A human-readable message intended for the end user. type: string example: We're having trouble connecting right now. Please try again later. SupportedProducts: type: string enum: - account_verification - identity_verification - transactions - transaction_history - statements - investments - rewards MemberUpdateRequestBody: properties: member: $ref: '#/components/schemas/MemberUpdateRequest' type: object OptionResponse: properties: guid: example: CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5 type: - string - 'null' label: example: IMAGE_1 type: - string - 'null' value: example: image_data type: - string - 'null' type: object MembersResponseBody: properties: members: items: $ref: '#/components/schemas/MemberResponse' type: array pagination: $ref: '#/components/schemas/PaginationResponse' type: object ChallengesResponseBody: properties: challenges: items: $ref: '#/components/schemas/ChallengeResponse' type: array pagination: $ref: '#/components/schemas/PaginationResponse' type: object MemberResumeRequest: properties: challenges: items: $ref: '#/components/schemas/CredentialRequest' type: array 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 MemberUpdateRequest: properties: background_aggregation_is_disabled: description: Indicates whether background aggregation is disabled for the `member`. example: false type: boolean credentials: items: $ref: '#/components/schemas/CredentialRequest' type: array id: description: The unique partner-defined identifier for the member. example: unique_id type: string metadata: description: Additional information you can store about the `member`. example: '\"credentials_last_refreshed_at\": \"2015-10-15\' type: string 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 type: object CredentialsResponseBody: properties: credentials: items: $ref: '#/components/schemas/CredentialResponse' type: array pagination: $ref: '#/components/schemas/PaginationResponse' type: object MemberStatusResponseBody: properties: member: $ref: '#/components/schemas/MemberStatusResponse' type: object MemberCreateRequestBody: properties: client_redirect_url: description: 'This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: ''APP''`. ' example: https://{yoursite.com} type: string data_request: type: object $ref: '#/components/schemas/DataRequest' enable_app2app: example: false type: boolean description: 'This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to `true`. When set to `false`, any `oauth_window_uri` generated will **not** direct the end user to the institution''s mobile application. This setting is not persistent. This setting currently only affects Chase institutions. ' member: $ref: '#/components/schemas/MemberCreateRequest' referral_source: example: APP type: string ui_message_webview_url_scheme: description: A client-defined scheme used in OAuth redirects in WebViews. Defaults to `mx`. type: string type: object MemberResumeRequestBody: properties: member: $ref: '#/components/schemas/MemberResumeRequest' type: object MemberCreateRequest: properties: background_aggregation_is_disabled: description: Indicates whether background aggregation is disabled for the `member`. example: false type: boolean credentials: items: $ref: '#/components/schemas/CredentialRequest' type: array id: description: The unique partner-defined identifier for the member. example: unique_id type: string institution_code: description: The code identifying a financial institution. example: mxbank type: string is_oauth: description: Indicates whether the member uses OAuth to authenticate. Defaults to `false`. example: false type: boolean metadata: description: Additional information you can store about the `member`. example: '\"credentials_last_refreshed_at\": \"2015-10-15\' type: string 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 required: - credentials - institution_code 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 MemberStatusResponse: 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' challenges: items: $ref: '#/components/schemas/ChallengeResponse' type: array 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 guid: description: The unique identifier for the member. Defined by MX. example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b type: - string - 'null' has_processed_account_numbers: description: Indicates whether the member has processed account numbers. example: true type: - boolean - 'null' has_processed_accounts: description: Indicates whether the member has processed accounts. example: true type: - boolean - 'null' has_processed_transactions: description: Indicates whether the member has processed transactions. example: false type: - boolean - 'null' is_authenticated: example: false type: - boolean - 'null' is_being_aggregated: example: false type: - boolean - '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' type: object CredentialResponse: properties: display_order: example: 1 type: - integer - 'null' field_name: example: LOGIN type: - string - 'null' field_type: example: TEXT type: - string - 'null' guid: example: CRD-1ec152cd-e628-e81a-e852-d1e7104624da type: - string - 'null' label: example: Username type: - string - 'null' type: example: TEXT type: - string - 'null' type: object MemberResponseBody: properties: member: $ref: '#/components/schemas/MemberResponse' type: object ImageOptionResponse: properties: data_uri: example: data:image/png;base64,iVBORw0KGgoAAAANSUh ... more image data ... type: - string - 'null' guid: example: CRD-ce76d2e3-86bd-ec4a-ec52-eb53b5194bf5 type: - string - 'null' label: example: IMAGE_1 type: - string - 'null' value: example: image_data type: - string - 'null' type: object MemberResponseWithJobErrorBody: properties: member: $ref: '#/components/schemas/MemberResponseWithJobError' type: object DataRequest: type: object description: Contains a products array that specifies the products you want to aggregate. required: - products properties: products: description: Contains the products you want to aggregate upon a successful connection. For accepted products, see [Defining Products](/products/connectivity/overview/intro-to-unified-product-ordering/#defining-products). items: $ref: '#/components/schemas/SupportedProducts' type: array parameters: 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 useCase: description: The use case associated with the member. Valid values are `PFM` and `MONEY_MOVEMENT`. For example, you can append either `?use_case=PFM` or `?use_case=MONEY_MOVEMENT`. required: false in: query name: use_case 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 xCallback: description: The base64 encoded string defined in this header will be returned in the [Member](/resources/webhooks/member/) and [Member Data Updated](/resources/webhooks/member/#member-data-updated) webhooks. This allows you to trace user interactions and workflows initiated externally and internally in the MX Platform. Max 1024 characters. example: 813e50bd-4a7e-4517-b6bb-9eef65a68cbd in: header name: X-CALLBACK-PAYLOAD schema: type: string 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 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