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 Goals API version: '20250224' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: goals description: 'Use these endpoints to create and manage goals for a `user`. You can also reposition goals to adjust their priority levels. Every goal has a track type and a meta type. The [track type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-track-type) is the overall classification of the goal (debt, savings, retirement, or emergency fund) while the [meta type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-meta-type) is the specific classification (like college, house, vacation, and so on). ' paths: /users/{user_guid}/goals: post: tags: - goals operationId: createGoal summary: Create a goal description: Create a goal. This endpoint accepts the optional `MX-Skip-Webhook` header and `skip_webhook` parameter. parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/userGuid' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GoalRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GoalResponseBody' get: tags: - goals operationId: listGoals summary: List goals description: List all goals a user can set. parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/acceptHeader' - $ref: '#/components/parameters/userGuid' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/recordsPerPageMax1000' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GoalsResponseBody' /users/{user_guid}/goals/{goal_guid}: parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/goalGuid' - $ref: '#/components/parameters/userGuid' delete: tags: - goals operationId: deleteGoal summary: Delete a goal description: Delete a goal. parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/acceptHeader' responses: '204': description: No content get: tags: - goals operationId: readGoal summary: Read a goal description: Read a specific goal. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GoalResponseBody' put: tags: - goals operationId: updateGoal summary: Update a goal description: This endpoint updates a specific goal. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateGoalRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GoalResponseBody' /users/{user_guid}/goals/reposition: put: tags: - goals operationId: repositionGoals summary: Reposition goals description: This endpoint repositions goal priority levels. If one goal is set to a lower priority, then any other goals need to be adjusted accordingly. parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/userGuid' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RepositionRequestBody' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RepositionResponseBody' components: schemas: UpdateGoalRequestBody: properties: goal: $ref: '#/components/schemas/UpdateGoalRequest' type: object GoalsResponse: properties: account_guid: description: The unique identifier for an account. Defined by MX. example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 type: string amount: description: The amount of the `goal`. example: 4500 type: number current_amount: description: The current amount of the `goal`. example: 1500 type: number guid: description: The unique identifier for the goal. Defined by MX. example: GOL-524ca5db-a2d5-44f3-b048-16de16059024 type: string goal_type_name: description: The type of goal. example: SAVE_AMOUNT type: - string - 'null' enum: - SAVE_AMOUNT - PAYOFF meta_type_name: description: The category of the goal. example: VACATION type: string name: description: The name of the goal. example: Save for Europe type: string completed_at: description: Date and time the `goal` was completed, represented in ISO 8601 format with a timestamp. example: '2025-08-15T10:30:00+00:00' type: string has_been_spent: description: Determines if the goal has been spent. example: false type: boolean is_complete: description: Determines if the goal is complete. example: false type: boolean metadata: description: Additional information you stored about the `goal`. example: Additional information type: string position: description: The priority of the goal in relation to multiple goals. example: 3 type: integer projected_to_complete_at: description: The date on which the project was completed. example: '2022-06-14T16:03:53-00:00' type: string targeted_to_complete_at: description: Date and time the goal is to complete, represented in ISO 8601 format with timestamp. Intended for users to set their own goal completion dates. example: '2026-12-08 00:00:00.000000' type: string track_type_name: description: The track of the goal. example: SAVINGS_TRACK type: string enum: - DEBT_TRACK - SAVINGS_TRACK - RETIREMENT_TRACK - EMERGENCY_FUND_TRACK user_guid: description: The unique identifier for the the user. Defined by MX. example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c type: string RepositionRequestBody: properties: goals: items: $ref: '#/components/schemas/RepositionRequest' type: array type: object GoalsResponseBody: properties: goals: items: $ref: '#/components/schemas/GoalsResponse' 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 GoalResponseBody: properties: goal: $ref: '#/components/schemas/GoalResponse' type: object GoalRequestBody: properties: goal: $ref: '#/components/schemas/GoalRequest' type: object GoalRequest: properties: account_guid: description: The unique identifier for an account. example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 type: string amount: description: The amount of the `goal`. example: 4500 type: number goal_type_name: description: The type of goal. Can be `SAVE_AMOUNT` or `PAYOFF`. example: SAVE_AMOUNT type: - string - 'null' enum: - SAVE_AMOUNT - PAYOFF meta_type_name: description: The category of the `goal`. example: VACATION type: string name: description: The name of the `goal`. example: Save for Europe type: string completed_at: description: Date and time the `goal` was completed, represented in ISO 8601 format with a timestamp. example: '2025-08-15T10:30:00+00:00' type: string has_been_spent: description: Determines if the `goal` has been spent. example: false type: boolean is_complete: description: Determines if the `goal` is complete. example: false type: boolean metadata: description: Additional information you can store about the `goal`. example: Additional information type: string position: description: The priority of the goal in relation to multiple goals. example: 3 type: integer targeted_to_complete_at: description: Date and time the `goal` is to complete. Intended for users to set their own goal completion dates. example: '2026-12-08 00:00:00.000000' type: string required: - account_guid - amount - goal_type_name - meta_type_name - name type: object RepositionRequest: properties: guid: description: The unique identifier for the goal. Defined by MX. example: GOL-97665947-235c-b213-ca25-8cf0174774f5 type: string position: description: The priority of the goal in relation to multiple goals. example: 1 type: integer required: - guid - position UpdateGoalRequest: properties: account_guid: description: The unique identifier for an account. Defined by MX. example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 type: string amount: description: The amount of the `goal`. example: 4500 type: number goal_type_name: description: The type of goal. Can be `SAVE_AMOUNT` or `PAYOFF`. example: SAVE_AMOUNT type: - string - 'null' enum: - SAVE_AMOUNT - PAYOFF meta_type_name: description: The category of the goal. example: VACATION type: string name: description: The name of the goal. example: Save for Europe type: string completed_at: description: Date and time the `goal` was completed, represented in ISO 8601 format with a timestamp. example: '2025-08-15T10:30:00+00:00' type: string has_been_spent: description: Determines if the goal has been spent. example: false type: boolean is_complete: description: Determines if the goal is complete. example: false type: boolean metadata: description: Additional information you can store about the `goal`. example: Additional information type: string position: description: The priority of the `goal` in relation to multiple goals. example: 3 type: integer targeted_to_complete_at: description: Date and time the goal is to complete. Intended for users to set their own goal completion dates. example: '2026-12-08 00:00:00.000000' type: string type: object GoalResponse: properties: account_guid: description: The unique identifier for an account. Defined by MX. example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 type: string amount: description: The amount of the `goal`. example: 4500 type: number completed_at: description: Date and time the `goal` was completed, represented in ISO 8601 format with a timestamp. example: '2025-08-15T10:30:00+00:00' type: string current_amount: description: The current amount of the `goal`. example: 1500 type: number goal_type_name: description: The type of goal. example: SAVE_AMOUNT type: - string - 'null' enum: - SAVE_AMOUNT - PAYOFF guid: description: Unique identifier for the goal. Defined by MX. example: GOL-f223463-4355-48d0-rce7-fe2rb345617c type: string has_been_spent: description: Determines if the goal has been spent. example: false type: boolean is_complete: description: Determines if the goal is complete. example: false type: boolean metadata: description: Additional information you stored about the `goal`. example: Additional information type: string meta_type_name: description: The category of the `goal`. example: VACATION type: string name: description: The name of the `goal`. example: Save for Europe type: string position: description: The priority of the `goal` in relation to multiple goals. example: 3 type: integer projected_to_complete_at: description: Date and time the `goal` is projected to be completed. example: '2022-06-14T16:03:53-00:00' type: string targeted_to_complete_at: description: Date and time the `goal` is to complete. Intended for users to set their own goal completion dates. example: '2026-12-08 00:00:00.000000' type: string track_type_name: description: The track of the `goal`. example: SAVINGS_TRACK type: string enum: - DEBT_TRACK - SAVINGS_TRACK - RETIREMENT_TRACK - EMERGENCY_FUND_TRACK user_guid: description: The unique identifier for the the user. Defined by MX. example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c type: string RepositionResponseBody: properties: goals: items: $ref: '#/components/schemas/GoalsResponse' type: array type: object parameters: 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 goalGuid: name: goal_guid description: The unique identifier for a goal. Defined by MX. required: true in: path 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 acceptHeader: description: Specifies the media type expected in the response. in: header name: Accept required: true schema: type: string example: application/json 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 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