openapi: 3.0.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.


    Just getting started? See our [use case guides](/use-cases/).

    '
  title: MX Platform accounts goals API
  version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: goals
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/userGuid'
      requestBody:
        required: true
        content:
          application/vnd.mx.api.v1+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/acceptHeader'
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      responses:
        '200':
          description: OK
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/GoalsResponseBody'
  /users/{user_guid}/goals/{goal_guid}:
    parameters:
    - $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/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/userGuid'
      requestBody:
        required: true
        content:
          application/vnd.mx.api.v1+json:
            schema:
              $ref: '#/components/schemas/RepositionRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositionResponseBody'
components:
  schemas:
    GoalResponse:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500
          type: number
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T10:37:04-06:00'
          type: string
        current_amount:
          description: The current amount of the goal.
          example: 1651.27
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          type: string
        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 a partner can store on 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:
          example: Track Type Name
          type: string
        user_guid:
          description: The unique identifier for the the user. Defined by MX.
          example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
          type: string
    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: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500.5
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          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
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T10:37:04-06: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 a partner can store on 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
    UpdateGoalRequestBody:
      properties:
        goal:
          $ref: '#/components/schemas/UpdateGoalRequest'
      type: object
    GoalRequest:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500.5
          type: number
        goal_type_name:
          description: The goal type.
          example: PAYOFF
          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
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T10:37:04-06: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 a partner can store on 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
    GoalsResponseBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/GoalsResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    GoalResponseBody:
      properties:
        goal:
          $ref: '#/components/schemas/GoalResponse'
      type: object
    RepositionRequestBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/RepositionRequest'
          type: array
      type: object
    GoalRequestBody:
      properties:
        goal:
          $ref: '#/components/schemas/GoalRequest'
      type: object
    RepositionResponseBody:
      properties:
        goals:
          items:
            $ref: '#/components/schemas/GoalsResponse'
          type: array
      type: object
    GoalsResponse:
      properties:
        account_guid:
          description: Unique identifier of the account for the goal.
          example: ACT-4e431124-4a29-abf9-f059-ab232ac14dbf
          type: string
        amount:
          description: Amount of the goal.
          example: 4500
          type: number
        current_amount:
          description: The current amount of the goal.
          example: 1651.27
          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 goal type.
          example: PAYOFF
          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
        completed_at:
          description: Date and time the goal was completed.
          example: '2015-06-19T10:37:04-06: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 a partner can store on 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:
          example: '2026-12-08 00:00:00.000000'
          type: string
        track_type_name:
          example: Track Type Name
          type: string
        user_guid:
          description: The unique identifier for the the user. Defined by MX.
          example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
          type: string
  parameters:
    acceptHeader:
      description: Specifies the media type expected in the response.
      in: header
      name: Accept
      required: true
      schema:
        type: string
        example: application/vnd.mx.api.v1+json
    goalGuid:
      name: goal_guid
      description: The unique identifier for a goal. Defined by MX.
      required: true
      in: path
      schema:
        type: string
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      scheme: basic
      type: http